00001 /* 00002 * DefaultConfigurableCacheFactory.hpp 00003 * 00004 * Copyright (c) 2000, 2011, 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_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP 00017 #define COH_DEFAULT_CONFIGURABLE_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/cache/CacheLoader.hpp" 00024 #include "coherence/net/cache/CacheMap.hpp" 00025 #include "coherence/run/xml/XmlDocument.hpp" 00026 #include "coherence/run/xml/XmlElement.hpp" 00027 #include "coherence/util/Map.hpp" 00028 00029 COH_OPEN_NAMESPACE2(coherence,net) 00030 00031 using coherence::net::cache::CacheLoader; 00032 using coherence::net::cache::CacheMap; 00033 using coherence::run::xml::XmlDocument; 00034 using coherence::run::xml::XmlElement; 00035 using coherence::util::Map; 00036 00037 00038 /** 00039 * DefaultConfigurableCacheFactory provides a facility to access caches 00040 * declared in a "cache-config.dtd" compliant configuration file. 00041 * 00042 * This class is designed to be easily extendable with a collection of factory 00043 * methods allowing subclasses to customize it by overriding any subset of 00044 * %cache instantiation routines or even allowing addition of custom schemes. 00045 * 00046 * There are various ways of using this factory: 00047 * <pre> 00048 * ConfigurableCacheFactory::Handle factory = 00049 * DefaultConfigurableCacheFactory::create(sPath); 00050 * ... 00051 * NamedCache::Handle cacheOne = factory->ensureCache("one"); 00052 * NamedCache::Handle cacheTwo = factory->ensureCache("two"); 00053 * </pre> 00054 * This approach allows an easy customization by extending the 00055 * DefaultConfigurableCacheFactory and changing the instantiation line: 00056 * <pre> 00057 * ConfigurableCacheFactory::Handle factory = 00058 * CustomConfigurableCacheFactory::create(); 00059 * ... 00060 * </pre> 00061 * 00062 * Another option is using the static version of the "ensureCache" call: 00063 * <pre> 00064 * NamedCache cacheOne = CacheFactory::getCache("one"); 00065 * NamedCache cacheTwo = CacheFactory::getCache("two"); 00066 * </pre> 00067 * which uses an instance of ConfigurableCacheFactory obtained by 00068 * {@link CacheFactory#getConfigurableCacheFactory()}. 00069 * 00070 * @see CacheFactory#getCache(String::View) 00071 * 00072 * @author mf 2008.04.08 00073 */ 00074 class COH_EXPORT DefaultConfigurableCacheFactory 00075 : public class_spec<DefaultConfigurableCacheFactory, 00076 extends<Object>, 00077 implements<ConfigurableCacheFactory> > 00078 { 00079 friend class factory<DefaultConfigurableCacheFactory>; 00080 00081 // ----- constructors --------------------------------------------------- 00082 00083 protected: 00084 /** 00085 * Create a new %cache factory. 00086 * 00087 * @param vsFile the name of the configuration file to load relative 00088 * to the current working directory, or NULL for an 00089 * unconfigured CacheFactory 00090 */ 00091 DefaultConfigurableCacheFactory(String::View vsFile = String::null_string); 00092 00093 00094 // ----- typedef: SchemeType -------------------------------------------- 00095 00096 public: 00097 /** 00098 * Scheme types. 00099 */ 00100 typedef enum 00101 { 00102 scheme_local, 00103 scheme_class, 00104 scheme_near, 00105 scheme_remote_cache, 00106 scheme_remote_invocation, 00107 scheme_unknown 00108 } SchemeType; 00109 00110 00111 // ----- nested class: CacheInfo ---------------------------------------- 00112 00113 public: 00114 /** 00115 * CacheInfo is a placeholder for cache attributes retrieved during 00116 * parsing the corresponding cache mapping element. 00117 */ 00118 class CacheInfo 00119 : public class_spec<CacheInfo> 00120 { 00121 friend class factory<CacheInfo>; 00122 00123 // ----- constructors --------------------------------------- 00124 00125 protected: 00126 /** 00127 * Create a new CacheInfo. 00128 * 00129 * @param vsCacheName the cache name 00130 * @param vsSchemeName the corresponding scheme name 00131 * @param vMapAttribute the corresponding map of attributes 00132 */ 00133 CacheInfo(String::View vsCacheName, String::View vsSchemeName, 00134 Map::View vMapAttribute); 00135 00136 // ----- accessors ------------------------------------------ 00137 00138 public: 00139 /** 00140 * Obtain the cache name. 00141 * 00142 * @return the cache name 00143 */ 00144 virtual String::View getCacheName() const; 00145 00146 /** 00147 * Obtain the scheme name. 00148 * 00149 * @return the scheme name 00150 */ 00151 virtual String::View getSchemeName() const; 00152 00153 /** 00154 * Obtain the attribute map. 00155 * 00156 * @return the attribute map 00157 */ 00158 virtual Map::View getAttributes() const; 00159 00160 // ----- helpers -------------------------------------------- 00161 00162 public: 00163 /** 00164 * Find and replace the attributes names in "{}" format with 00165 * the corresponding values for this cache info. 00166 * <p> 00167 * Note: the content of the specified XmlElement could be 00168 * modified, so the caller is supposed to clone the passed in 00169 * XML if necessary. 00170 * 00171 * @param hXml the XmlElement to replace "{}" attributes at 00172 */ 00173 virtual void replaceAttributes(XmlElement::Handle hXml) const; 00174 00175 /** 00176 * Generate a synthetic CacheInfo for a cache that has a name 00177 * suffixed with the specified string. 00178 * 00179 * @param vsSuffix the cache name suffix 00180 * 00181 * @return the "cloned" synthetic CacheInfo 00182 */ 00183 virtual CacheInfo::Handle getSyntheticInfo(String::View vsSuffix) const; 00184 00185 00186 // ----- data fields ---------------------------------------- 00187 00188 protected: 00189 /** 00190 * The cache name. 00191 */ 00192 FinalView<String> m_vsCacheName; 00193 00194 /** 00195 * The corresponding scheme name. 00196 */ 00197 FinalView<String> m_vsSchemeName; 00198 00199 /** 00200 * Map of scheme attributes. 00201 */ 00202 FinalView<Map> m_vMapAttribute; 00203 }; 00204 00205 00206 // ----- DefaultConfigurableCacheFactory interface ---------------------- 00207 00208 public: 00209 /** 00210 * In the configuration XML find a "cache-mapping" element associated with a 00211 * given cache name. 00212 * 00213 * @param vsCacheName the value of the "cache-name" element to look for 00214 * 00215 * @return a CacheInfo object associated with a given cache name 00216 */ 00217 virtual CacheInfo::View findSchemeMapping(String::View vsCacheName); 00218 00219 /** 00220 * In the configuration XML find a "scheme" element associated with a 00221 * given cache and resolve it (recursively) using the "scheme-ref" 00222 * elements. The returned XML is always a clone of the actual configuration 00223 * and could be safely modified. 00224 * 00225 * @param vInfo the cache info 00226 * 00227 * @return a resolved "scheme" element associated with a given cache 00228 */ 00229 virtual XmlElement::View resolveScheme(CacheInfo::View vInfo); 00230 00231 /** 00232 * Translate the scheme name into the scheme type. Valid scheme types are 00233 * any of the SCHEME_* constants. 00234 * 00235 * @param vsScheme the scheme name 00236 * 00237 * @return the scheme type 00238 */ 00239 virtual SchemeType translateSchemeType(String::View vsScheme); 00240 00241 /** 00242 * Create an Object using "class-scheme" element. 00243 * 00244 * @param vInfo the cache info 00245 * @param vXmlScheme "class-scheme" element. 00246 * 00247 * @return a newly instantiated Object 00248 */ 00249 virtual Object::Handle instantiateAny(CacheInfo::View vInfo, 00250 XmlElement::View vXmlScheme); 00251 00252 00253 protected: 00254 /** 00255 * Resolve the specified "XYZ-scheme" by retrieving the base element 00256 * refered to by the "scheme-ref" element, resolving it recursively, 00257 * and combining it with the specified overrides and cache specific attributes. 00258 * 00259 * @param vXmlScheme a scheme element to resolve 00260 * @param vInfo the cache info (optional) 00261 * @param fChild if true, the actual cache scheme is the only "xyz-scheme" 00262 * child of the specified xmlScheme element; 00263 * otherwise it's the xmlScheme element itself 00264 * @param fRequired if true, the child scheme must be present; false otherwise 00265 * 00266 * @return a "scheme" element associated with a given cache name; NULL if 00267 * the child is missing and is not required 00268 */ 00269 virtual XmlElement::Handle resolveScheme(XmlElement::View vXmlScheme, 00270 CacheInfo::View vInfo, bool fChild, bool fRequired); 00271 00272 /** 00273 * In the configuration XML find a "scheme" element associated with a 00274 * given cache name. 00275 * 00276 * @param vsSchemeName the value of the "cache-name" element to look for 00277 * 00278 * @return a "scheme" element associated with a given cache name 00279 */ 00280 virtual XmlElement::Handle findScheme(String::View vsSchemeName); 00281 00282 /** 00283 * In the configuration XML find a "scheme" element associated with a 00284 * given service name. 00285 * 00286 * @param vsServiceName the value of the "service-name" element to look for 00287 * 00288 * @return a "scheme" element associated with a given service name 00289 */ 00290 virtual XmlElement::Handle findServiceScheme(String::View vsServiceName); 00291 00292 /** 00293 * Ensures a cache for given scheme. 00294 * 00295 * @param vInfo the cache info 00296 * @param vXmlScheme the corresponding scheme 00297 * 00298 * @return a named cache created according to the description 00299 * in the configuration 00300 */ 00301 virtual NamedCache::Handle configureCache(CacheInfo::View vInfo, 00302 XmlElement::View vXmlScheme); 00303 00304 /** 00305 * Release a cache managed by this factory, optionally destroying it. 00306 * 00307 * @param cache the cache to release 00308 * @param fDestroy true to destroy the cache as well 00309 */ 00310 virtual void releaseCache(NamedCache::Handle hCache, bool fDestroy); 00311 00312 /** 00313 * Ensure the service for the specified scheme. 00314 * 00315 * @param vXmlScheme the scheme 00316 * 00317 * @return running Service corresponding to the scheme 00318 */ 00319 virtual Service::Handle configureService(XmlElement::View vXmlScheme); 00320 00321 /** 00322 * Configures a backing map according to the scheme. 00323 * 00324 * @param vInfo the cache info 00325 * @param vXmlScheme the scheme element for cache configuration 00326 * 00327 * @return a backing map configured according to the scheme 00328 */ 00329 virtual CacheMap::Handle configureBackingMap(CacheInfo::View vInfo, 00330 XmlElement::View vXmlScheme); 00331 00332 /** 00333 * Instantiate a custom (class-name) based cache based on the supplied 00334 * configuration and scheme. 00335 * 00336 * @param vInfo the CacheInfo 00337 * @param vXmlScheme the cache scheme 00338 * 00339 * @return a new NamedCache instance. 00340 */ 00341 virtual NamedCache::Handle instantiateCustomCache(CacheInfo::View vInfo, 00342 XmlElement::View vXmlScheme); 00343 00344 /** 00345 * Instantiate a local cache based on the supplied configuration and 00346 * scheme. 00347 * 00348 * @param vInfo the CacheInfo 00349 * @param vXmlScheme the cache scheme 00350 * 00351 * @return a new NamedCache instance. 00352 */ 00353 virtual NamedCache::Handle instantiateLocalCache(CacheInfo::View vInfo, 00354 XmlElement::View vXmlScheme); 00355 00356 /** 00357 * Instantiate a remote cache based on the supplied configuration and 00358 * scheme. 00359 * 00360 * @param vInfo the CacheInfo 00361 * @param vXmlScheme the cache scheme 00362 * 00363 * @return a new NamedCache instance. 00364 */ 00365 virtual NamedCache::Handle ensureRemoteCache(CacheInfo::View vInfo, 00366 XmlElement::View vXmlScheme); 00367 00368 /** 00369 * Instantiate a near cache based on the supplied configuration and 00370 * scheme. 00371 * 00372 * @param vInfo the CacheInfo 00373 * @param vXmlScheme the cache scheme 00374 * 00375 * @return a new NamedCache instance. 00376 */ 00377 virtual NamedCache::Handle ensureNearCache(CacheInfo::View vInfo, 00378 XmlElement::View vXmlScheme); 00379 00380 /** 00381 * Create a backing Map using the "class-scheme" element. 00382 * This method is a thin wrapper around instantiateAny. 00383 * 00384 * @param vInfo the cache info 00385 * @param vXmlScheme "class-scheme" element. 00386 * 00387 * @return a newly instantiated Map 00388 */ 00389 virtual Map::Handle instantiateMap(CacheInfo::View vInfo, 00390 XmlElement::View vXmlScheme); 00391 00392 /** 00393 * Create a CacheLoader or CacheStore using the "cachestore-scheme" element. 00394 * 00395 * @param vInfo the cache info 00396 * @param vXmlStore "cachestore-scheme" element for the store or loader 00397 * 00398 * @return a newly instantiated CacheStore or CacheLoader 00399 */ 00400 virtual CacheLoader::Handle instantiateCacheStore(CacheInfo::View vInfo, 00401 XmlElement::View vXmlStore); 00402 00403 00404 // ----- ConfigurableCacheFactory interface ----------------------------- 00405 00406 public: 00407 /** 00408 * {@inheritDoc} 00409 */ 00410 virtual NamedCache::Handle ensureCache(String::View vsCacheName); 00411 00412 /** 00413 * {@inheritDoc} 00414 */ 00415 virtual void destroyCache(NamedCache::Handle hCache); 00416 00417 /** 00418 * {@inheritDoc} 00419 */ 00420 virtual void releaseCache(NamedCache::Handle hCache); 00421 00422 /** 00423 * {@inheritDoc} 00424 */ 00425 virtual Service::Handle ensureService(String::View vsServiceName); 00426 00427 /** 00428 * {@inheritDoc} 00429 */ 00430 virtual void shutdown(); 00431 00432 00433 // ----- XmlConfigurable interface -------------------------------------- 00434 00435 public: 00436 /** 00437 * {@inheritDoc} 00438 */ 00439 virtual XmlElement::View getConfig() const; 00440 00441 /** 00442 * {@inheritDoc} 00443 */ 00444 virtual void setConfig(XmlElement::View vXml); 00445 00446 00447 // ----- accessors ------------------------------------------------------ 00448 00449 public: 00450 /** 00451 * Return the OperationalContext for this cache factory. 00452 * 00453 * @return the OperationalContext for this cache factory 00454 * 00455 * @since Coherence 3.7 00456 */ 00457 virtual OperationalContext::View ensureOperationalContext(); 00458 00459 /** 00460 * Set the OperationalContext for this cache factory. 00461 * 00462 * @param vContext the OperationalContext for this cache factory 00463 * 00464 * @throws IllegalStateException if an OperationalContext was already 00465 * set 00466 * 00467 * @since Coherence 3.7 00468 */ 00469 virtual void setOperationalContext(OperationalContext::View vContext); 00470 00471 /** 00472 * The default XML configuration used when one isn't explicitly passed 00473 * in the constructor for this class. 00474 * 00475 * @return the default XML configuration 00476 * 00477 * @since Coherence 3.7 00478 */ 00479 static XmlDocument::Handle getDefaultCacheConfig(); 00480 00481 00482 protected: 00483 /** 00484 * Return the cache reference store for this cache factory. 00485 * 00486 * @return the cache reference store for this cache factory 00487 * 00488 * @since Coherence 3.7 00489 */ 00490 virtual Object::Handle ensureStoreCache(); 00491 00492 /** 00493 * Return the service reference store for this cache factory. 00494 * 00495 * @return the service reference store for this cache factory 00496 * 00497 * @since Coherence 3.7 00498 */ 00499 virtual Object::Handle ensureStoreService(); 00500 00501 00502 // ----- data members --------------------------------------------------- 00503 00504 protected: 00505 /** 00506 * Operational Context for all Services associated with this factory. 00507 */ 00508 MemberView<OperationalContext> m_vContext; 00509 00510 /** 00511 * XmlElement that corresponds to used XML cache configuration. 00512 */ 00513 MemberView<XmlElement> m_vXmlConfig; 00514 00515 /** 00516 * Store that holds cache references by name and optionally, 00517 * if configured, Subject. 00518 */ 00519 MemberHandle<Object> m_hStoreCache; 00520 00521 /** 00522 * Store that holds service references by name and optionally, 00523 * if configured, Subject. 00524 */ 00525 MemberHandle<Object> m_hStoreService; 00526 00527 /** 00528 * The parent ThreadGroup for all Services associated with this factory. 00529 */ 00530 FinalHandle<ThreadGroup> m_hThreadGroup; 00531 }; 00532 00533 COH_CLOSE_NAMESPACE2 00534 00535 #endif // COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP