Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/io/pof/PofWriter.hpp

    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         * Obtain a PofWriter that can be used to write a set of properties into
    01054         * a single property of the current user type. The returned PofWriter is
    01055         * only valid from the time that it is returned until the next call is
    01056         * made to this PofWriter.
    01057         *
    01058         * @param iProp  the property index
    01059         *
    01060         * @return a PofWriter whose contents are nested into a single property
    01061         *         of this PofWriter
    01062         *
    01063         * @throws coherence::lang::IllegalArgumentException if the property
    01064         *         index is invalid, or is less than or equal to the index of
    01065         *         the previous property written to the POF stream
    01066         * @throws coherence::lang::IllegalStateException if no user type is
    01067         *         being written
    01068         * @throws coherence::io::IOException if an I/O error occurs
    01069         *
    01070         * @since Coherence 3.6
    01071         */
    01072         virtual PofWriter::Handle createNestedPofWriter(int32_t iProp) = 0;
    01073
    01074         /**
    01075         * Write the remaining properties to the POF stream, terminating the
    01076         * writing of the currrent user type. As part of writing out a user
    01077         * type, this method must be called by the PofSerializer that is
    01078         * writing out the user type, or the POF stream will be corrupted.
    01079         *
    01080         * Calling this method terminates the current user type by writing
    01081         * a -1 to the POF stream after the last indexed property. Subsequent
    01082         * calls to the various <tt>writeXYZ</tt> methods of this interface
    01083         * will fail after this method is called.
    01084         *
    01085         * @param vBinProps a buffer that contains zero or more indexed
    01086         *                  properties in binary POF encoded form; may be
    01087         *                  <tt>NULL</tt>
    01088         *
    01089         * @throws coherence::lang::IllegalStateException if no user type is
    01090         *         being written
    01091         * @throws coherence::io::IOException if an I/O error occurs
    01092         */
    01093         virtual void writeRemainder(Binary::View vBinProps) = 0;
    01094     };
    01095
    01096 COH_CLOSE_NAMESPACE3
    01097
    01098 #endif // COH_POF_WRITER_HPP

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.