Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/net/DefaultConfigurableCacheFactory.hpp

    00001 /*
    00002 * DefaultConfigurableCacheFactory.hpp
    00003 *
    00004 * Copyright (c) 2000, 2010, 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         * {@inheritDoc}
    00474         */
    00475         virtual IdentityAsserter::Handle getIdentityAsserter() const;
    00476
    00477         /**
    00478         * {@inheritDoc}
    00479         */
    00480         virtual void setIdentityAsserter(IdentityAsserter::Handle hAsserter);
    00481
    00482         /**
    00483         * {@inheritDoc}
    00484         */
    00485         virtual IdentityTransformer::Handle getIdentityTransformer() const;
    00486
    00487         /**
    00488         * {@inheritDoc}
    00489         */
    00490         virtual void setIdentityTransformer(IdentityTransformer::Handle hTransformer);
    00491
    00492
    00493     // ----- XmlConfigurable interface --------------------------------------
    00494
    00495     public:
    00496         /**
    00497         * {@inheritDoc}
    00498         */
    00499         virtual XmlElement::View getConfig() const;
    00500
    00501         /**
    00502         * {@inheritDoc}
    00503         */
    00504         virtual void setConfig(XmlElement::View vXml);
    00505
    00506
    00507     // ----- data members ---------------------------------------------------
    00508
    00509     protected:
    00510         /**
    00511         * XmlElement that corresponds to used XML cache configuration
    00512         */
    00513         MemberView<XmlElement> m_vXmlConfig;
    00514
    00515         /**
    00516         * Filter map config.
    00517         */
    00518         MemberView<Map> m_vMapFilterConfig;
    00519
    00520         /**
    00521         * The local member.
    00522         */
    00523         MemberView<Member> m_vMemberLocal;
    00524
    00525         /**
    00526         * Store that holds cache references by name and optionally,
    00527         * if configured, Subject.
    00528         */
    00529         FinalHandle<Object> m_hStoreCache;
    00530
    00531         /**
    00532         * Store that holds service references by name and optionally,
    00533         * if configured, Subject.
    00534         */
    00535         FinalHandle<Object> m_hStoreService;
    00536
    00537         /**
    00538         * The configured edition.
    00539         */
    00540         int32_t m_nEdition;
    00541
    00542         /**
    00543         * The parent ThreadGroup for all Services associated with this factory.
    00544         */
    00545         FinalHandle<ThreadGroup> m_hThreadGroup;
    00546
    00547         /**
    00548         * The IdentityAsserter available for Services.
    00549         */
    00550         mutable MemberHandle<IdentityAsserter> m_hAsserter;
    00551
    00552         /**
    00553         * The IdentityTransformer available for Services.
    00554         */
    00555         mutable MemberHandle<IdentityTransformer> m_hTransformer;
    00556     };
    00557
    00558 COH_CLOSE_NAMESPACE2
    00559
    00560 #endif // COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.