C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/util/SerializationHelper.hpp

00001 /*
00002  * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
00003  *
00004  * Licensed under the Universal Permissive License v 1.0 as shown at
00005  * http://oss.oracle.com/licenses/upl.
00006  */
00007 #ifndef COH_SERIALIZATION_HELPER_HPP
00008 #define COH_SERIALIZATION_HELPER_HPP
00009 
00010 #include "coherence/lang.ns"
00011 
00012 #include "coherence/io/Serializer.hpp"
00013 #include "coherence/io/WriteBuffer.hpp"
00014 #include "coherence/util/Binary.hpp"
00015 
00016 COH_OPEN_NAMESPACE2(coherence,util)
00017 
00018 using coherence::io::Serializer;
00019 using coherence::io::WriteBuffer;
00020 
00021 
00022 /**
00023 * Miscellaneous serialization utilities.
00024 *
00025 * @author phf  2011.04.19
00026 *
00027 * @since Coherence 3.7.1
00028 */
00029 class COH_EXPORT SerializationHelper
00030     : public abstract_spec<SerializationHelper>
00031     {
00032     // ----- constructors ---------------------------------------------------
00033 
00034     private:
00035         /**
00036         * This constructor is blocked (private) as SerializationHelper
00037         * provides only a static interface and no instances may be created.
00038         */
00039         SerializationHelper();
00040 
00041 
00042     // ----- SerializationHelper interface ----------------------------------
00043 
00044     public:
00045         /**
00046         * Decorate the specified Binary value with the specified integer
00047         * decoration.
00048         *
00049         * @param vBinValue     the Binary value to be decorated
00050         * @param nDecoration   the integer decoration
00051         *
00052         * @return the decorated (with integer decoration) Binary object
00053         */
00054         static Binary::View decorateBinary(Binary::View vBinValue, int32_t nDecoration);
00055 
00056         /**
00057         * Extract a decoration value from the specified Binary that contains
00058         * an int decoration
00059         *
00060         * @param vBin  the Binary object
00061         *
00062         * @return the integer decoration value
00063         *
00064         * @throws IllegalArgumentException if the Binary does not have an
00065         *         int decoration
00066         */
00067         static int32_t extractIntDecoration(Binary::View vBin);
00068 
00069         /**
00070         * Check whether or not the specified Binary has an integer
00071         * decoration.
00072         *
00073         * @param vBin  the Binary object
00074         *
00075         * @return true if the Binary contains (starts with) an integer
00076         *         decoration; false otherwise
00077         */
00078         static bool isIntDecorated(Binary::View vBin);
00079 
00080         /**
00081         * Remove a decoration value from the specified Binary that contains a
00082         * representation of an IntDecoratedObject.
00083         *
00084         * @param vBin  the Binary object
00085         *
00086         * @return the undecorated Binary value
00087         */
00088         static Binary::View removeIntDecoration(Binary::View vBin);
00089 
00090         /**
00091         * Serialize an object into its Binary form.
00092         *
00093         * @param v            object to serialize
00094         * @param vSerializer  Serializer to use
00095         *
00096         * @return Binary representation of the specified object
00097         */
00098         static Binary::View toBinary(Object::View v, Serializer::View vSerializer);
00099 
00100         /**
00101         * Deserialize an object from its Binary form.
00102         *
00103         * @param vBin         Binary representation of an object
00104         * @param vSerializer  Serializer to use
00105         *
00106         * @return deserialized object
00107         *
00108         * @throws IOException if an I/O error occurs
00109         */
00110         static Object::Holder fromBinary(Binary::View vBin, Serializer::View vSerializer);
00111 
00112 
00113     // ----- inner class: Stats ---------------------------------------------
00114 
00115     protected:
00116         /**
00117         * Serialization statistics for a given user type.
00118         */
00119         class COH_EXPORT Stats
00120             : public class_spec<Stats,
00121                 extends<Object> >
00122             {
00123             friend class factory<Stats>;
00124 
00125             // ----- constructors ---------------------------------------
00126 
00127             protected:
00128                 /**
00129                 * Create a new Stats.
00130                 */
00131                 Stats();
00132 
00133 
00134             // ----- Stats methods --------------------------------------
00135 
00136             public:
00137                 /**
00138                 * Update the serialization statistics with the size (in
00139                 * bytes) of a newly serialized object.
00140                 *
00141                 * @param cb  the number of bytes used to serialize
00142                 */
00143                 virtual void update(int32_t cb);
00144 
00145                 /**
00146                 * Instantiate a WriteBuffer to write a user type for which
00147                 * this Stats object maintains serialization statistics.
00148                 *
00149                 * @return a WriteBuffer to write to
00150                 */
00151                 virtual WriteBuffer::Handle instantiateBuffer() const;
00152 
00153 
00154             // ----- constants ------------------------------------------
00155 
00156             private:
00157                 /**
00158                 * The expiry for statistics (in milliseconds).
00159                 */
00160                 static const int32_t expiry_millis = 10 * 60 * 1000; // 10 minutes
00161 
00162 
00163             // ----- data members ---------------------------------------
00164 
00165             private:
00166                 /**
00167                 * <ul>
00168                 * <li>high 2 bytes - Number of items that have been
00169                 * submitted for statistics keeping.</li>
00170                 * <li>low 6 bytes - Total number of bytes of all the items
00171                 * submitted.</li>
00172                 * </ul>
00173                 */
00174                 Volatile<int64_t> m_lAccum;
00175 
00176                 /**
00177                 * <ul>
00178                 * <li>highWord - Largest size in bytes of all the items
00179                 * submitted.</li>
00180                 * <li>lowWord  - The average size in bytes of all the items
00181                 * submitted.</li>
00182                 * </ul>
00183                 */
00184                 Volatile<int64_t> m_lStats;
00185 
00186                 /**
00187                 * Time at which this Stats object was created.
00188                 */
00189                 Volatile<int64_t> m_ldtCreated;
00190             };
00191 
00192 
00193     // ----- helper methods -------------------------------------------------
00194 
00195     private:
00196         /**
00197         * Calculate a somewhat unique ID for the type of the passed Object.
00198         *
00199         * @param v  a user type value
00200         *
00201         * @return an ID that is hopefully unique across the set of user type
00202         *         classes in use within this process at this general point in
00203         *         time
00204         */
00205         static int32_t calculateStatsId(Object::View v);
00206 
00207         /**
00208         * If statistics are being maintained for the class of the specified
00209         * Object value, then find and return those stats.
00210         *
00211         * @param v  the value to search for a Stats object for
00212         *
00213         * @return the Stats object for the specified Object value, or NULL
00214         */
00215         static SerializationHelper::Stats::Handle findStats(Object::View v);
00216 
00217         /**
00218         * If statistics are being maintained for the class of the specified
00219         * Object value, then find and return those stats.
00220         *
00221         * @param v      the object that has been written
00222         * @param stats  the statistics that track the serialized sizes of
00223         *               objects
00224         * @param cb     the size in bytes of the object as it was written
00225         */
00226         static void updateStats(Object::View v,
00227                 SerializationHelper::Stats::Handle hStats, int32_t cb);
00228 
00229 
00230     // ----- data members ---------------------------------------------------
00231 
00232     protected:
00233         /**
00234         * Decoration: The original value (before being decorated).
00235         */
00236         static const int32_t deco_value   = 0;
00237 
00238         /**
00239         * Serialization format: Decorated Binary value.
00240         *
00241         * Structure is:
00242         * <pre>
00243         * byte 0    : format identifier (18)
00244         * byte 1    : bit mask of decoration identifiers (see DECO_* constants)
00245         * byte 2    : packed int specifying the length of the first decoration
00246         * byte next : binary data
00247         * ...
00248         * </pre>
00249         * For each decoration, there is a packed int for its length, followed by
00250         * its binary data. The first decoration is the decorated value itself, if
00251         * present.
00252         *
00253         * Note: fmt_ido cannot be combined with fmt_bin_deco.
00254         */
00255         static const octet_t fmt_bin_deco = 18;
00256 
00257         /**
00258         * Serialization format: Extended-range Decorated Binary value.
00259         *
00260         * Structure is:
00261         * <pre>
00262         * byte 0    : format identifier (19)
00263         * byte 1    : bit mask of decoration identifiers (see DECO_* constants),
00264         *             in the packed long format (1-10 bytes)
00265         * byte next : packed int specifying the length of the first decoration
00266         * byte next : binary data
00267         * ...
00268         * </pre>
00269         * For each decoration, there is a packed int for its length, followed by
00270         * its binary data. The first decoration is the decorated value itself, if
00271         * present.
00272         *
00273         * Note: fmt_ido cannot be combined with fmt_bin_ext_deco.
00274         */
00275         static const octet_t fmt_bin_ext_deco = 19;
00276 
00277         /**
00278         * Serialization format: A DefaultSerializer is NOT used.
00279         */
00280         static const octet_t fmt_ext = 21;
00281 
00282         /**
00283         * Serialization format: Integer-decorated value.
00284         */
00285         static const octet_t fmt_ido = 13;
00286     };
00287 
00288 COH_CLOSE_NAMESPACE2
00289 
00290 #endif // COH_SERIALIZATION_HELPER_HPP
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.