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