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