00001 /* 00002 * CacheFactory.hpp 00003 * 00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_CACHE_FACTORY_HPP 00017 #define COH_CACHE_FACTORY_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/net/ConfigurableCacheFactory.hpp" 00022 #include "coherence/net/NamedCache.hpp" 00023 #include "coherence/net/Service.hpp" 00024 #include "coherence/run/xml/XmlElement.hpp" 00025 00026 #include <iostream> 00027 00028 COH_OPEN_NAMESPACE2(coherence,net) 00029 00030 using coherence::run::xml::XmlElement; 00031 00032 00033 /** 00034 * Factory for the <b>Oracle Coherence for C++</b> %cache product. 00035 * 00036 * One of the most common functions provided by the CacheFactory is ability to 00037 * obtain an instance of a %cache. There are various %cache services and %cache 00038 * topologies that are supported by Coherence. 00039 * 00040 * To get a %cache reference use getCache() method. 00041 * 00042 * When a %cache retrieved by any of the above methods is no longer used, it is 00043 * preferrable to call #releaseCache to release the associated resources. To 00044 * destroy all instances of the %cache across the cluster, use #destroyCache. 00045 */ 00046 class COH_EXPORT CacheFactory 00047 : public abstract_spec<CacheFactory> 00048 { 00049 // ----- constructors --------------------------------------------------- 00050 00051 private: 00052 /** 00053 * This constructor is blocked (private) as CacheFactory provides only 00054 * static interface and no instances may be created. 00055 */ 00056 CacheFactory(); 00057 00058 00059 // ----- caches --------------------------------------------------------- 00060 00061 public: 00062 /** 00063 * Return an instance of a %cache configured by the current 00064 * ConfigurableCacheFactory. This helper method is a simple wrapper 00065 * around the ConfigurableCacheFactory#ensureCache method. 00066 * 00067 * @param vsName %cache name (unique for a given configurable %cache 00068 * factory). If the NamedCache with the specified name 00069 * already exists, a reference to the same object will be 00070 * returned 00071 * 00072 * @return a handle to the NamedCache object 00073 */ 00074 static NamedCache::Handle getCache(String::View vsName); 00075 00076 /** 00077 * Releases and destroys the specified NamedCache. 00078 * 00079 * <b>Warning:</b> This method is used to completely destroy the 00080 * specified %cache across the cluster. All references in the entire 00081 * cluster to this %cache will be invalidated, the cached data will be 00082 * cleared, and all resources will be released. 00083 * 00084 * @param hCache the NamedCache object to be destroyed 00085 * 00086 * @see releaseCache 00087 */ 00088 static void destroyCache(NamedCache::Handle hCache); 00089 00090 /** 00091 * Release local resources associated with the specified instance of 00092 * the %cache. 00093 * 00094 * Releasing a NamedCache reference makes it no longer usable, but 00095 * does not affect the content of the %cache. In other words, all other 00096 * references to the %cache will still be valid, and the %cache data is 00097 * not affected by releasing the reference. 00098 * 00099 * The reference that is released using this method can no longer be 00100 * used; any attempt to use the reference will result in an exception. 00101 * 00102 * @param hCache the NamedCache object to be released 00103 * 00104 * @see destroyCache 00105 */ 00106 static void releaseCache(NamedCache::Handle hCache); 00107 00108 00109 // ----- Service -------------------------------------------------------- 00110 00111 public: 00112 /** 00113 * Factory method returning an instance the named service. 00114 * 00115 * @param vsName service name (unique across the cluster). If the 00116 * service with the specified name already exists, the 00117 * reference to the same service will be returned. If 00118 * the name is not specified the default service name 00119 * will be used 00120 * 00121 * @return an instance of the running service 00122 */ 00123 static Service::Handle getService(String::View vsName); 00124 00125 00126 // ----- common --------------------------------------------------------- 00127 00128 public: 00129 /** 00130 * Shutdown all clustered services. 00131 */ 00132 static void shutdown(); 00133 00134 00135 // ----- configuration -------------------------------------------------- 00136 00137 public: 00138 /** 00139 * Configure the CacheFactory and local member. 00140 * 00141 * @param vXmlCache an XML element corresponding to cache-config.dtd 00142 * @param vXmlCoherence an XML element corresponding to coherence.dtd 00143 * 00144 * @throws IllegalStateException if the factory has already been 00145 * configured 00146 * 00147 * @see loadXml to read an XmlElement from an std::istream or file 00148 */ 00149 static void configure(XmlElement::View vXmlCache, 00150 XmlElement::View vXmlCoherence = NULL); 00151 00152 /** 00153 * Read an XmlElement from the supplied stream. 00154 * 00155 * This method does not configure the CacheFactory, but it can be used 00156 * to obtain a configuration which can be supplied to the configure 00157 * method. 00158 * 00159 * @param in the stream from which to read the XML element 00160 * 00161 * @return the XmlElement 00162 */ 00163 static XmlElement::Handle loadXml(std::istream& in); 00164 00165 /** 00166 * Read an XmlElement from the named file. 00167 * 00168 * This method does not configure the CacheFactory, but it can be used 00169 * to obtain a configuration which can be supplied to the configure 00170 * method. 00171 * 00172 * @param vsFile name of the file to read from relative to the current 00173 * working directory. 00174 * 00175 * @return the XmlElement 00176 */ 00177 static XmlElement::Handle loadXmlFile(String::View vsFile); 00178 00179 /** 00180 * Obtain the ConfigurableCacheFactory singleton. 00181 * 00182 * @return an instance of ConfigurableCacheFactory 00183 */ 00184 static ConfigurableCacheFactory::Handle getConfigurableCacheFactory(); 00185 00186 /** 00187 * Specify a singleton of ConfigurableCacheFactory. 00188 * 00189 * @param hFactory an instance of ConfigurableCacheFactory 00190 */ 00191 static void setConfigurableCacheFactory(ConfigurableCacheFactory::Handle hFactory); 00192 00193 /** 00194 * Indicates if Subject scope is enabled by the operational 00195 * configuration. 00196 */ 00197 static bool isSubjectScoped(); 00198 00199 /** 00200 * Invoke the Coherence C++ command line tool. 00201 */ 00202 static void main(ObjectArray::View vasArg); 00203 }; 00204 00205 COH_CLOSE_NAMESPACE2 00206 00207 #endif // COH_CACHE_FACTORY_HPP