Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/net/ConfigurableAddressProvider.hpp

00001 /*
00002 * ConfigurableAddressProvider.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_CONFIGURABLE_ADDRESS_PROVIDER_HPP
00017 #define COH_CONFIGURABLE_ADDRESS_PROVIDER_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/lang/IndexOutOfBoundsException.hpp"
00022 #include "coherence/net/AddressProvider.hpp"
00023 #include "coherence/run/xml/XmlElement.hpp"
00024 #include "coherence/util/List.hpp"
00025 
00026 COH_OPEN_NAMESPACE2(coherence,net)
00027 
00028 using coherence::run::xml::XmlElement;
00029 using coherence::util::List;
00030 
00031 /**
00032 * ConfigurableAddressProvider is an implementation of the AddressProvider
00033 * interface based on a static list of addresses configured in an XML element
00034 * that contains one or more items in the following format:
00035 * <pre>
00036 * &lt;socket-address&gt;
00037 * &nbsp;&nbsp;&lt;address&gt;...&lt;/address&gt;
00038 * &nbsp;&nbsp;&lt;port&gt;...&lt;/port&gt;
00039 * &lt;/socket-address&gt;
00040 * </pre>
00041 * The order of items in the configured list will be randomized to provide
00042 * basic load balancing.
00043 * <p/>
00044 * This implementation is not thread safe.
00045 *
00046 * @author gg 2008-08-18
00047 * @author gm 2008-08-25
00048 * @since Coherence 3.4
00049 */
00050 class COH_EXPORT ConfigurableAddressProvider
00051     : public class_spec<ConfigurableAddressProvider,
00052         extends<Object>,
00053         implements<AddressProvider> >
00054     {
00055     friend class factory<ConfigurableAddressProvider>;
00056 
00057     // ----- constructors ---------------------------------------------------
00058 
00059     protected:
00060         /**
00061         * Create a new ConfigurableAddressProvider instance.
00062         */
00063         ConfigurableAddressProvider();
00064 
00065         /**
00066         * Construct an instance of ConfigurableAddressProvider based on the
00067         * specified XML element.
00068         *
00069         * @param vXml   the XML element that contains the configuration info
00070         * @param fSafe  true if the provider is skips unresolved addresses
00071         */
00072         ConfigurableAddressProvider(XmlElement::View vXml, bool fSafe = true);
00073 
00074 
00075     // ----- AddressProvider interface --------------------------------------
00076 
00077     public:
00078         /**
00079         * {@inheritDoc}
00080         */
00081         virtual InetSocketAddress::View getNextAddress();
00082 
00083         /**
00084         * {@inheritDoc}
00085         */
00086         virtual void accept();
00087 
00088         /**
00089         * {@inheritDoc}
00090         */
00091         virtual void reject(Exception::Holder oheCause);
00092 
00093 
00094     // ----- helpers --------------------------------------------------------
00095 
00096     private:
00097         /**
00098         * Configure this ConfigurableAddressProvider based on the specified
00099         * XML.
00100         *
00101         * @param xmlConfig  the XML element that contains the configuration
00102         *                   info
00103         */
00104         virtual void configure(XmlElement::View vXml);
00105 
00106     protected:
00107         /**
00108         * Reset the address provider making all previously returned addresses
00109         * iterable.
00110         */
00111         virtual void reset();
00112 
00113     public:
00114         /**
00115         * Instantiate an AddressProvider configured using an XML that
00116         * conforms to the format of the "remote-addresses" element found in
00117         * the cache-config.dtd in the Coherence library:
00118         * <pre>
00119         *   &lt;!ELEMENT address-provider
00120         *     (class-name | (class-factory-name, method-name), init-params?&gt;
00121         * </pre>
00122         *
00123         * @param vXml  the XML element that contains the configuration info
00124         *
00125         * @return an instance of the corresponding AddressProvider
00126         *         implementation
00127         */
00128         static AddressProvider::Handle createAddressProvider(XmlElement::View vXml);
00129 
00130 
00131     // ----- Object methods -------------------------------------------------
00132 
00133     public:
00134         /**
00135         * {@inheritDoc}
00136         */
00137         virtual void toStream(std::ostream& out) const;
00138 
00139 
00140     // ----- inner class: AddressHolder -------------------------------------
00141 
00142     protected:
00143         /**
00144         * A stateful holder for an InetSocketAddress object.
00145         */
00146         class COH_EXPORT AddressHolder
00147             : public class_spec<AddressHolder>
00148             {
00149             friend class factory<AddressHolder>;
00150             friend class ConfigurableAddressProvider;
00151 
00152             // ----- constructors ---------------------------------------
00153 
00154             protected:
00155                 /**
00156                 * Construct an AddressHolder for the specified
00157                 * InetSocketAddress.
00158                 *
00159                 * @param sHost  the hostname
00160                 * @param nPort  the port number
00161                 */
00162                 AddressHolder(String::View vsHost, int32_t nPort);
00163 
00164                 /**
00165                 * Create a new AddressHolder instance.
00166                 */
00167                 AddressHolder();
00168 
00169             // ----- accessors ------------------------------------------
00170 
00171             public:
00172                 /**
00173                 * Obtain the underlying address.
00174                 *
00175                 * @return the underlying InetSocketAddress object
00176                 */
00177                 InetSocketAddress::View getAddress() const;
00178 
00179             protected:
00180                 /**
00181                 * Check whether or not the underlying address has been accepted.
00182                 *
00183                 * @return true iff the underlying address has not yet been
00184                 *         accepted
00185                 */
00186                 virtual bool isPending() const;
00187 
00188                 /**
00189                 * Set or clear the "pending" flag.
00190                 *
00191                 * @param fPending  the flag value
00192                 */
00193                 virtual void setPending(bool fPending);
00194 
00195                 /**
00196                 * Check whether or not the underlying address has been reported
00197                 * as unresolveable.
00198                 *
00199                 * @return true iff the underlying address has been reported as
00200                 *         unresolveable
00201                 */
00202                 virtual bool isReported() const;
00203 
00204                 /**
00205                 * Set of clear the "reported" flag.
00206                 *
00207                 * @param fReported  the flag value
00208                 */
00209                 virtual void setReported(bool fReported);
00210 
00211             // ----- data members -------------------------------------------
00212 
00213             protected:
00214                 /**
00215                 * The configured address, either hostname or IP address.
00216                 */
00217                 FinalView<String> m_vsHost;
00218 
00219                 /**
00220                 * The configured port.
00221                 */
00222                 const uint16_t m_nPort;
00223 
00224                 /**
00225                 * A flag indicating that the underlying address has been
00226                 * provided to a client, but has not yet been accepted.
00227                 */
00228                 bool m_fPending;
00229 
00230                 /**
00231                 * Specifies if this address has already been reported as
00232                 * unresolved.
00233                 */
00234                 bool m_fReported;
00235             };
00236 
00237 
00238     // ----- data members ---------------------------------------------------
00239 
00240     protected:
00241         /**
00242         * A list of AddressHolder objects.
00243         */
00244         MemberView<List> m_vListHolders;
00245 
00246         /**
00247         * Index of the last returned address.
00248         */
00249         size32_t m_iLast;
00250 
00251         /**
00252         * Specifies if the provider is only to return resolved addresses.
00253         */
00254         bool m_fSafe;
00255     };
00256 
00257 COH_CLOSE_NAMESPACE2
00258 
00259 #endif // COH_CONFIGURABLE_ADDRESS_PROVIDER_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.