00001 /* 00002 * DefaultConfigurableCacheFactory.hpp 00003 * 00004 * Copyright (c) 2000, 2009, 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/cache/CacheLoader.hpp" 00023 #include "coherence/net/cache/CacheMap.hpp" 00024 #include "coherence/run/xml/XmlElement.hpp" 00025 #include "coherence/util/Map.hpp" 00026 00027 00028 COH_OPEN_NAMESPACE2(coherence,net) 00029 00030 using coherence::net::cache::CacheLoader; 00031 using coherence::net::cache::CacheMap; 00032 using coherence::run::xml::XmlElement; 00033 using coherence::util::Map; 00034 00035 00036 /** 00037 * DefaultConfigurableCacheFactory provides a facility to access caches 00038 * declared in a "cache-config.dtd" compliant configuration file. 00039 * 00040 * This class is designed to be easily extendable with a collection of factory 00041 * methods allowing subclasses to customize it by overriding any subset of 00042 * %cache instantiation routines or even allowing addition of custom schemes. 00043 * 00044 * There are various ways of using this factory: 00045 * <pre> 00046 * ConfigurableCacheFactory::Handle factory = 00047 * DefaultConfigurableCacheFactory::create(sPath); 00048 * ... 00049 * NamedCache::Handle cacheOne = factory->ensureCache("one"); 00050 * NamedCache::Handle cacheTwo = factory->ensureCache("two"); 00051 * </pre> 00052 * This approach allows an easy customization by extending the 00053 * DefaultConfigurableCacheFactory and changing the instantiation line: 00054 * <pre> 00055 * ConfigurableCacheFactory::Handle factory = 00056 * CustomConfigurableCacheFactory::create(); 00057 * ... 00058 * </pre> 00059 * 00060 * Another option is using the static version of the "ensureCache" call: 00061 * <pre> 00062 * NamedCache cacheOne = CacheFactory::getCache("one"); 00063 * NamedCache cacheTwo = CacheFactory::getCache("two"); 00064 * </pre> 00065 * which uses an instance of ConfigurableCacheFactory obtained by 00066 * {@link CacheFactory#getConfigurableCacheFactory()}. 00067 * 00068 * @see CacheFactory#getCache(String::View) 00069 * 00070 * @author mf 2008.04.08 00071 */ 00072 class COH_EXPORT DefaultConfigurableCacheFactory 00073 : public class_spec<DefaultConfigurableCacheFactory, 00074 extends<Object>, 00075 implements<ConfigurableCacheFactory> > 00076 { 00077 friend class factory<DefaultConfigurableCacheFactory>; 00078 00079 // ----- constructors --------------------------------------------------- 00080 00081 protected: 00082 /** 00083 * Create a new %cache factory. 00084 * 00085 * @param vsFile the name of the configuration file to load relative 00086 * to the current working directory, or NULL for an 00087 * unconfigured CacheFactory 00088 */ 00089 DefaultConfigurableCacheFactory(String::View vsFile = String::NULL_STRING); 00090 00091 00092 // ----- typedef: SchemeType -------------------------------------------- 00093 00094 public: 00095 /** 00096 * Scheme types. 00097 */ 00098 typedef enum 00099 { 00100 SCHEME_LOCAL, 00101 SCHEME_CLASS, 00102 SCHEME_NEAR, 00103 SCHEME_REMOTE_CACHE, 00104 SCHEME_REMOTE_INVOCATION, 00105 SCHEME_UNKNOWN 00106 } SchemeType; 00107 00108 00109 // ----- typedef: ProductEdition ---------------------------------------- 00110 00111 public: 00112 /** 00113 * Extend editions. 00114 */ 00115 typedef enum 00116 { 00117 EDITION_DC = 0, 00118 EDITION_RTC = 1 00119 } ProductEdition; 00120 00121 00122 // ----- nested class: CacheInfo ---------------------------------------- 00123 00124 public: 00125 /** 00126 * CacheInfo is a placeholder for cache attributes retrieved during 00127 * parsing the corresponding cache mapping element. 00128 */ 00129 class CacheInfo 00130 : public class_spec<CacheInfo> 00131 { 00132 friend class factory<CacheInfo>; 00133 00134 // ----- constructors --------------------------------------- 00135 00136 protected: 00137 /** 00138 * Create a new CacheInfo. 00139 * 00140 * @param vsCacheName the cache name 00141 * @param vsSchemeName the corresponding scheme name 00142 * @param vMapAttribute the corresponding map of attributes 00143 */ 00144 CacheInfo(String::View vsCacheName, String::View vsSchemeName, 00145 Map::View vMapAttribute); 00146 00147 // ----- accessors ------------------------------------------ 00148 00149 public: 00150 /** 00151 * Obtain the cache name. 00152 * 00153 * @return the cache name 00154 */ 00155 virtual String::View getCacheName() const; 00156 00157 /** 00158 * Obtain the scheme name. 00159 * 00160 * @return the scheme name 00161 */ 00162 virtual String::View getSchemeName() const; 00163 00164 /** 00165 * Obtain the attribute map. 00166 * 00167 * @return the attribute map 00168 */ 00169 virtual Map::View getAttributes() const; 00170 00171 // ----- helpers -------------------------------------------- 00172 00173 public: 00174 /** 00175 * Find and replace the attributes names in "{}" format with 00176 * the corresponding values for this cache info. 00177 * <p> 00178 * Note: the content of the specified XmlElement could be 00179 * modified, so the caller is supposed to clone the passed in 00180 * XML if necessary. 00181 * 00182 * @param hXml the XmlElement to replace "{}" attributes at 00183 */ 00184 virtual void replaceAttributes(XmlElement::Handle hXml) const; 00185 00186 /** 00187 * Generate a synthetic CacheInfo for a cache that has a name 00188 * suffixed with the specified string. 00189 * 00190 * @param vsSuffix the cache name suffix 00191 * 00192 * @return the "cloned" synthetic CacheInfo 00193 */ 00194 virtual CacheInfo::Handle getSyntheticInfo(String::View vsSuffix) const; 00195 00196 00197 // ----- data fields ---------------------------------------- 00198 00199 protected: 00200 /** 00201 * The cache name. 00202 */ 00203 FinalView<String> m_vsCacheName; 00204 00205 /** 00206 * The corresponding scheme name. 00207 */ 00208 FinalView<String> m_vsSchemeName; 00209 00210 /** 00211 * Map of scheme attributes. 00212 */ 00213 FinalView<Map> m_vMapAttribute; 00214 }; 00215 00216 00217 // ----- DefaultConfigurableCacheFactory interface ---------------------- 00218 00219 public: 00220 /** 00221 * In the configuration XML find a "cache-mapping" element associated with a 00222 * given cache name. 00223 * 00224 * @param vsCacheName the value of the "cache-name" element to look for 00225 * 00226 * @return a CacheInfo object associated with a given cache name 00227 */ 00228 virtual CacheInfo::View findSchemeMapping(String::View vsCacheName); 00229 00230 /** 00231 * In the configuration XML find a "scheme" element associated with a 00232 * given cache and resolve it (recursively) using the "scheme-ref" 00233 * elements. The returned XML is always a clone of the actual configuration 00234 * and could be safely modified. 00235 * 00236 * @param vInfo the cache info 00237 * 00238 * @return a resolved "scheme" element associated with a given cache 00239 */ 00240 virtual XmlElement::View resolveScheme(CacheInfo::View vInfo); 00241 00242 /** 00243 * Translate the scheme name into the scheme type. Valid scheme types are 00244 * any of the SCHEME_* constants. 00245 * 00246 * @param vsScheme the scheme name 00247 * 00248 * @return the scheme type 00249 */ 00250 virtual SchemeType translateSchemeType(String::View vsScheme); 00251 00252 /** 00253 * Create an Object using "class-scheme" element. 00254 * 00255 * @param vInfo the cache info 00256 * @param vXmlScheme "class-scheme" element. 00257 * 00258 * @return a newly instantiated Object 00259 */ 00260 virtual Object::Handle instantiateAny(CacheInfo::View vInfo, 00261 XmlElement::View vXmlScheme); 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 custom (class-name) based cache based on the supplied 00344 * configuration and scheme. 00345 * 00346 * @param vInfo the CacheInfo 00347 * @param vXmlScheme the cache scheme 00348 * 00349 * @return a new NamedCache instance. 00350 */ 00351 virtual NamedCache::Handle instantiateCustomCache(CacheInfo::View vInfo, 00352 XmlElement::View vXmlScheme); 00353 00354 /** 00355 * Instantiate a local cache based on the supplied configuration and 00356 * scheme. 00357 * 00358 * @param vInfo the CacheInfo 00359 * @param vXmlScheme the cache scheme 00360 * 00361 * @return a new NamedCache instance. 00362 */ 00363 virtual NamedCache::Handle instantiateLocalCache(CacheInfo::View vInfo, 00364 XmlElement::View vXmlScheme); 00365 00366 /** 00367 * Instantiate a remote cache based on the supplied configuration and 00368 * scheme. 00369 * 00370 * @param vInfo the CacheInfo 00371 * @param vXmlScheme the cache scheme 00372 * 00373 * @return a new NamedCache instance. 00374 */ 00375 virtual NamedCache::Handle ensureRemoteCache(CacheInfo::View vInfo, 00376 XmlElement::View vXmlScheme); 00377 00378 /** 00379 * Instantiate a near cache based on the supplied configuration and 00380 * scheme. 00381 * 00382 * @param vInfo the CacheInfo 00383 * @param vXmlScheme the cache scheme 00384 * 00385 * @return a new NamedCache instance. 00386 */ 00387 virtual NamedCache::Handle ensureNearCache(CacheInfo::View vInfo, 00388 XmlElement::View vXmlScheme); 00389 00390 /** 00391 * Create a backing Map using the "class-scheme" element. 00392 * This method is a thin wrapper around instantiateAny. 00393 * 00394 * @param vInfo the cache info 00395 * @param vXmlScheme "class-scheme" element. 00396 * 00397 * @return a newly instantiated Map 00398 */ 00399 virtual Map::Handle instantiateMap(CacheInfo::View vInfo, 00400 XmlElement::View vXmlScheme); 00401 00402 /** 00403 * Create a CacheLoader or CacheStore using the "cachestore-scheme" element. 00404 * 00405 * @param vInfo the cache info 00406 * @param vXmlStore "cachestore-scheme" element for the store or loader 00407 * 00408 * @return a newly instantiated CacheStore or CacheLoader 00409 */ 00410 virtual CacheLoader::Handle instantiateCacheStore(CacheInfo::View vInfo, 00411 XmlElement::View vXmlStore); 00412 00413 00414 // ----- ConfigurableCacheFactory interface ----------------------------- 00415 00416 public: 00417 /** 00418 * {@inheritDoc} 00419 */ 00420 virtual NamedCache::Handle ensureCache(String::View vsCacheName); 00421 00422 /** 00423 * {@inheritDoc} 00424 */ 00425 virtual void destroyCache(NamedCache::Handle hCache); 00426 00427 /** 00428 * {@inheritDoc} 00429 */ 00430 virtual void releaseCache(NamedCache::Handle hCache); 00431 00432 /** 00433 * {@inheritDoc} 00434 */ 00435 virtual Service::Handle ensureService(String::View vsServiceName); 00436 00437 /** 00438 * {@inheritDoc} 00439 */ 00440 virtual int32_t getEdition() const; 00441 00442 /** 00443 * {@inheritDoc} 00444 */ 00445 virtual void setEdition(int32_t nEdition); 00446 00447 /** 00448 * {@inheritDoc} 00449 */ 00450 virtual Member::View getLocalMember() const; 00451 00452 /** 00453 * {@inheritDoc} 00454 */ 00455 virtual void setLocalMember(Member::View vMemberLocal); 00456 00457 /** 00458 * {@inheritDoc} 00459 */ 00460 virtual Map::View getFilterConfigMap() const; 00461 00462 /** 00463 * {@inheritDoc} 00464 */ 00465 virtual void setFilterConfigMap(Map::View vMapFilterConfig); 00466 00467 /** 00468 * {@inheritDoc} 00469 */ 00470 virtual void shutdown(); 00471 00472 00473 // ----- XmlConfigurable interface -------------------------------------- 00474 00475 public: 00476 /** 00477 * {@inheritDoc} 00478 */ 00479 virtual XmlElement::View getConfig() const; 00480 00481 /** 00482 * {@inheritDoc} 00483 */ 00484 virtual void setConfig(XmlElement::View vXml); 00485 00486 00487 // ----- data members --------------------------------------------------- 00488 00489 protected: 00490 /** 00491 * XmlElement that corresponds to used XML cache configuration 00492 */ 00493 MemberView<XmlElement> m_vXmlConfig; 00494 00495 /** 00496 * Filter map config. 00497 */ 00498 MemberView<Map> m_vMapFilterConfig; 00499 00500 /** 00501 * The local member. 00502 */ 00503 MemberView<Member> m_vMemberLocal; 00504 00505 /** 00506 * Map of cache names to NamedCache instances. 00507 */ 00508 FinalHandle<Map> m_hMapCache; 00509 00510 /** 00511 * Map of service names to Service instances. 00512 */ 00513 FinalHandle<Map> m_hMapService; 00514 00515 /** 00516 * The configured edition. 00517 */ 00518 int32_t m_nEdition; 00519 }; 00520 00521 COH_CLOSE_NAMESPACE2 00522 00523 #endif // COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP