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