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

coherence/net/ConfigurableAddressProvider.hpp

/*
* ConfigurableAddressProvider.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_CONFIGURABLE_ADDRESS_PROVIDER_HPP
#define COH_CONFIGURABLE_ADDRESS_PROVIDER_HPP

#include "coherence/lang.ns"

#include "coherence/lang/IndexOutOfBoundsException.hpp"
#include "coherence/net/AddressProvider.hpp"
#include "coherence/run/xml/XmlElement.hpp"
#include "coherence/util/List.hpp"

COH_OPEN_NAMESPACE2(coherence,net)

using coherence::run::xml::XmlElement;
using coherence::util::List;

/**
* ConfigurableAddressProvider is an implementation of the AddressProvider
* interface based on a static list of addresses configured in an XML element
* that contains one or more items in the following format:
* <pre>
* &lt;socket-address&gt;
* &nbsp;&nbsp;&lt;address&gt;...&lt;/address&gt;
* &nbsp;&nbsp;&lt;port&gt;...&lt;/port&gt;
* &lt;/socket-address&gt;
* </pre>
* The order of items in the configured list will be randomized to provide
* basic load balancing.
* <p/>
* This implementation is not thread safe.
*
* @author gg 2008-08-18
* @author gm 2008-08-25
* @since Coherence 3.4
*/
class COH_EXPORT ConfigurableAddressProvider
    : public class_spec<ConfigurableAddressProvider,
        extends<Object>,
        implements<AddressProvider> >
    {
    friend class factory<ConfigurableAddressProvider>;

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

    protected:
        /**
        * Create a new ConfigurableAddressProvider instance.
        */
        ConfigurableAddressProvider();

        /**
        * Construct an instance of ConfigurableAddressProvider based on the
        * specified XML element.
        *
        * @param vXml   the XML element that contains the configuration info
        * @param fSafe  true if the provider is skips unresolved addresses
        */
        ConfigurableAddressProvider(XmlElement::View vXml, bool fSafe = true);


    // ----- AddressProvider interface --------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual InetSocketAddress::View getNextAddress();

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

        /**
        * {@inheritDoc}
        */
        virtual void reject(Exception::Holder oheCause);


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

    protected:
        /**
        * Configure this ConfigurableAddressProvider based on the specified
        * XML.
        *
        * @param xmlConfig  the XML element that contains the configuration
        *                   info
        */
        virtual void configure(XmlElement::View vXml);

        /**
        * Make all addresses iterable, starting at the first address.
        */
        virtual void reset();

        /**
        * Make all addresses iterable, starting at the index after the specified
        * one.
        *
        * @param iLast  the index of the last address returned
        */
        virtual void reset(size32_t iLast);

        /**
        * Sort the holders in the order to be returned by the getNextAddress
        * method.  This implementation randomizes the holder lists for
        * simple load balancing.
        *
        * @param list  the original list retrieved from the configuration
        *
        * @return the re-ordered list
        */
        virtual List::Handle sortHolders(List::Handle hList);

    public:
        /**
        * Instantiate an AddressProvider configured using an XML that
        * conforms to the format of the "remote-addresses" element found in
        * the cache-config.dtd in the Coherence library:
        * <pre>
        *   &lt;!ELEMENT address-provider
        *     (class-name | (class-factory-name, method-name), init-params?&gt;
        * </pre>
        *
        * @param vXml  the XML element that contains the configuration info
        *
        * @return an instance of the corresponding AddressProvider
        *         implementation
        */
        static AddressProvider::Handle createAddressProvider(XmlElement::View vXml);


    // ----- Object methods -------------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual void toStream(std::ostream& out) const;


    // ----- inner class: AddressHolder -------------------------------------

    protected:
        /**
        * A stateful holder for an InetSocketAddress object.
        */
        class COH_EXPORT AddressHolder
            : public class_spec<AddressHolder>
            {
            friend class factory<AddressHolder>;
            friend class ConfigurableAddressProvider;

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

            protected:
                /**
                * Construct an AddressHolder for the specified
                * InetSocketAddress.
                *
                * @param sHost  the hostname
                * @param nPort  the port number
                */
                AddressHolder(String::View vsHost, int32_t nPort);

                /**
                * Create a new AddressHolder instance.
                */
                AddressHolder();

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

            public:
                /**
                * Obtain the underlying address.
                *
                * @return the underlying InetSocketAddress object
                */
                InetSocketAddress::View getAddress() const;

            protected:
                /**
                * Check whether or not the underlying address has been accepted.
                *
                * @return true iff the underlying address has not yet been
                *         accepted
                */
                virtual bool isPending() const;

                /**
                * Set or clear the "pending" flag.
                *
                * @param fPending  the flag value
                */
                virtual void setPending(bool fPending);

                /**
                * Check whether or not the underlying address has been reported
                * as unresolveable.
                *
                * @return true iff the underlying address has been reported as
                *         unresolveable
                */
                virtual bool isReported() const;

                /**
                * Set of clear the "reported" flag.
                *
                * @param fReported  the flag value
                */
                virtual void setReported(bool fReported);

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

            protected:
                /**
                * The configured address, either hostname or IP address.
                */
                FinalView<String> m_vsHost;

                /**
                * The configured port.
                */
                const uint16_t m_nPort;

                /**
                * A flag indicating that the underlying address has been
                * provided to a client, but has not yet been accepted.
                */
                bool m_fPending;

                /**
                * Specifies if this address has already been reported as
                * unresolved.
                */
                bool m_fReported;
            };


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

    protected:
        /**
        * A list of AddressHolder objects.
        */
        MemberView<List> m_vListHolders;

        /**
        * Index of the last returned address.
        */
        size32_t m_iLast;

        /**
        * Specifies if the provider is only to return resolved addresses.
        */
        bool m_fSafe;


    // ----- constants ------------------------------------------------------

    public:
        /**
        * The largest possible value of type size32_t.
        */
        static const size32_t npos = size32_t(-1);
    };

COH_CLOSE_NAMESPACE2

#endif // COH_CONFIGURABLE_ADDRESS_PROVIDER_HPP

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