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