Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

coherence/net/DefaultConfigurableCacheFactory.hpp

/*
* DefaultConfigurableCacheFactory.hpp
*
* Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP
#define COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP

#include "coherence/lang.ns"

#include "coherence/net/ConfigurableCacheFactory.hpp"
#include "coherence/net/cache/CacheLoader.hpp"
#include "coherence/net/cache/CacheMap.hpp"
#include "coherence/run/xml/XmlElement.hpp"
#include "coherence/util/Map.hpp"


COH_OPEN_NAMESPACE2(coherence,net)

using coherence::net::cache::CacheLoader;
using coherence::net::cache::CacheMap;
using coherence::run::xml::XmlElement;
using coherence::util::Map;


/**
* DefaultConfigurableCacheFactory provides a facility to access caches
* declared in a "cache-config.dtd" compliant configuration file.
*
* This class is designed to be easily extendable with a collection of factory
* methods allowing subclasses to customize it by overriding any subset of
* %cache instantiation routines or even allowing addition of custom schemes.
*
* There are various ways of using this factory:
* <pre>
*   ConfigurableCacheFactory::Handle factory =
*       DefaultConfigurableCacheFactory::create(sPath);
*   ...
*   NamedCache::Handle cacheOne = factory->ensureCache("one");
*   NamedCache::Handle cacheTwo = factory->ensureCache("two");
* </pre>
* This approach allows an easy customization by extending the
* DefaultConfigurableCacheFactory and changing the instantiation line:
* <pre>
*   ConfigurableCacheFactory::Handle factory =
*       CustomConfigurableCacheFactory::create();
*   ...
* </pre>
*
* Another option is using the static version of the "ensureCache" call:
* <pre>
*   NamedCache cacheOne = CacheFactory::getCache("one");
*   NamedCache cacheTwo = CacheFactory::getCache("two");
* </pre>
* which uses an instance of ConfigurableCacheFactory obtained by
* {@link CacheFactory#getConfigurableCacheFactory()}.
*
* @see CacheFactory#getCache(String::View)
*
* @author mf  2008.04.08
*/
class COH_EXPORT DefaultConfigurableCacheFactory
    : public class_spec<DefaultConfigurableCacheFactory,
        extends<Object>,
        implements<ConfigurableCacheFactory> >
    {
    friend class factory<DefaultConfigurableCacheFactory>;

    // ----- constructors ---------------------------------------------------

    protected:
        /**
        * Create a new %cache factory.
        *
        * @param vsFile  the name of the configuration file to load relative
        *                to the current working directory, or NULL for an
        *                unconfigured CacheFactory
        */
        DefaultConfigurableCacheFactory(String::View vsFile = String::NULL_STRING);


    // ----- typedef: SchemeType --------------------------------------------

    public:
        /**
        * Scheme types.
        */
        typedef enum
            {
            SCHEME_LOCAL,
            SCHEME_CLASS,
            SCHEME_NEAR,
            SCHEME_REMOTE_CACHE,
            SCHEME_REMOTE_INVOCATION,
            SCHEME_UNKNOWN
            } SchemeType;


    // ----- typedef: ProductEdition ----------------------------------------

    public:
        /**
        * Extend editions.
        */
        typedef enum
            {
            EDITION_DC  = 0,
            EDITION_RTC = 1
            } ProductEdition;


    // ----- nested class: CacheInfo ----------------------------------------

    public:
        /**
        * CacheInfo is a placeholder for cache attributes retrieved during
        * parsing the corresponding cache mapping element.
        */
        class CacheInfo
            : public class_spec<CacheInfo>
            {
            friend class factory<CacheInfo>;

            // ----- constructors ---------------------------------------

            protected:
                /**
                * Create a new CacheInfo.
                *
                * @param vsCacheName    the cache name
                * @param vsSchemeName   the corresponding scheme name
                * @param vMapAttribute  the corresponding map of attributes
                */
                CacheInfo(String::View vsCacheName, String::View vsSchemeName,
                        Map::View vMapAttribute);

            // ----- accessors ------------------------------------------

            public:
                /**
                * Obtain the cache name.
                *
                * @return  the cache name
                */
                virtual String::View getCacheName() const;

                /**
                * Obtain the scheme name.
                *
                * @return  the scheme name
                */
                virtual String::View getSchemeName() const;

                /**
                * Obtain the attribute map.
                *
                * @return  the attribute map
                */
                virtual Map::View getAttributes() const;

            // ----- helpers --------------------------------------------

            public:
                /**
                * Find and replace the attributes names in "{}" format with
                * the corresponding values for this cache info.
                * <p>
                * Note: the content of the specified XmlElement could be
                * modified, so the caller is supposed to clone the passed in
                * XML if necessary.
                *
                * @param hXml  the XmlElement to replace "{}" attributes at
                */
                virtual void replaceAttributes(XmlElement::Handle hXml) const;

                /**
                * Generate a synthetic CacheInfo for a cache that has a name
                * suffixed with the specified string.
                *
                * @param vsSuffix  the cache name suffix
                *
                * @return  the "cloned" synthetic CacheInfo
                */
                virtual CacheInfo::Handle getSyntheticInfo(String::View vsSuffix) const;


            // ----- data fields ----------------------------------------

            protected:
                /**
                * The cache name.
                */
                FinalView<String> m_vsCacheName;

                /**
                * The corresponding scheme name.
                */
                FinalView<String> m_vsSchemeName;

                /**
                * Map of scheme attributes.
                */
                FinalView<Map> m_vMapAttribute;
            };


    // ----- DefaultConfigurableCacheFactory interface ----------------------

    public:
        /**
        * In the configuration XML find a "cache-mapping" element associated with a
        * given cache name.
        *
        * @param vsCacheName  the value of the "cache-name" element to look for
        *
        * @return a CacheInfo object associated with a given cache name
        */
        virtual CacheInfo::View findSchemeMapping(String::View vsCacheName);

        /**
        * In the configuration XML find a "scheme" element associated with a
        * given cache and resolve it (recursively) using the "scheme-ref"
        * elements. The returned XML is always a clone of the actual configuration
        * and could be safely modified.
        *
        * @param vInfo  the cache info
        *
        * @return a resolved "scheme" element associated with a given cache
        */
        virtual XmlElement::View resolveScheme(CacheInfo::View vInfo);

        /**
        * Translate the scheme name into the scheme type. Valid scheme types are
        * any of the SCHEME_* constants.
        *
        * @param vsScheme  the scheme name
        *
        * @return the scheme type
        */
        virtual SchemeType translateSchemeType(String::View vsScheme);

        /**
        * Create an Object using "class-scheme" element.
        *
        * @param vInfo       the cache info
        * @param vXmlScheme  "class-scheme" element.
        *
        * @return a newly instantiated Object
        */
        virtual Object::Handle instantiateAny(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

    protected:
        /**
        * Resolve the specified "XYZ-scheme" by retrieving the base element
        * refered to by the "scheme-ref" element, resolving it recursively,
        * and combining it with the specified overrides and cache specific attributes.
        *
        * @param vXmlScheme  a scheme element to resolve
        * @param vInfo       the cache info (optional)
        * @param fChild      if true, the actual cache scheme is the only "xyz-scheme"
        *                    child of the specified xmlScheme element;
        *                    otherwise it's the xmlScheme element itself
        * @param fRequired  if true, the child scheme must be present; false otherwise
        *
        * @return a "scheme" element associated with a given cache name; NULL if
        *         the child is missing and is not required
        */
        virtual XmlElement::Handle resolveScheme(XmlElement::View vXmlScheme,
                CacheInfo::View vInfo, bool fChild, bool fRequired);

        /**
        * In the configuration XML find a "scheme" element associated with a
        * given cache name.
        *
        * @param vsSchemeName  the value of the "cache-name" element to look for
        *
        * @return a "scheme" element associated with a given cache name
        */
        virtual XmlElement::Handle findScheme(String::View vsSchemeName);

        /**
        * In the configuration XML find a "scheme" element associated with a
        * given service name.
        *
        * @param vsServiceName  the value of the "service-name" element to look for
        *
        * @return a "scheme" element associated with a given service name
        */
        virtual XmlElement::Handle findServiceScheme(String::View vsServiceName);

        /**
        * Ensures a cache for given scheme.
        *
        * @param vInfo       the cache info
        * @param vXmlScheme  the corresponding scheme
        *
        * @return a named cache created according to the description
        *         in the configuration
        */
        virtual NamedCache::Handle configureCache(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Release a cache managed by this factory, optionally destroying it.
        *
        * @param cache     the cache to release
        * @param fDestroy  true to destroy the cache as well
        */
        virtual void releaseCache(NamedCache::Handle hCache, bool fDestroy);

        /**
        * Ensure the service for the specified scheme.
        *
        * @param vXmlScheme  the scheme
        *
        * @return running Service corresponding to the scheme
        */
        virtual Service::Handle configureService(XmlElement::View vXmlScheme);

        /**
        * Configures a backing map according to the scheme.
        *
        * @param vInfo         the cache info
        * @param vXmlScheme    the scheme element for cache configuration
        *
        * @return a backing map configured according to the scheme
        */
        virtual CacheMap::Handle configureBackingMap(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Instantiate a custom (class-name) based cache based on the supplied
        * configuration and scheme.
        *
        * @param vInfo       the CacheInfo
        * @param vXmlScheme  the cache scheme
        *
        * @return a new NamedCache instance.
        */
        virtual NamedCache::Handle instantiateCustomCache(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Instantiate a local cache based on the supplied configuration and
        * scheme.
        *
        * @param vInfo       the CacheInfo
        * @param vXmlScheme  the cache scheme
        *
        * @return a new NamedCache instance.
        */
        virtual NamedCache::Handle instantiateLocalCache(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Instantiate a remote cache based on the supplied configuration and
        * scheme.
        *
        * @param vInfo       the CacheInfo
        * @param vXmlScheme  the cache scheme
        *
        * @return a new NamedCache instance.
        */
        virtual NamedCache::Handle ensureRemoteCache(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Instantiate a near cache based on the supplied configuration and
        * scheme.
        *
        * @param vInfo       the CacheInfo
        * @param vXmlScheme  the cache scheme
        *
        * @return a new NamedCache instance.
        */
        virtual NamedCache::Handle ensureNearCache(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Create a backing Map using the "class-scheme" element.
        * This method is a thin wrapper around instantiateAny.
        *
        * @param vInfo       the cache info
        * @param vXmlScheme  "class-scheme" element.
        *
        * @return a newly instantiated Map
        */
        virtual Map::Handle instantiateMap(CacheInfo::View vInfo,
                XmlElement::View vXmlScheme);

        /**
        * Create a CacheLoader or CacheStore using the "cachestore-scheme" element.
        *
        * @param vInfo      the cache info
        * @param vXmlStore  "cachestore-scheme" element for the store or loader
        *
        * @return a newly instantiated CacheStore or CacheLoader
        */
        virtual CacheLoader::Handle instantiateCacheStore(CacheInfo::View vInfo,
                    XmlElement::View vXmlStore);


    // ----- ConfigurableCacheFactory interface -----------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual NamedCache::Handle ensureCache(String::View vsCacheName);

        /**
        * {@inheritDoc}
        */
        virtual void destroyCache(NamedCache::Handle hCache);

        /**
        * {@inheritDoc}
        */
        virtual void releaseCache(NamedCache::Handle hCache);

        /**
        * {@inheritDoc}
        */
        virtual Service::Handle ensureService(String::View vsServiceName);

        /**
        * {@inheritDoc}
        */
        virtual int32_t getEdition() const;

        /**
        * {@inheritDoc}
        */
        virtual void setEdition(int32_t nEdition);

        /**
        * {@inheritDoc}
        */
        virtual Member::View getLocalMember() const;

        /**
        * {@inheritDoc}
        */
        virtual void setLocalMember(Member::View vMemberLocal);

        /**
        * {@inheritDoc}
        */
        virtual Map::View getFilterConfigMap() const;

        /**
        * {@inheritDoc}
        */
        virtual void setFilterConfigMap(Map::View vMapFilterConfig);

        /**
        * {@inheritDoc}
        */
        virtual void shutdown();

        /**
        * {@inheritDoc}
        */
        virtual IdentityAsserter::Handle getIdentityAsserter() const;

        /**
        * {@inheritDoc}
        */
        virtual void setIdentityAsserter(IdentityAsserter::Handle hAsserter);

        /**
        * {@inheritDoc}
        */
        virtual IdentityTransformer::Handle getIdentityTransformer() const;

        /**
        * {@inheritDoc}
        */
        virtual void setIdentityTransformer(IdentityTransformer::Handle hTransformer);


    // ----- XmlConfigurable interface --------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual XmlElement::View getConfig() const;

        /**
        * {@inheritDoc}
        */
        virtual void setConfig(XmlElement::View vXml);


    // ----- data members ---------------------------------------------------

    protected:
        /**
        * XmlElement that corresponds to used XML cache configuration
        */
        MemberView<XmlElement> m_vXmlConfig;

        /**
        * Filter map config.
        */
        MemberView<Map> m_vMapFilterConfig;

        /**
        * The local member.
        */
        MemberView<Member> m_vMemberLocal;

        /**
        * Store that holds cache references by name and optionally,
        * if configured, Subject.
        */
        FinalHandle<Object> m_hStoreCache;

        /**
        * Store that holds service references by name and optionally,
        * if configured, Subject.
        */
        FinalHandle<Object> m_hStoreService;

        /**
        * The configured edition.
        */
        int32_t m_nEdition;

        /**
        * The parent ThreadGroup for all Services associated with this factory.
        */
        FinalHandle<ThreadGroup> m_hThreadGroup;

        /**
        * The IdentityAsserter available for Services.
        */
        mutable MemberHandle<IdentityAsserter> m_hAsserter;

        /**
        * The IdentityTransformer available for Services.
        */
        mutable MemberHandle<IdentityTransformer> m_hTransformer;
    };

COH_CLOSE_NAMESPACE2

#endif // COH_DEFAULT_CONFIGURABLE_CACHE_FACTORY_HPP

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