Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/util/extractor/PofExtractor.hpp

00001 /*
00002 * PofExtractor.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_POF_EXTRACTOR_HPP
00017 #define COH_POF_EXTRACTOR_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/io/pof/PofConstants.hpp"
00022 #include "coherence/io/pof/PofContext.hpp"
00023 #include "coherence/io/pof/PofHelper.hpp"
00024 #include "coherence/io/pof/PofReader.hpp"
00025 #include "coherence/io/pof/PofWriter.hpp"
00026 #include "coherence/io/pof/PortableObject.hpp"
00027 #include "coherence/io/pof/reflect/PofNavigator.hpp"
00028 #include "coherence/util/extractor/AbstractExtractor.hpp"
00029 
00030 #include <typeinfo>
00031 
00032 COH_OPEN_NAMESPACE3(coherence,util,extractor)
00033 
00034 using coherence::io::pof::PofConstants;
00035 using coherence::io::pof::PofContext;
00036 using coherence::io::pof::PofHelper;
00037 using coherence::io::pof::PofReader;
00038 using coherence::io::pof::PofWriter;
00039 using coherence::io::pof::reflect::PofNavigator;
00040 
00041 
00042 /**
00043 * POF-based ValueExtractor implementation.
00044 * PofExtractor takes advantage of POF's indexed state to extract part of an
00045 * object without needing to deserialize the entire object.
00046 * <p/>
00047 * POF uses a compact form in the serialized value when possible. For example,
00048 * some numeric values are represented as special POF intrinsic types in which
00049 * the type implies the value. As a result, POF requires the receiver of a
00050 * value to have implicit knowledge of the type. PofExtractor uses the type
00051 * supplied in the constructor as the source of the type information. If the
00052 * type is void, PofExtractor will infer the type from the serialized state.
00053 * See {@link PofConstants} for the list of the POF types.
00054 * <p/>
00055 * In C++ the type is expressed by type_info which is obtained from the typeid
00056 * operator.
00057 *
00058 * Example where extracted value is float64_t:
00059 * <pre><code>
00060 *     ValueExtractor::Handle hExtractor =
00061 *         PofExtractor::create(typeid(float64_t), 0);
00062 * </code></pre>
00063 *
00064 * Example where extracted value should be inferred from the serialized state:
00065 * <pre><code>
00066 *     ValueExtractor::Handle hExtractor =
00067 *         PofExtractor::create(typeid(void), 0);
00068 * </code></pre>
00069 *
00070 * @author as/gm 2009.04.02
00071 * @since Coherence 3.5
00072 */
00073 class COH_EXPORT PofExtractor
00074     : public class_spec<PofExtractor,
00075         extends<AbstractExtractor>,
00076         implements<PortableObject> >
00077     {
00078     friend class factory<PofExtractor>;
00079 
00080     // ----- constructors ---------------------------------------------------
00081 
00082     protected:
00083         /**
00084         * Default constructor (necessary for the PortableObject interface).
00085         */
00086         PofExtractor();
00087 
00088         /**
00089         * Constructs a PofExtractor based on a property index.
00090         * <p/>
00091         * This constructor is equivalent to:
00092         * <pre>
00093         *   PofExtractor::View vExtractor =
00094         *       PofExtractor::create(info, SimplePofPath::create(iProp), VALUE);
00095         * </pre>
00096         *
00097         * @param info  the required type of the extracted value or void if
00098         *              the type is to be inferred from the serialized state
00099         * @param iProp  property index
00100         */
00101         PofExtractor(const std::type_info& info, int32_t iProp);
00102 
00103         /**
00104         * Constructs a PofExtractor based on a property path and the entry
00105         * extraction target.
00106         *
00107         * @param info        the required type of the extracted value or void
00108         *                    if the type is to be inferred from the serialized
00109         *                    state
00110         * @param vNavigator  POF navigator
00111         * @param nTarget     one of the {@link #VALUE} or {@link #KEY} values
00112         */
00113         PofExtractor(const std::type_info& info, PofNavigator::View vNavigator,
00114                 int32_t nTarget = VALUE);
00115 
00116 
00117     // ----- AbstractExtractor methods ---------------------------------------
00118 
00119     public:
00120         /**
00121         * Extract the value from the passed Entry object. The returned value
00122         * should follow the conventions outlined in the {@link #extract}
00123         * method.
00124         * <p/>
00125         * This method will always throw a
00126         * {@link UnsupportedOperationException} if called directly by the
00127         * C++ client application, as its execution is only meaningful within
00128         * the cluster.
00129         * <p/>
00130         * It is expected that this extractor will only be used against
00131         * POF-encoded binary entries within a remote partitioned cache.
00132         *
00133         * @param entry  an Entry object to extract a desired value from
00134         *
00135         * @throws UnsupportedOperationException  always, as it is expected
00136         *         that this extractor will only be executed within the
00137         *         cluster.
00138         *
00139         * @return the extracted value
00140         */
00141         virtual Object::Holder extractFromEntry(Map::Entry::Holder ohEntry) const;
00142 
00143 
00144     // ----- PortableObject interface ---------------------------------------
00145 
00146     public:
00147         /**
00148         * {@inheritDoc}
00149         */
00150         virtual void readExternal(PofReader::Handle hIn);
00151 
00152         /**
00153         * {@inheritDoc}
00154         */
00155         virtual void writeExternal(PofWriter::Handle hOut) const;
00156 
00157 
00158     // ----- Object interface -----------------------------------------------
00159 
00160     public:
00161         /**
00162         * Compare the PofExtractor with another object to determine equality.
00163         * Two PofExtractor objects are considered equal iff their paths are
00164         * equal and they have the same target (key or value).
00165         *
00166         * @return true iff this PofExtractor and the passed object are
00167         *              equivalent
00168         */
00169         virtual bool equals(Object::View v) const;
00170 
00171         /**
00172         * Determine a hash value for the PofExtractor object according to the
00173         * general {@link Object#hashCode()} contract.
00174         *
00175         * @return an integer hash value for this PofExtractor object
00176         */
00177         virtual size32_t hashCode() const;
00178 
00179         /**
00180         * Return a human-readable description for this PofExtractor.
00181         *
00182         * @return a String description of the PofExtractor
00183         */
00184         virtual void toStream(std::ostream& out) const;
00185 
00186 
00187     // ----- accessors ------------------------------------------------------
00188 
00189     public:
00190         /**
00191         * Obtain the Class of the extracted value.
00192         *
00193         * @return the expected Class
00194         */
00195         Class::View getClassExtracted() const;
00196 
00197         /**
00198         * Obtain the PofPath for this extractor.
00199         *
00200         * @return the PofPath value
00201         */
00202         virtual PofNavigator::View getNavigator() const;
00203 
00204 
00205     protected:
00206         // ----- helper methods ---------------------------------------------
00207 
00208         /**
00209         *  Compute the expected pof type id based on the class.
00210         *
00211         * @param vCtx  pof context
00212         *
00213         * @return pof type id or T_UNKNOWN if the class is null.
00214         */
00215         virtual int32_t getPofTypeId(PofContext::View vCtx) const;
00216 
00217 
00218         // ----- data members -----------------------------------------------
00219 
00220     private:
00221         /**
00222         * POF navigator.
00223         */
00224         FinalView<PofNavigator> m_vNavigator;
00225 
00226         /**
00227         * Class for what is being extracted; or null if this information is
00228         * specified in m_nType.
00229         */
00230         MemberView<Class> m_vClass;
00231 
00232         /**
00233         * POF type for expected value;
00234         */
00235         int32_t m_nType;
00236     };
00237 
00238 COH_CLOSE_NAMESPACE3
00239 
00240 #endif // #define COH_POF_EXTRACTOR_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.