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