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