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