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_POF_WRITER_HPP 00008 #define COH_POF_WRITER_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/io/pof/PofContext.hpp" 00013 #include "coherence/io/pof/RawDate.hpp" 00014 #include "coherence/io/pof/RawDateTime.hpp" 00015 #include "coherence/io/pof/RawDayTimeInterval.hpp" 00016 #include "coherence/io/pof/RawTime.hpp" 00017 #include "coherence/io/pof/RawTimeInterval.hpp" 00018 #include "coherence/io/pof/RawYearMonthInterval.hpp" 00019 #include "coherence/util/Binary.hpp" 00020 #include "coherence/util/Collection.hpp" 00021 #include "coherence/util/LongArray.hpp" 00022 #include "coherence/util/Map.hpp" 00023 00024 COH_OPEN_NAMESPACE3(coherence,io,pof) 00025 00026 using coherence::util::Binary; 00027 using coherence::util::Collection; 00028 using coherence::util::Map; 00029 using coherence::util::LongArray; 00030 00031 00032 /** 00033 * The PofWriter interface provides the capability of writing a set of 00034 * non-primitive types ("user types") to a POF stream as an ordered sequence 00035 * of indexed properties. 00036 * 00037 * The serialized format of a POF user type is as follows: 00038 * <ul> 00039 * <li>Type Identifier</li> 00040 * <li>Version Identifier</li> 00041 * <li>[Property Index, Property Value]*</li> 00042 * <li>-1</li> 00043 * </ul> 00044 * The type identifier is an integer value greater than or equal to zero that 00045 * identifies the non-primitive type. The type identifier has no explicit 00046 * or self-describing meaning within the POF stream itself; in other words, 00047 * the type identifier does not contain the actual class definition. Instead, 00048 * the PofWriter and corresponding {@link PofReader} share a 00049 * {@link PofContext} which contains the necessary meta-data, including type 00050 * identifier to type mappings. 00051 * 00052 * The version identifier is used to support both backwards and forwards 00053 * compatibility of serialized POF user types. Versioning of user types allows 00054 * the addition of new properties to a user type, but not the replacement or 00055 * removal of properties that existed in a previous version of the user type. 00056 * 00057 * When a version <i>v1</i> of a user type written by a PofWriter is read by 00058 * a PofReader that supports version <i>v2</i> of the same user type, the 00059 * PofReader returns default values for the additional properties of the User 00060 * Type that exist in <i>v2</i> but do not exist in <i>v1</i>. Conversely, 00061 * when a version <i>v2</i> of a user type written by a PofWriter is read by 00062 * a PofReader that supports version <i>v1</i> of the same user type, the 00063 * instance of user type <i>v1</i> must store those additional opaque 00064 * properties for later encoding. The PofReader enables the user type to 00065 * store off the opaque properties in binary form (see {@link 00066 * PofReader#readRemainder PofReader::readRemainder}). When the user type 00067 * is re-encoded, it must be done so using the version identifier 00068 * <i>v2</i>, since it is including the unaltered <i>v2</i> properties. The 00069 * opaque properties are subsequently included in the POF stream using the 00070 * {@link #writeRemainder} method. 00071 * 00072 * Following the version identifier is an ordered sequence of index/value 00073 * pairs, each of which is composed of a property index encoded as 00074 * non-negative integer value whose value is greater than the previous 00075 * property index, and a property value encoded as a POF value. The user type 00076 * is finally terminated with an illegal property index of -1. 00077 * 00078 * Note: To read a property that was written using a PofWrite method, the 00079 * corresponding read method on {@link PofReader} must be used. For example, 00080 * if a property was written using {@link #writeByteArray}, 00081 * {@link PofReader#readByteArray PofReader::readByteArray} must be used to 00082 * read the property. 00083 * 00084 * @author jh 2008.01.18 00085 * 00086 * @see PofContext 00087 * @see PofReader 00088 */ 00089 class COH_EXPORT PofWriter 00090 : public interface_spec<PofWriter> 00091 { 00092 // ----- primitive type support ----------------------------------------- 00093 00094 public: 00095 /** 00096 * Write a boolean property to the POF stream. 00097 * 00098 * @param iProp the property index 00099 * @param f the <tt>bool</tt> property value to write 00100 * 00101 * @throws coherence::lang::IllegalArgumentException if the property 00102 * index is invalid, or is less than or equal to the index of 00103 * the previous property written to the POF stream 00104 * @throws coherence::io::IOException if an I/O error occurs 00105 */ 00106 virtual void writeBoolean(int32_t iProp, bool f) = 0; 00107 00108 /** 00109 * Write an octet property to the POF stream. 00110 * 00111 * @param iProp the property index 00112 * @param b the <tt>octet_t</tt> property value to write 00113 * 00114 * @throws coherence::lang::IllegalArgumentException if the property 00115 * index is invalid, or is less than or equal to the index of 00116 * the previous property written to the POF stream 00117 * @throws coherence::io::IOException if an I/O error occurs 00118 */ 00119 virtual void writeOctet(int32_t iProp, octet_t b) = 0; 00120 00121 /** 00122 * Write a 16-bit Unicode character property (represented as a 00123 * <tt>wchar16_t</tt>) to the POF stream. 00124 * 00125 * @param iProp the property index 00126 * @param ch the <tt>wchar16_t</tt> property value to write 00127 * 00128 * @throws coherence::lang::IllegalArgumentException if the property 00129 * index is invalid, or is less than or equal to the index of 00130 * the previous property written to the POF stream 00131 * @throws coherence::io::IOException if an I/O error occurs 00132 */ 00133 virtual void writeChar16(int32_t iProp, wchar16_t ch) = 0; 00134 00135 /** 00136 * Write a 16-bit integer property to the POF stream. 00137 * 00138 * @param iProp the property index 00139 * @param n the <tt>int16_t</tt> property value to write 00140 * 00141 * @throws coherence::lang::IllegalArgumentException if the property 00142 * index is invalid, or is less than or equal to the index of 00143 * the previous property written to the POF stream 00144 * @throws coherence::io::IOException if an I/O error occurs 00145 */ 00146 virtual void writeInt16(int32_t iProp, int16_t n) = 0; 00147 00148 /** 00149 * Write a 32-bit integer property to the POF stream. 00150 * 00151 * @param iProp the property index 00152 * @param n the <tt>int32_t</tt> property value to write 00153 * 00154 * @throws coherence::lang::IllegalArgumentException if the property 00155 * index is invalid, or is less than or equal to the index of 00156 * the previous property written to the POF stream 00157 * @throws coherence::io::IOException if an I/O error occurs 00158 */ 00159 virtual void writeInt32(int32_t iProp, int32_t n) = 0; 00160 00161 /** 00162 * Write a 64-bit integer property to the POF stream. 00163 * 00164 * @param iProp the property index 00165 * @param l the <tt>int64_t</tt> property value to write 00166 * 00167 * @throws coherence::lang::IllegalArgumentException if the property 00168 * index is invalid, or is less than or equal to the index of 00169 * the previous property written to the POF stream 00170 * @throws coherence::io::IOException if an I/O error occurs 00171 */ 00172 virtual void writeInt64(int32_t iProp, int64_t l) = 0; 00173 00174 /** 00175 * Write a 32-bit floating-point property to the POF stream. 00176 * 00177 * @param iProp the property index 00178 * @param fl the <tt>float32_t</tt> property value to write 00179 * 00180 * @throws coherence::lang::IllegalArgumentException if the property 00181 * index is invalid, or is less than or equal to the index of 00182 * the previous property written to the POF stream 00183 * @throws coherence::io::IOException if an I/O error occurs 00184 */ 00185 virtual void writeFloat32(int32_t iProp, float32_t fl) = 0; 00186 00187 /** 00188 * Write a 64-bit floating-point property to the POF stream. 00189 * 00190 * @param iProp the property index 00191 * @param dfl the <tt>float64_t</tt> property value to write 00192 * 00193 * @throws coherence::lang::IllegalArgumentException if the property 00194 * index is invalid, or is less than or equal to the index of 00195 * the previous property written to the POF stream 00196 * @throws coherence::io::IOException if an I/O error occurs 00197 */ 00198 virtual void writeFloat64(int32_t iProp, float64_t dfl) = 0; 00199 00200 00201 // ----- primitive array support ---------------------------------------- 00202 00203 public: 00204 /** 00205 * Write a boolean array property to the POF stream. 00206 * 00207 * @param iProp the property index 00208 * @param vaf the <tt>bool</tt> array property value to write 00209 * 00210 * @throws coherence::lang::IllegalArgumentException if the property 00211 * index is invalid, or is less than or equal to the index of 00212 * the previous property written to the POF stream 00213 * @throws coherence::io::IOException if an I/O error occurs 00214 */ 00215 virtual void writeBooleanArray(int32_t iProp, Array<bool>::View vaf) = 0; 00216 00217 /** 00218 * Write an octect array property to the POF stream. 00219 * 00220 * @param iProp the property index 00221 * @param vab the <tt>octet_t</tt> array property value to write 00222 * 00223 * @throws coherence::lang::IllegalArgumentException if the property 00224 * index is invalid, or is less than or equal to the index of 00225 * the previous property written to the POF stream 00226 * @throws coherence::io::IOException if an I/O error occurs 00227 */ 00228 virtual void writeOctetArray(int32_t iProp, Array<octet_t>::View vab) = 0; 00229 00230 /** 00231 * Write a 16-bit Unicode character array property to the POF stream. 00232 * 00233 * @param iProp the property index 00234 * @param vach the <tt>wchar16_t</tt> array property value to write 00235 * 00236 * @throws coherence::lang::IllegalArgumentException if the property 00237 * index is invalid, or is less than or equal to the index of 00238 * the previous property written to the POF stream 00239 * @throws coherence::io::IOException if an I/O error occurs 00240 */ 00241 virtual void writeChar16Array(int32_t iProp, Array<wchar16_t>::View vach) = 0; 00242 00243 /** 00244 * Write a 16-bit integer array property to the POF stream. 00245 * 00246 * @param iProp the property index 00247 * @param van the <tt>int16_t</tt> array property value to write 00248 * 00249 * @throws coherence::lang::IllegalArgumentException if the property 00250 * index is invalid, or is less than or equal to the index of 00251 * the previous property written to the POF stream 00252 * @throws coherence::io::IOException if an I/O error occurs 00253 */ 00254 virtual void writeInt16Array(int32_t iProp, Array<int16_t>::View van) = 0; 00255 00256 /** 00257 * Write a 32-bit integer array property to the POF stream. 00258 * 00259 * @param iProp the property index 00260 * @param van the <tt>int32_t</tt> array property value to write 00261 * 00262 * @throws coherence::lang::IllegalArgumentException if the property 00263 * index is invalid, or is less than or equal to the index of 00264 * the previous property written to the POF stream 00265 * @throws coherence::io::IOException if an I/O error occurs 00266 */ 00267 virtual void writeInt32Array(int32_t iProp, Array<int32_t>::View van) = 0; 00268 00269 /** 00270 * Write a 64-bit integer array property to the POF stream. 00271 * 00272 * @param iProp the property index 00273 * @param val the <tt>int64_t</tt> array property value to write 00274 * 00275 * @throws coherence::lang::IllegalArgumentException if the property 00276 * index is invalid, or is less than or equal to the index of 00277 * the previous property written to the POF stream 00278 * @throws coherence::io::IOException if an I/O error occurs 00279 */ 00280 virtual void writeInt64Array(int32_t iProp, Array<int64_t>::View val) = 0; 00281 00282 /** 00283 * Write a 32-bit floating-point array property to the POF stream. 00284 * 00285 * @param iProp the property index 00286 * @param vafl the <tt>float32_t</tt> array property value to write 00287 * 00288 * @throws coherence::lang::IllegalArgumentException if the property 00289 * index is invalid, or is less than or equal to the index of 00290 * the previous property written to the POF stream 00291 * @throws coherence::io::IOException if an I/O error occurs 00292 */ 00293 virtual void writeFloat32Array(int32_t iProp, Array<float32_t>::View vafl) = 0; 00294 00295 /** 00296 * Write a 64-bit floating-point array property to the POF stream. 00297 * 00298 * @param iProp the property index 00299 * @param vadfl the <tt>float64_t</tt> array property value to write 00300 * 00301 * @throws coherence::lang::IllegalArgumentException if the property 00302 * index is invalid, or is less than or equal to the index of 00303 * the previous property written to the POF stream 00304 * @throws coherence::io::IOException if an I/O error occurs 00305 */ 00306 virtual void writeFloat64Array(int32_t iProp, Array<float64_t>::View vadfl) = 0; 00307 00308 00309 // ----- object value support ------------------------------------------- 00310 00311 public: 00312 /** 00313 * Write a <tt>Binary</tt> property to the POF stream. 00314 * 00315 * @param iProp the property index 00316 * @param vBin the <tt>Binary</tt> property value to write 00317 * 00318 * @throws coherence::lang::IllegalArgumentException if the property 00319 * index is invalid, or is less than or equal to the index of 00320 * the previous property written to the POF stream 00321 * @throws coherence::io::IOException if an I/O error occurs 00322 */ 00323 virtual void writeBinary(int32_t iProp, Binary::View vBin) = 0; 00324 00325 /** 00326 * Write a <tt>String</tt> property to the POF stream. 00327 * 00328 * @param iProp the property index 00329 * @param vs the <tt>String</tt> property value to write 00330 * 00331 * @throws coherence::lang::IllegalArgumentException if the property 00332 * index is invalid, or is less than or equal to the index of 00333 * the previous property written to the POF stream 00334 * @throws coherence::io::IOException if an I/O error occurs 00335 */ 00336 virtual void writeString(int32_t iProp, String::View vs) = 0; 00337 00338 /** 00339 * Write a {@link RawDate} property to the POF stream. 00340 * 00341 * @param iProp the property index 00342 * @param vDate the <tt>RawDate</tt> property value to write 00343 * 00344 * @throws coherence::lang::IllegalArgumentException if the property 00345 * index is invalid, or is less than or equal to the index of 00346 * the previous property written to the POF stream 00347 * @throws coherence::io::IOException if an I/O error occurs 00348 */ 00349 virtual void writeRawDate(int32_t iProp, RawDate::View vDate) = 0; 00350 00351 /** 00352 * Write a {@link RawDateTime} property to the POF stream. 00353 * 00354 * @param iProp the property index 00355 * @param vdt the <tt>RawDateTime</tt> property value to write 00356 * 00357 * @throws coherence::lang::IllegalArgumentException if the property 00358 * index is invalid, or is less than or equal to the index of 00359 * the previous property written to the POF stream 00360 * @throws coherence::io::IOException if an I/O error occurs 00361 */ 00362 virtual void writeRawDateTime(int32_t iProp, RawDateTime::View vdt) = 0; 00363 00364 /** 00365 * Write a {@link RawDayTimeInterval} property to the POF stream. 00366 * 00367 * @param iProp the property index 00368 * @param vInterval the <tt>RawDayTimeInterval</tt> property value to 00369 * write 00370 * 00371 * @throws coherence::lang::IllegalArgumentException if the property 00372 * index is invalid, or is less than or equal to the index of 00373 * the previous property written to the POF stream 00374 * @throws coherence::io::IOException if an I/O error occurs 00375 */ 00376 virtual void writeRawDayTimeInterval(int32_t iProp, 00377 RawDayTimeInterval::View vInterval) = 0; 00378 00379 /** 00380 * Write a {@link RawTime} property to the POF stream. 00381 * 00382 * @param iProp the property index 00383 * @param vTime the <tt>RawTime</tt> property value to write 00384 * 00385 * @throws coherence::lang::IllegalArgumentException if the property 00386 * index is invalid, or is less than or equal to the index of 00387 * the previous property written to the POF stream 00388 * @throws coherence::io::IOException if an I/O error occurs 00389 */ 00390 virtual void writeRawTime(int32_t iProp, RawTime::View vTime) = 0; 00391 00392 /** 00393 * Write a {@link RawTimeInterval} property to the POF stream. 00394 * 00395 * @param iProp the property index 00396 * @param vInterval the <tt>RawTimeInterval</tt> property value to 00397 * write 00398 * 00399 * @throws coherence::lang::IllegalArgumentException if the property 00400 * index is invalid, or is less than or equal to the index of 00401 * the previous property written to the POF stream 00402 * @throws coherence::io::IOException if an I/O error occurs 00403 */ 00404 virtual void writeRawTimeInterval(int32_t iProp, 00405 RawTimeInterval::View vInterval) = 0; 00406 00407 /** 00408 * Write a {@link RawYearMonthInterval} property to the POF stream. 00409 * 00410 * @param iProp the property index 00411 * @param vInterval the <tt>RawYearMonthInterval</tt> property value 00412 * to write 00413 * 00414 * @throws coherence::lang::IllegalArgumentException if the property 00415 * index is invalid, or is less than or equal to the index of 00416 * the previous property written to the POF stream 00417 * @throws coherence::io::IOException if an I/O error occurs 00418 */ 00419 virtual void writeRawYearMonthInterval(int32_t iProp, 00420 RawYearMonthInterval::View vInterval) = 0; 00421 00422 /** 00423 * Write an <tt>Object</tt> property to the POF stream. 00424 * 00425 * The given object must be an instance of one of the following: 00426 * <ul> 00427 * <li>Boolean</li> 00428 * <li>Octet</li> 00429 * <li>Char16</li> 00430 * <li>Int16</li> 00431 * <li>Int32</li> 00432 * <li>Int64</li> 00433 * <li>Float32</li> 00434 * <li>Float64</li> 00435 * <li>Array<bool></li> 00436 * <li>Array<octet_t></li> 00437 * <li>Array<wchar16_t></li> 00438 * <li>Array<int16_t></li> 00439 * <li>Array<int32_t></li> 00440 * <li>Array<int64_t></li> 00441 * <li>Array<float32_t></li> 00442 * <li>Array<float64_t></li> 00443 * <li>Binary</li> 00444 * <li>String</li> 00445 * <li>{@link RawDate}</li> 00446 * <li>{@link RawDateTime}</li> 00447 * <li>{@link RawDayTimeInterval}</li> 00448 * <li>{@link RawTime}</li> 00449 * <li>{@link RawTimeInterval}</li> 00450 * <li>{@link RawYearMonthInterval}</li> 00451 * <li>Collection, with the same restrictions for all elements</li> 00452 * <li>LongArray, with the same restrictions for all elements</li> 00453 * <li>ObjectArray, with the same restrictions for all elements</li> 00454 * </ul> 00455 * 00456 * Otherwise, a {@link PofSerializer} for the object must be 00457 * obtainable from the {@link PofContext} associated with this 00458 * PofWriter. 00459 * 00460 * @param iProp the property index 00461 * @param v the <tt>Object</tt> property to write 00462 * 00463 * @throws coherence::lang::IllegalArgumentException if the property 00464 * index is invalid, or is less than or equal to the index of 00465 * the previous property written to the POF stream 00466 * @throws coherence::lang::IllegalArgumentException if the given 00467 * property cannot be encoded into a POF stream 00468 * @throws coherence::io::IOException if an I/O error occurs 00469 */ 00470 virtual void writeObject(int32_t iProp, Object::View v) = 0; 00471 00472 00473 // ----- collection support --------------------------------------------- 00474 00475 public: 00476 /** 00477 * Write an <tt>ObjectArray</tt> property to the POF stream. 00478 * 00479 * Each element of the given array must be an instance (or a 00480 * collection of instances) of one of the following: 00481 * <ul> 00482 * <li>Boolean</li> 00483 * <li>Octet</li> 00484 * <li>Char16</li> 00485 * <li>Int16</li> 00486 * <li>Int32</li> 00487 * <li>Int64</li> 00488 * <li>Float32</li> 00489 * <li>Float64</li> 00490 * <li>Array<bool></li> 00491 * <li>Array<octet_t></li> 00492 * <li>Array<wchar16_t></li> 00493 * <li>Array<int16_t></li> 00494 * <li>Array<int32_t></li> 00495 * <li>Array<int64_t></li> 00496 * <li>Array<float32_t></li> 00497 * <li>Array<float64_t></li> 00498 * <li>Binary</li> 00499 * <li>String</li> 00500 * <li>{@link RawDate}</li> 00501 * <li>{@link RawDateTime}</li> 00502 * <li>{@link RawDayTimeInterval}</li> 00503 * <li>{@link RawTime}</li> 00504 * <li>{@link RawTimeInterval}</li> 00505 * <li>{@link RawYearMonthInterval}</li> 00506 * <li>Collection, with the same restrictions for all elements</li> 00507 * <li>LongArray, with the same restrictions for all elements</li> 00508 * <li>ObjectArray, with the same restrictions for all elements</li> 00509 * </ul> 00510 * 00511 * Otherwise, a {@link PofSerializer} for each element of the array 00512 * must be obtainable from the {@link PofContext} associated with this 00513 * PofWriter. 00514 * 00515 * @param iProp the property index 00516 * @param va the <tt>ObjectArray</tt> property value to write 00517 * 00518 * @throws coherence::lang::IllegalArgumentException if the property 00519 * index is invalid, or is less than or equal to the index of 00520 * the previous property written to the POF stream 00521 * @throws coherence::lang::IllegalArgumentException if the given 00522 * property cannot be encoded into a POF stream 00523 * @throws coherence::io::IOException if an I/O error occurs 00524 */ 00525 virtual void writeObjectArray(int32_t iProp, ObjectArray::View va) = 0; 00526 00527 /** 00528 * Write a uniform <tt>ObjectArray</tt> property to the POF stream. 00529 * 00530 * Each element of the given array must be an instance (or a 00531 * collection of instances) of one of the following: 00532 * <ul> 00533 * <li>Boolean</li> 00534 * <li>Octet</li> 00535 * <li>Char16</li> 00536 * <li>Int16</li> 00537 * <li>Int32</li> 00538 * <li>Int64</li> 00539 * <li>Float32</li> 00540 * <li>Float64</li> 00541 * <li>Array<bool></li> 00542 * <li>Array<octet_t></li> 00543 * <li>Array<wchar16_t></li> 00544 * <li>Array<int16_t></li> 00545 * <li>Array<int32_t></li> 00546 * <li>Array<int64_t></li> 00547 * <li>Array<float32_t></li> 00548 * <li>Array<float64_t></li> 00549 * <li>Binary</li> 00550 * <li>String</li> 00551 * <li>{@link RawDate}</li> 00552 * <li>{@link RawDateTime}</li> 00553 * <li>{@link RawDayTimeInterval}</li> 00554 * <li>{@link RawTime}</li> 00555 * <li>{@link RawTimeInterval}</li> 00556 * <li>{@link RawYearMonthInterval}</li> 00557 * <li>Collection, with the same restrictions for all elements</li> 00558 * <li>LongArray, with the same restrictions for all elements</li> 00559 * <li>ObjectArray, with the same restrictions for all elements</li> 00560 * </ul> 00561 * 00562 * Otherwise, a {@link PofSerializer} for each element of the array 00563 * must be obtainable from the {@link PofContext} associated with this 00564 * PofWriter. 00565 * 00566 * Additionally, the type of each element must be equal to the 00567 * specified class. 00568 * 00569 * @param iProp the property index 00570 * @param va the <tt>ObjectArray</tt> property value to write 00571 * @param vClass the class of all elements; must not be <tt>NULL</tt> 00572 * 00573 * @throws coherence::lang::IllegalArgumentException if the property 00574 * index is invalid, or is less than or equal to the index of 00575 * the previous property written to the POF stream 00576 * @throws coherence::lang::IllegalArgumentException if the given 00577 * property cannot be encoded into a POF stream 00578 * @throws coherence::lang::IllegalArgumentException if the type of 00579 * one or more elements of the array is not equal to the 00580 * specified class 00581 * @throws coherence::io::IOException if an I/O error occurs 00582 */ 00583 virtual void writeObjectArray(int32_t iProp, ObjectArray::View va, 00584 Class::View vClass) = 0; 00585 00586 /** 00587 * Write a <tt>LongArray</tt> property to the POF stream. 00588 * 00589 * Each element of the given array must be an instance (or a 00590 * collection of instances) of one of the following: 00591 * <ul> 00592 * <li>Boolean</li> 00593 * <li>Octet</li> 00594 * <li>Char16</li> 00595 * <li>Int16</li> 00596 * <li>Int32</li> 00597 * <li>Int64</li> 00598 * <li>Float32</li> 00599 * <li>Float64</li> 00600 * <li>Array<bool></li> 00601 * <li>Array<octet_t></li> 00602 * <li>Array<wchar16_t></li> 00603 * <li>Array<int16_t></li> 00604 * <li>Array<int32_t></li> 00605 * <li>Array<int64_t></li> 00606 * <li>Array<float32_t></li> 00607 * <li>Array<float64_t></li> 00608 * <li>Binary</li> 00609 * <li>String</li> 00610 * <li>{@link RawDate}</li> 00611 * <li>{@link RawDateTime}</li> 00612 * <li>{@link RawDayTimeInterval}</li> 00613 * <li>{@link RawTime}</li> 00614 * <li>{@link RawTimeInterval}</li> 00615 * <li>{@link RawYearMonthInterval}</li> 00616 * <li>Collection, with the same restrictions for all elements</li> 00617 * <li>LongArray, with the same restrictions for all elements</li> 00618 * <li>ObjectArray, with the same restrictions for all elements</li> 00619 * </ul> 00620 * 00621 * Otherwise, a {@link PofSerializer} for each element of the array 00622 * must be obtainable from the {@link PofContext} associated with this 00623 * PofWriter. 00624 * 00625 * @param iProp the property index 00626 * @param vla the <tt>LongArray</tt> property value to write 00627 * 00628 * @throws coherence::lang::IllegalArgumentException if the property 00629 * index is invalid, or is less than or equal to the index of 00630 * the previous property written to the POF stream 00631 * @throws coherence::lang::IllegalArgumentException if the given 00632 * property cannot be encoded into a POF stream 00633 * @throws coherence::io::IOException if an I/O error occurs 00634 */ 00635 virtual void writeLongArray(int32_t iProp, LongArray::View vla) = 0; 00636 00637 /** 00638 * Write a uniform <tt>LongArray</tt> property to the POF stream. 00639 * 00640 * Each element of the given array must be an instance (or a 00641 * collection of instances) of one of the following: 00642 * <ul> 00643 * <li>Boolean</li> 00644 * <li>Octet</li> 00645 * <li>Char16</li> 00646 * <li>Int16</li> 00647 * <li>Int32</li> 00648 * <li>Int64</li> 00649 * <li>Float32</li> 00650 * <li>Float64</li> 00651 * <li>Array<bool></li> 00652 * <li>Array<octet_t></li> 00653 * <li>Array<wchar16_t></li> 00654 * <li>Array<int16_t></li> 00655 * <li>Array<int32_t></li> 00656 * <li>Array<int64_t></li> 00657 * <li>Array<float32_t></li> 00658 * <li>Array<float64_t></li> 00659 * <li>Binary</li> 00660 * <li>String</li> 00661 * <li>{@link RawDate}</li> 00662 * <li>{@link RawDateTime}</li> 00663 * <li>{@link RawDayTimeInterval}</li> 00664 * <li>{@link RawTime}</li> 00665 * <li>{@link RawTimeInterval}</li> 00666 * <li>{@link RawYearMonthInterval}</li> 00667 * <li>Collection, with the same restrictions for all elements</li> 00668 * <li>LongArray, with the same restrictions for all elements</li> 00669 * <li>ObjectArray, with the same restrictions for all elements</li> 00670 * </ul> 00671 * 00672 * Otherwise, a {@link PofSerializer} for each element of the array 00673 * must be obtainable from the {@link PofContext} associated with this 00674 * PofWriter. 00675 * 00676 * Additionally, the type of each element must be equal to the 00677 * specified class. 00678 * 00679 * @param iProp the property index 00680 * @param vla the <tt>LongArray</tt> property value to write 00681 * @param vClass the class of all elements; must not be <tt>NULL</tt> 00682 * 00683 * @throws coherence::lang::IllegalArgumentException if the property 00684 * index is invalid, or is less than or equal to the index of 00685 * the previous property written to the POF stream 00686 * @throws coherence::lang::IllegalArgumentException if the given 00687 * property cannot be encoded into a POF stream 00688 * @throws coherence::lang::IllegalArgumentException if the type of 00689 * one or more elements of the array is not equal to the 00690 * specified class 00691 * @throws coherence::io::IOException if an I/O error occurs 00692 */ 00693 virtual void writeLongArray(int32_t iProp, LongArray::View vla, 00694 Class::View vClass) = 0; 00695 00696 /** 00697 * Write a <tt>Collection</tt> property to the POF stream. 00698 * 00699 * Each element of the given <tt>Collection</tt> must be an instance 00700 * (or collection of instances) of one of the following: 00701 * <ul> 00702 * <li>Boolean</li> 00703 * <li>Octet</li> 00704 * <li>Char16</li> 00705 * <li>Int16</li> 00706 * <li>Int32</li> 00707 * <li>Int64</li> 00708 * <li>Float32</li> 00709 * <li>Float64</li> 00710 * <li>Array<bool></li> 00711 * <li>Array<octet_t></li> 00712 * <li>Array<wchar16_t></li> 00713 * <li>Array<int16_t></li> 00714 * <li>Array<int32_t></li> 00715 * <li>Array<int64_t></li> 00716 * <li>Array<float32_t></li> 00717 * <li>Array<float64_t></li> 00718 * <li>Binary</li> 00719 * <li>String</li> 00720 * <li>{@link RawDate}</li> 00721 * <li>{@link RawDateTime}</li> 00722 * <li>{@link RawDayTimeInterval}</li> 00723 * <li>{@link RawTime}</li> 00724 * <li>{@link RawTimeInterval}</li> 00725 * <li>{@link RawYearMonthInterval}</li> 00726 * <li>Collection, with the same restrictions for all elements</li> 00727 * <li>LongArray, with the same restrictions for all elements</li> 00728 * <li>ObjectArray, with the same restrictions for all elements</li> 00729 * </ul> 00730 * 00731 * Otherwise, a {@link PofSerializer} for each element of the 00732 * <tt>Collection</tt> must be obtainable from the {@link PofContext} 00733 * associated with this PofWriter. 00734 * 00735 * @param iProp the property index 00736 * @param vCol the <tt>Collection</tt> property value to write 00737 * 00738 * @throws coherence::lang::IllegalArgumentException if the property 00739 * index is invalid, or is less than or equal to the index of 00740 * the previous property written to the POF stream 00741 * @throws coherence::lang::IllegalArgumentException if the given 00742 * property cannot be encoded into a POF stream 00743 * @throws coherence::io::IOException if an I/O error occurs 00744 */ 00745 virtual void writeCollection(int32_t iProp, Collection::View vCol) = 0; 00746 00747 /** 00748 * Write a uniform <tt>Collection</tt> property to the POF stream. 00749 * 00750 * Each element of the given <tt>Collection</tt> must be an instance 00751 * (or collection of instances) of one of the following: 00752 * <ul> 00753 * <li>Boolean</li> 00754 * <li>Octet</li> 00755 * <li>Char16</li> 00756 * <li>Int16</li> 00757 * <li>Int32</li> 00758 * <li>Int64</li> 00759 * <li>Float32</li> 00760 * <li>Float64</li> 00761 * <li>Array<bool></li> 00762 * <li>Array<octet_t></li> 00763 * <li>Array<wchar16_t></li> 00764 * <li>Array<int16_t></li> 00765 * <li>Array<int32_t></li> 00766 * <li>Array<int64_t></li> 00767 * <li>Array<float32_t></li> 00768 * <li>Array<float64_t></li> 00769 * <li>Binary</li> 00770 * <li>String</li> 00771 * <li>{@link RawDate}</li> 00772 * <li>{@link RawDateTime}</li> 00773 * <li>{@link RawDayTimeInterval}</li> 00774 * <li>{@link RawTime}</li> 00775 * <li>{@link RawTimeInterval}</li> 00776 * <li>{@link RawYearMonthInterval}</li> 00777 * <li>Collection, with the same restrictions for all elements</li> 00778 * <li>LongArray, with the same restrictions for all elements</li> 00779 * <li>ObjectArray, with the same restrictions for all elements</li> 00780 * </ul> 00781 * 00782 * Otherwise, a {@link PofSerializer} for each element of the 00783 * <tt>Collection</tt> must be obtainable from the {@link PofContext} 00784 * associated with this PofWriter. 00785 * 00786 * Additionally, the type of each element must be equal to the 00787 * specified class. 00788 * 00789 * @param iProp the property index 00790 * @param vCol the <tt>Collection</tt> property value to write 00791 * @param vClass the class of all elements; must not be <tt>NULL</tt> 00792 * 00793 * @throws coherence::lang::IllegalArgumentException if the property 00794 * index is invalid, or is less than or equal to the index of 00795 * the previous property written to the POF stream 00796 * @throws coherence::lang::IllegalArgumentException if the given 00797 * property cannot be encoded into a POF stream 00798 * @throws coherence::lang::IllegalArgumentException if the type of 00799 * one or more elements of the <tt>Collection</tt> is not 00800 * equal to the specified class 00801 * @throws coherence::io::IOException if an I/O error occurs 00802 */ 00803 virtual void writeCollection(int32_t iProp, Collection::View vCol, 00804 Class::View vClass) = 0; 00805 00806 /** 00807 * Write a <tt>Map</tt> property to the POF stream. 00808 * 00809 * Each key and value of the given <tt>Map</tt> must be an instance 00810 * (or a collection of instances) of one of the following: 00811 * <ul> 00812 * <li>Boolean</li> 00813 * <li>Octet</li> 00814 * <li>Char16</li> 00815 * <li>Int16</li> 00816 * <li>Int32</li> 00817 * <li>Int64</li> 00818 * <li>Float32</li> 00819 * <li>Float64</li> 00820 * <li>Array<bool></li> 00821 * <li>Array<octet_t></li> 00822 * <li>Array<wchar16_t></li> 00823 * <li>Array<int16_t></li> 00824 * <li>Array<int32_t></li> 00825 * <li>Array<int64_t></li> 00826 * <li>Array<float32_t></li> 00827 * <li>Array<float64_t></li> 00828 * <li>Binary</li> 00829 * <li>String</li> 00830 * <li>{@link RawDate}</li> 00831 * <li>{@link RawDateTime}</li> 00832 * <li>{@link RawDayTimeInterval}</li> 00833 * <li>{@link RawTime}</li> 00834 * <li>{@link RawTimeInterval}</li> 00835 * <li>{@link RawYearMonthInterval}</li> 00836 * <li>Collection, with the same restrictions for all elements</li> 00837 * <li>LongArray, with the same restrictions for all elements</li> 00838 * <li>ObjectArray, with the same restrictions for all elements</li> 00839 * </ul> 00840 * 00841 * Otherwise, a {@link PofSerializer} for each key and value of 00842 * the <tt>Map</tt> must be obtainable from the {@link PofContext} 00843 * associated with this PofWriter. 00844 * 00845 * @param iProp the property index 00846 * @param vMap the <tt>Map</tt> property value to write 00847 * 00848 * @throws coherence::lang::IllegalArgumentException if the property 00849 * index is invalid, or is less than or equal to the index of 00850 * the previous property written to the POF stream 00851 * @throws coherence::lang::IllegalArgumentException if the given 00852 * property cannot be encoded into a POF stream 00853 * @throws coherence::io::IOException if an I/O error occurs 00854 */ 00855 virtual void writeMap(int32_t iProp, Map::View vMap) = 0; 00856 00857 /** 00858 * Write a uniform key <tt>Map</tt> property to the POF stream. 00859 * 00860 * Each key and value of the given <tt>Map</tt> must be an instance 00861 * (or a collection of instances) of one of the following: 00862 * <ul> 00863 * <li>Boolean</li> 00864 * <li>Octet</li> 00865 * <li>Char16</li> 00866 * <li>Int16</li> 00867 * <li>Int32</li> 00868 * <li>Int64</li> 00869 * <li>Float32</li> 00870 * <li>Float64</li> 00871 * <li>Array<bool></li> 00872 * <li>Array<octet_t></li> 00873 * <li>Array<wchar16_t></li> 00874 * <li>Array<int16_t></li> 00875 * <li>Array<int32_t></li> 00876 * <li>Array<int64_t></li> 00877 * <li>Array<float32_t></li> 00878 * <li>Array<float64_t></li> 00879 * <li>Binary</li> 00880 * <li>String</li> 00881 * <li>{@link RawDate}</li> 00882 * <li>{@link RawDateTime}</li> 00883 * <li>{@link RawDayTimeInterval}</li> 00884 * <li>{@link RawTime}</li> 00885 * <li>{@link RawTimeInterval}</li> 00886 * <li>{@link RawYearMonthInterval}</li> 00887 * <li>Collection, with the same restrictions for all elements</li> 00888 * <li>LongArray, with the same restrictions for all elements</li> 00889 * <li>ObjectArray, with the same restrictions for all elements</li> 00890 * </ul> 00891 * 00892 * Otherwise, a {@link PofSerializer} for each key and value of 00893 * the <tt>Map</tt> must be obtainable from the {@link PofContext} 00894 * associated with this PofWriter. 00895 * 00896 * Additionally, the type of each key must be equal to the specified 00897 * class. 00898 * 00899 * @param iProp the property index 00900 * @param vMap the <tt>Map</tt> property value to write 00901 * @param vClassKey the class of all keys; must not be <tt>NULL</tt> 00902 * 00903 * @throws coherence::lang::IllegalArgumentException if the property 00904 * index is invalid, or is less than or equal to the index of 00905 * the previous property written to the POF stream 00906 * @throws coherence::lang::IllegalArgumentException if the given 00907 * property cannot be encoded into a POF stream 00908 * @throws coherence::lang::IllegalArgumentException if the type of 00909 * one or more keys of the <tt>Map</tt> is not equal to the 00910 * specified class 00911 * @throws coherence::io::IOException if an I/O error occurs 00912 */ 00913 virtual void writeMap(int32_t iProp, Map::View vMap, 00914 Class::View vClassKey) = 0; 00915 00916 /** 00917 * Write a uniform <tt>Map</tt> property to the POF stream. 00918 * 00919 * Each key and value of the given <tt>Map</tt> must be an instance 00920 * (or a collection of instances) of one of the following: 00921 * <ul> 00922 * <li>Boolean</li> 00923 * <li>Octet</li> 00924 * <li>Char16</li> 00925 * <li>Int16</li> 00926 * <li>Int32</li> 00927 * <li>Int64</li> 00928 * <li>Float32</li> 00929 * <li>Float64</li> 00930 * <li>Array<bool></li> 00931 * <li>Array<octet_t></li> 00932 * <li>Array<wchar16_t></li> 00933 * <li>Array<int16_t></li> 00934 * <li>Array<int32_t></li> 00935 * <li>Array<int64_t></li> 00936 * <li>Array<float32_t></li> 00937 * <li>Array<float64_t></li> 00938 * <li>Binary</li> 00939 * <li>String</li> 00940 * <li>{@link RawDate}</li> 00941 * <li>{@link RawDateTime}</li> 00942 * <li>{@link RawDayTimeInterval}</li> 00943 * <li>{@link RawTime}</li> 00944 * <li>{@link RawTimeInterval}</li> 00945 * <li>{@link RawYearMonthInterval}</li> 00946 * <li>Collection, with the same restrictions for all elements</li> 00947 * <li>LongArray, with the same restrictions for all elements</li> 00948 * <li>ObjectArray, with the same restrictions for all elements</li> 00949 * </ul> 00950 * 00951 * Otherwise, a {@link PofSerializer} for each key and value of 00952 * the <tt>Map</tt> must be obtainable from the {@link PofContext} 00953 * associated with this PofWriter. 00954 * 00955 * Additionally, the type of each key must be equal to the specified 00956 * class. 00957 * 00958 * @param iProp the property index 00959 * @param vMap the <tt>Map</tt> property value to write 00960 * @param vClassKey the class of all keys; must not be 00961 * <tt>NULL</tt> 00962 * @param vClassValue the class of all values; must not be 00963 * <tt>NULL</tt> 00964 * 00965 * @throws coherence::lang::IllegalArgumentException if the property 00966 * index is invalid, or is less than or equal to the index of 00967 * the previous property written to the POF stream 00968 * @throws coherence::lang::IllegalArgumentException if the given 00969 * property cannot be encoded into a POF stream 00970 * @throws coherence::lang::IllegalArgumentException if the type of 00971 * one or more keys or values of the <tt>Map</tt> is not equal 00972 * to the specified classes 00973 * @throws coherence::io::IOException if an I/O error occurs 00974 */ 00975 virtual void writeMap(int32_t iProp, Map::View vMap, 00976 Class::View vClassKey, Class::View vClassValue) = 0; 00977 00978 00979 // ----- POF user type support ------------------------------------------ 00980 00981 public: 00982 /** 00983 * Return the PofContext object used by this PofWriter to serialize 00984 * user types to a POF stream. 00985 * 00986 * @return the PofContext object that contains user type meta-data 00987 */ 00988 virtual PofContext::View getPofContext() const = 0; 00989 00990 /** 00991 * Configure the PofContext object used by this PofWriter to serialize 00992 * user types to a POF stream. 00993 * 00994 * Note: this is an advanced method that should be used with care. For 00995 * example, if this method is being used to switch to another 00996 * PofContext mid-POF stream, it is important to eventually restore 00997 * the original PofContext. For example: 00998 * <pre> 00999 * PofContext::View vCtxOrig = hWriter->getPofContext(); 01000 * 01001 * // switch to another PofContext 01002 * PofContext::View vCtxNew = ...; 01003 * hWriter->setContext(vCtxNew); 01004 * 01005 * // output POF data using the writer 01006 * ... 01007 * 01008 * // restore the original PofContext 01009 * hWriter->setPofContext(vCtxOrig); 01010 * </pre> 01011 * 01012 * @param vCtx the new PofContext; must not be <tt>NULL</tt> 01013 */ 01014 virtual void setPofContext(PofContext::View vCtx) = 0; 01015 01016 /** 01017 * Determine the user type that is currently being written. 01018 * 01019 * @return the user type identifier, or -1 if the PofWriter is not 01020 * currently writing a user type 01021 */ 01022 virtual int32_t getUserTypeId() const = 0; 01023 01024 /** 01025 * Determine the version identifier of the user type that is currently 01026 * being written. 01027 * 01028 * @return the integer version ID of the user type; always 01029 * non-negative 01030 * 01031 * @throws coherence::lang::IllegalStateException if no user type is 01032 * being parsed 01033 */ 01034 virtual int32_t getVersionId() const = 0; 01035 01036 /** 01037 * Set the version identifier of the user type that is currently being 01038 * written. 01039 * 01040 * @param nVersionId the user type identifier; must be non-negative 01041 * 01042 * @throws coherence::lang::IllegalArgumentException if the given 01043 * version ID is negative 01044 * @throws coherence::lang::IllegalStateException if no user type is 01045 * being written 01046 */ 01047 virtual void setVersionId(int32_t nVersionId) = 0; 01048 01049 /** 01050 * Obtain a PofWriter that can be used to write a set of properties into 01051 * a single property of the current user type. The returned PofWriter is 01052 * only valid from the time that it is returned until the next call is 01053 * made to this PofWriter. 01054 * 01055 * @param iProp the property index 01056 * 01057 * @return a PofWriter whose contents are nested into a single property 01058 * of this PofWriter 01059 * 01060 * @throws coherence::lang::IllegalArgumentException if the property 01061 * index is invalid, or is less than or equal to the index of 01062 * the previous property written to the POF stream 01063 * @throws coherence::lang::IllegalStateException if no user type is 01064 * being written 01065 * @throws coherence::io::IOException if an I/O error occurs 01066 * 01067 * @since Coherence 3.6 01068 */ 01069 virtual PofWriter::Handle createNestedPofWriter(int32_t iProp) = 0; 01070 01071 /** 01072 * Obtain a PofWriter that can be used to write a set of properties into 01073 * a single property of the current user type. The returned PofWriter is 01074 * only valid from the time that it is returned until the next call is 01075 * made to this PofWriter. 01076 * 01077 * @param iProp the property index 01078 * @param nTypeId the type identifier of the nested property 01079 * 01080 * @return a PofWriter whose contents are nested into a single property 01081 * of this PofWriter 01082 * 01083 * @throws coherence::lang::IllegalArgumentException if the property 01084 * index is invalid, or is less than or equal to the index of 01085 * the previous property written to the POF stream 01086 * @throws coherence::lang::IllegalStateException if no user type is 01087 * being written 01088 * @throws coherence::io::IOException if an I/O error occurs 01089 * 01090 * @since Coherence 12.2.1 01091 */ 01092 virtual PofWriter::Handle createNestedPofWriter(int32_t iProp, int32_t nTypeId) = 0; 01093 01094 /** 01095 * Write the remaining properties to the POF stream, terminating the 01096 * writing of the currrent user type. As part of writing out a user 01097 * type, this method must be called by the PofSerializer that is 01098 * writing out the user type, or the POF stream will be corrupted. 01099 * 01100 * Calling this method terminates the current user type by writing 01101 * a -1 to the POF stream after the last indexed property. Subsequent 01102 * calls to the various <tt>writeXYZ</tt> methods of this interface 01103 * will fail after this method is called. 01104 * 01105 * @param vBinProps a buffer that contains zero or more indexed 01106 * properties in binary POF encoded form; may be 01107 * <tt>NULL</tt> 01108 * 01109 * @throws coherence::lang::IllegalStateException if no user type is 01110 * being written 01111 * @throws coherence::io::IOException if an I/O error occurs 01112 */ 01113 virtual void writeRemainder(Binary::View vBinProps) = 0; 01114 }; 01115 01116 COH_CLOSE_NAMESPACE3 01117 01118 #endif // COH_POF_WRITER_HPP