00001 /* 00002 * CacheFactory.hpp 00003 * 00004 * Copyright (c) 2000, 2019, 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/io/IOException.hpp" 00022 #include "coherence/net/ConfigurableCacheFactory.hpp" 00023 #include "coherence/net/OperationalContext.hpp" 00024 #include "coherence/net/NamedCache.hpp" 00025 #include "coherence/net/Service.hpp" 00026 #include "coherence/run/xml/XmlElement.hpp" 00027 00028 #include <istream> 00029 #include <sstream> 00030 00031 COH_OPEN_NAMESPACE2(coherence,net) 00032 00033 using coherence::run::xml::XmlElement; 00034 using coherence::io::IOException; 00035 00036 00037 /** 00038 * Factory for the <b>Oracle Coherence for C++</b> %cache product. 00039 * 00040 * One of the most common functions provided by the CacheFactory is ability to 00041 * obtain an instance of a %cache. There are various %cache services and %cache 00042 * topologies that are supported by Coherence. 00043 * 00044 * To get a %cache reference use getCache() method. 00045 * 00046 * When a %cache retrieved by any of the above methods is no longer used, it is 00047 * preferable to call #releaseCache to release the associated resources. To 00048 * destroy all instances of the %cache across the cluster, use #destroyCache. 00049 */ 00050 class COH_EXPORT CacheFactory 00051 : public abstract_spec<CacheFactory> 00052 { 00053 // ----- constructors --------------------------------------------------- 00054 00055 private: 00056 /** 00057 * This constructor is blocked (private) as CacheFactory provides only 00058 * static interface and no instances may be created. 00059 */ 00060 CacheFactory(); 00061 00062 00063 // ----- caches --------------------------------------------------------- 00064 00065 public: 00066 /** 00067 * Return an instance of a %cache configured by the current 00068 * ConfigurableCacheFactory. This helper method is a simple wrapper 00069 * around the ConfigurableCacheFactory#ensureCache method. 00070 * 00071 * @param vsName %cache name (unique for a given configurable %cache 00072 * factory). If the NamedCache with the specified name 00073 * already exists, a reference to the same object will be 00074 * returned 00075 * 00076 * @return a handle to the NamedCache object 00077 */ 00078 static NamedCache::Handle getCache(String::View vsName); 00079 00080 /** 00081 * Releases and destroys the specified NamedCache. 00082 * 00083 * <b>Warning:</b> This method is used to completely destroy the 00084 * specified %cache across the cluster. All references in the entire 00085 * cluster to this %cache will be invalidated, the cached data will be 00086 * cleared, and all resources will be released. 00087 * 00088 * @param hCache the NamedCache object to be destroyed 00089 * 00090 * @see releaseCache 00091 */ 00092 static void destroyCache(NamedCache::Handle hCache); 00093 00094 /** 00095 * Release local resources associated with the specified instance of 00096 * the %cache. 00097 * 00098 * Releasing a NamedCache reference makes it no longer usable, but 00099 * does not affect the content of the %cache. In other words, all other 00100 * references to the %cache will still be valid, and the %cache data is 00101 * not affected by releasing the reference. 00102 * 00103 * The reference that is released using this method can no longer be 00104 * used; any attempt to use the reference will result in an exception. 00105 * 00106 * @param hCache the NamedCache object to be released 00107 * 00108 * @see destroyCache 00109 */ 00110 static void releaseCache(NamedCache::Handle hCache); 00111 00112 00113 // ----- Service -------------------------------------------------------- 00114 00115 public: 00116 /** 00117 * Factory method returning an instance the named service. 00118 * 00119 * @param vsName service name (unique across the cluster). If the 00120 * service with the specified name already exists, the 00121 * reference to the same service will be returned. If 00122 * the name is not specified the default service name 00123 * will be used 00124 * 00125 * @return an instance of the running service 00126 */ 00127 static Service::Handle getService(String::View vsName); 00128 00129 00130 // ----- common --------------------------------------------------------- 00131 00132 public: 00133 /** 00134 * Shutdown all clustered services. 00135 */ 00136 static void shutdown(); 00137 00138 00139 // ----- configuration -------------------------------------------------- 00140 00141 public: 00142 /** 00143 * Configure the CacheFactory and local member. 00144 * 00145 * @param vXmlCache an XML element corresponding to cache-config.dtd 00146 * @param vXmlCoherence an XML element corresponding to coherence.dtd 00147 * 00148 * @throws IllegalStateException if the factory has already been 00149 * configured 00150 * 00151 * @see loadXml to read an XmlElement from an std::istream, String, or file 00152 */ 00153 static void configure(XmlElement::View vXmlCache, 00154 XmlElement::View vXmlCoherence = NULL); 00155 00156 /** 00157 * Read an XmlElement from the supplied stream. 00158 * 00159 * This method does not configure the CacheFactory, but it can be used 00160 * to obtain a configuration which can be supplied to the configure 00161 * method. 00162 * 00163 * @param in the stream from which to read the XML element 00164 * 00165 * @return the XmlElement 00166 */ 00167 COH_INLINE static XmlElement::Handle loadXml(std::istream& in) 00168 { 00169 if (in.fail()) 00170 { 00171 COH_THROW_STREAM (IOException, 00172 "Exception occurred during parsing: The stream " 00173 << " is in a failed state."); 00174 } 00175 std::stringstream ss; 00176 char caLine[256]; 00177 00178 while (!in.eof()) 00179 { 00180 in.read(caLine, 255); 00181 caLine[in.gcount()] = 0x00; 00182 ss << caLine; 00183 } 00184 00185 return loadXml(ss.str()); 00186 } 00187 00188 /** 00189 * Read an XmlElement from the supplied string. 00190 * 00191 * This method does not configure the CacheFactory, but it can be used 00192 * to obtain a configuration which can be supplied to the configure 00193 * method. 00194 * 00195 * @param vsXml the string containing the XML 00196 * 00197 * @return the XmlElement 00198 */ 00199 static XmlElement::Handle loadXml(String::View vsXml); 00200 00201 /** 00202 * Read an XmlElement from the named file. 00203 * 00204 * This method does not configure the CacheFactory, but it can be used 00205 * to obtain a configuration which can be supplied to the configure 00206 * method. 00207 * 00208 * @param vsFile name of the file to read from relative to the current 00209 * working directory. 00210 * 00211 * @return the XmlElement 00212 */ 00213 static XmlElement::Handle loadXmlFile(String::View vsFile); 00214 00215 /** 00216 * Obtain the ConfigurableCacheFactory singleton. 00217 * 00218 * @return an instance of ConfigurableCacheFactory 00219 */ 00220 static ConfigurableCacheFactory::Handle getConfigurableCacheFactory(); 00221 00222 /** 00223 * Specify a singleton of ConfigurableCacheFactory. 00224 * 00225 * @param hFactory an instance of ConfigurableCacheFactory 00226 * @param vContext an (optional) OperationalContext 00227 */ 00228 static void setConfigurableCacheFactory( 00229 ConfigurableCacheFactory::Handle hFactory, 00230 OperationalContext::View vContext = NULL); 00231 00232 /** 00233 * Invoke the Coherence C++ command line tool. 00234 */ 00235 static void main(ObjectArray::View vasArg); 00236 }; 00237 00238 COH_CLOSE_NAMESPACE2 00239 00240 #endif // COH_CACHE_FACTORY_HPP