Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

coherence/io/pof/PofReader.hpp

00001 /*
00002 * PofReader.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_READER_HPP
00017 #define COH_POF_READER_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::LongArray;
00038 using coherence::util::Map;
00039 
00040 
00041 /**
00042 * The PofReader interface provides the capability of reading a set of
00043 * non-primitive types ("user types") from a POF stream as an ordered
00044 * sequence of indexed properties.
00045 *
00046 * See {@link PofWriter} for a complete description of the POF user type
00047 * serialization format.
00048 *
00049 * @author jh  2008.01.18
00050 */
00051 class COH_EXPORT PofReader
00052     : public interface_spec<PofReader>
00053     {
00054     // ----- primitive type support -----------------------------------------
00055 
00056     public:
00057         /**
00058         * Read a boolean property from the POF stream.
00059         *
00060         * @param iProp  the property index to read
00061         *
00062         * @return the <tt>bool</tt> property value
00063         *
00064         * @throws coherence::lang::IllegalArgumentException if the property
00065         *         index is invalid, or is less than or equal to the index of
00066         *         the previous property read from the POF stream
00067         * @throws coherence::io::IOException if an I/O error occurs
00068         */
00069         virtual bool readBoolean(int32_t iProp) = 0;
00070 
00071         /**
00072         * Read an octet property from the POF stream.
00073         *
00074         * @param iProp  the property index to read
00075         *
00076         * @return the <tt>octet_t</tt> property value
00077         *
00078         * @throws coherence::lang::IllegalArgumentException if the property
00079         *         index is invalid, or is less than or equal to the index of
00080         *         the previous property read from the POF stream
00081         * @throws coherence::io::IOException if an I/O error occurs
00082         */
00083         virtual octet_t readOctet(int32_t iProp) = 0;
00084 
00085         /**
00086         * Read a 16-bit Unicode character property from the POF stream.
00087         *
00088         * @param iProp  the property index to read
00089         *
00090         * @return the 16-bit Unicode character property value as a
00091         *         <tt>char16_t</tt> value
00092         *
00093         * @throws coherence::lang::IllegalArgumentException if the property
00094         *         index is invalid, or is less than or equal to the index of
00095         *         the previous property read from the POF stream
00096         * @throws coherence::io::IOException if an I/O error occurs
00097         */
00098         virtual char16_t readChar16(int32_t iProp) = 0;
00099 
00100         /**
00101         * Read a 16-bit integer property from the POF stream.
00102         *
00103         * @param iProp  the property index to read
00104         *
00105         * @return the <tt>int16_t</tt> property value
00106         *
00107         * @throws coherence::lang::IllegalArgumentException if the property
00108         *         index is invalid, or is less than or equal to the index of
00109         *         the previous property read from the POF stream
00110         * @throws coherence::io::IOException if an I/O error occurs
00111         */
00112         virtual int16_t readInt16(int32_t iProp) = 0;
00113 
00114         /**
00115         * Read a 32-bit integer property from the POF stream.
00116         *
00117         * @param iProp  the property index to read
00118         *
00119         * @return the <tt>int32_t</tt> property value
00120         *
00121         * @throws coherence::lang::IllegalArgumentException if the property
00122         *         index is invalid, or is less than or equal to the index of
00123         *         the previous property read from the POF stream
00124         * @throws coherence::io::IOException if an I/O error occurs
00125         */
00126         virtual int32_t readInt32(int32_t iProp) = 0;
00127 
00128         /**
00129         * Read a 64-bit integer property from the POF stream.
00130         *
00131         * @param iProp  the property index to read
00132         *
00133         * @return the <tt>int64_t</tt> property value
00134         *
00135         * @throws coherence::lang::IllegalArgumentException if the property
00136         *         index is invalid, or is less than or equal to the index of
00137         *         the previous property read from the POF stream
00138         * @throws coherence::io::IOException if an I/O error occurs
00139         */
00140         virtual int64_t readInt64(int32_t iProp) = 0;
00141 
00142         /**
00143         * Read a a 32-bit floating-point property from the POF stream.
00144         *
00145         * @param iProp  the property index to read
00146         *
00147         * @return the <tt>float32_t</tt> property value
00148         *
00149         * @throws coherence::lang::IllegalArgumentException if the property
00150         *         index is invalid, or is less than or equal to the index of
00151         *         the previous property read from the POF stream
00152         * @throws coherence::io::IOException if an I/O error occurs
00153         */
00154         virtual float32_t readFloat32(int32_t iProp) = 0;
00155 
00156         /**
00157         * Read a 64-bit floating-point property from the POF stream.
00158         *
00159         * @param iProp  the property index to read
00160         *
00161         * @return the <tt>float64_t</tt> property value
00162         *
00163         * @throws coherence::lang::IllegalArgumentException if the property
00164         *         index is invalid, or is less than or equal to the index of
00165         *         the previous property read from the POF stream
00166         * @throws coherence::io::IOException if an I/O error occurs
00167         */
00168         virtual float64_t readFloat64(int32_t iProp) = 0;
00169 
00170 
00171     // ----- primitive array support ----------------------------------------
00172 
00173     public:
00174         /**
00175         * Read a boolean array property from the POF stream.
00176         *
00177         * @param iProp  the property index to read
00178         *
00179         * @return the <tt>bool</tt> array property value, or <tt>NULL</tt>
00180         *         if no value was available in the POF stream
00181         *
00182         * @throws coherence::lang::IllegalArgumentException if the property
00183         *         index is invalid, or is less than or equal to the index of
00184         *         the previous property read from the POF stream
00185         * @throws coherence::io::IOException if an I/O error occurs
00186         */
00187         virtual Array<bool>::Handle readBooleanArray(int32_t iProp) = 0;
00188 
00189         /**
00190         * Read an octet array property from the POF stream.
00191         *
00192         * @param iProp  the property index to read
00193         *
00194         * @return the <tt>octet_t</tt> array property value, or <tt>NULL</tt>
00195         *         if no value was available in the POF stream
00196         *
00197         * @throws coherence::lang::IllegalArgumentException if the property
00198         *         index is invalid, or is less than or equal to the index of
00199         *         the previous property read from the POF stream
00200         * @throws coherence::io::IOException if an I/O error occurs
00201         */
00202         virtual Array<octet_t>::Handle readOctetArray(int32_t iProp) = 0;
00203 
00204         /**
00205         * Read a 16-bit Unicode character array property from the POF stream.
00206         *
00207         * @param iProp  the property index to read
00208         *
00209         * @return the <tt>char16_t</tt> array property value, or
00210         *         <tt>NULL</tt> if no value was available in the POF stream
00211         *
00212         * @throws coherence::lang::IllegalArgumentException if the property
00213         *         index is invalid, or is less than or equal to the index of
00214         *         the previous property read from the POF stream
00215         * @throws coherence::io::IOException if an I/O error occurs
00216         */
00217         virtual Array<char16_t>::Handle readChar16Array(int32_t iProp) = 0;
00218 
00219         /**
00220         * Read a 16-bit integer array property from the POF stream.
00221         *
00222         * @param iProp  the property index to read
00223         *
00224         * @return the <tt>int16_t</tt> array property value, or <tt>NULL</tt>
00225         *         if no value was available in the POF stream
00226         *
00227         * @throws coherence::lang::IllegalArgumentException if the property
00228         *         index is invalid, or is less than or equal to the index of
00229         *         the previous property read from the POF stream
00230         * @throws coherence::io::IOException if an I/O error occurs
00231         */
00232         virtual Array<int16_t>::Handle readInt16Array(int32_t iProp) = 0;
00233 
00234         /**
00235         * Read a 32-bit integer array property from the POF stream.
00236         *
00237         * @param iProp  the property index to read
00238         *
00239         * @return the <tt>int32_t</tt> array property value, or <tt>NULL</tt>
00240         *         if no value was available in the POF stream
00241         *
00242         * @throws coherence::lang::IllegalArgumentException if the property
00243         *         index is invalid, or is less than or equal to the index of
00244         *         the previous property read from the POF stream
00245         * @throws coherence::io::IOException if an I/O error occurs
00246         */
00247         virtual Array<int32_t>::Handle readInt32Array(int32_t iProp) = 0;
00248 
00249         /**
00250         * Read a 64-bit integer array property from the POF stream.
00251         *
00252         * @param iProp  the property index to read
00253         *
00254         * @return the <tt>int64_t</tt> array property value, or <tt>NULL</tt>
00255         *         if no value was available in the POF stream
00256         *
00257         * @throws coherence::lang::IllegalArgumentException if the property
00258         *         index is invalid, or is less than or equal to the index of
00259         *         the previous property read from the POF stream
00260         * @throws coherence::io::IOException if an I/O error occurs
00261         */
00262         virtual Array<int64_t>::Handle readInt64Array(int32_t iProp) = 0;
00263 
00264         /**
00265         * Read a a 32-bit floating-point array property from the POF stream.
00266         *
00267         * @param iProp  the property index to read
00268         *
00269         * @return the <tt>float32_t</tt> array property value, or
00270         *         <tt>NULL</tt> if no value was available in the POF stream
00271         *
00272         * @throws coherence::lang::IllegalArgumentException if the property
00273         *         index is invalid, or is less than or equal to the index of
00274         *         the previous property read from the POF stream
00275         * @throws coherence::io::IOException if an I/O error occurs
00276         */
00277         virtual Array<float32_t>::Handle readFloat32Array(int32_t iProp) = 0;
00278 
00279         /**
00280         * Read a a 64-bit floating-point array property from the POF stream.
00281         *
00282         * @param iProp  the property index to read
00283         *
00284         * @return the <tt>float64_t</tt> array property value, or
00285         *         <tt>NULL</tt> if no value was available in the POF stream
00286         *
00287         * @throws coherence::lang::IllegalArgumentException if the property
00288         *         index is invalid, or is less than or equal to the index of
00289         *         the previous property read from the POF stream
00290         * @throws coherence::io::IOException if an I/O error occurs
00291         */
00292         virtual Array<float64_t>::Handle readFloat64Array(int32_t iProp) = 0;
00293 
00294 
00295     // ----- object value support -------------------------------------------
00296 
00297     public:
00298         /**
00299         * Read a <tt>Binary</tt> property from the POF stream.
00300         *
00301         * @param iProp  the property index to read
00302         *
00303         * @return the <tt>Binary</tt> property value, or <tt>NULL</tt> if no
00304         *         value was available in the POF stream
00305         *
00306         * @throws coherence::lang::IllegalArgumentException if the property
00307         *         index is invalid, or is less than or equal to the index of
00308         *         the previous property read from the POF stream
00309         * @throws coherence::io::IOException if an I/O error occurs
00310         */
00311         virtual Binary::View readBinary(int32_t iProp) = 0;
00312 
00313         /**
00314         * Read a <tt>String</tt> property from the POF stream.
00315         *
00316         * @param iProp  the property index to read
00317         *
00318         * @return the <tt>String</tt> property value, or <tt>NULL</tt> if no
00319         *         value was available in the POF stream
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 read from the POF stream
00324         * @throws coherence::io::IOException if an I/O error occurs
00325         */
00326         virtual String::View readString(int32_t iProp) = 0;
00327 
00328         /**
00329         * Read a {@link RawDate} property from the POF stream.
00330         *
00331         * @param iProp  the property index to read
00332         *
00333         * @return the <tt>RawDate</tt> property value, or <tt>NULL</tt> if no
00334         *         value was available in the POF stream
00335         *
00336         * @throws coherence::lang::IllegalArgumentException if the property
00337         *         index is invalid, or is less than or equal to the index of
00338         *         the previous property read from the POF stream
00339         * @throws coherence::io::IOException if an I/O error occurs
00340         */
00341         virtual RawDate::View readRawDate(int32_t iProp) = 0;
00342 
00343         /**
00344         * Read a {@link RawTime} property from the POF stream.
00345         *
00346         * @param iProp  the property index to read
00347         *
00348         * @return the <tt>RawTime</tt> property value, or <tt>NULL</tt> if no
00349         *         value was available in the POF stream
00350         *
00351         * @throws coherence::lang::IllegalArgumentException if the property
00352         *         index is invalid, or is less than or equal to the index of
00353         *         the previous property read from the POF stream
00354         * @throws coherence::io::IOException if an I/O error occurs
00355         */
00356         virtual RawTime::View readRawTime(int32_t iProp) = 0;
00357 
00358         /**
00359         * Read a {@link RawDateTime} property from the POF stream.
00360         *
00361         * @param iProp  the property index to read
00362         *
00363         * @return the <tt>RawDateTime</tt> property value, or <tt>NULL</tt>
00364         *         if no value was available in the POF stream
00365         *
00366         * @throws coherence::lang::IllegalArgumentException if the property
00367         *         index is invalid, or is less than or equal to the index of
00368         *         the previous property read from the POF stream
00369         * @throws coherence::io::IOException if an I/O error occurs
00370         */
00371         virtual RawDateTime::View readRawDateTime(int32_t iProp) = 0;
00372 
00373         /**
00374         * Read a {@link RawYearMonthInterval} property from the POF stream.
00375         *
00376         * @param iProp  the property index to read
00377         *
00378         * @return the <tt>RawYearMonthInterval</tt> property value, or
00379         *         <tt>NULL</tt> if no value was available in the POF stream
00380         *
00381         * @throws coherence::lang::IllegalArgumentException if the property
00382         *         index is invalid, or is less than or equal to the index of
00383         *         the previous property read from the POF stream
00384         * @throws coherence::io::IOException if an I/O error occurs
00385         */
00386         virtual RawYearMonthInterval::View readRawYearMonthInterval(
00387                 int32_t iProp) = 0;
00388 
00389         /**
00390         * Read a {@link RawTimeInterval} property from the POF stream.
00391         *
00392         * @param iProp  the property index to read
00393         *
00394         * @return the <tt>RawTimeInterval</tt> property value, or
00395         *         <tt>NULL</tt> if no value was available in the POF stream
00396         *
00397         * @throws coherence::lang::IllegalArgumentException if the property
00398         *         index is invalid, or is less than or equal to the index of
00399         *         the previous property read from the POF stream
00400         * @throws coherence::io::IOException if an I/O error occurs
00401         */
00402         virtual RawTimeInterval::View readRawTimeInterval(int32_t iProp) = 0;
00403 
00404         /**
00405         * Read a {@link RawDayTimeInterval} property from the POF stream.
00406         *
00407         * @param iProp  the property index to read
00408         *
00409         * @return the <tt>RawDayTimeInterval</tt> property value, or
00410         *         <tt>NULL</tt> if no value was available in the POF stream
00411         *
00412         * @throws coherence::lang::IllegalArgumentException if the property
00413         *         index is invalid, or is less than or equal to the index of
00414         *         the previous property read from the POF stream
00415         * @throws coherence::io::IOException if an I/O error occurs
00416         */
00417         virtual RawDayTimeInterval::View readRawDayTimeInterval(int32_t iProp) = 0;
00418 
00419         /**
00420         * Read a property of any type, including a user type, from the POF
00421         * stream.
00422         *
00423         * @param iProp  the property index to read
00424         *
00425         * @return the Object value, or <tt>NULL</tt> if no value was
00426         *         available in the POF stream
00427         *
00428         * @throws coherence::lang::IllegalArgumentException if the property
00429         *         index is invalid, or is less than or equal to the index of
00430         *         the previous property read from the POF stream
00431         * @throws coherence::io::IOException if an I/O error occurs
00432         */
00433         virtual Object::Holder readObject(int32_t iProp) = 0;
00434 
00435         /**
00436         * Read an <tt>ObjectArray</tt> property from the POF stream.
00437         *
00438         * @param iProp  the property index to read
00439         *
00440         * @return an <tt>ObjectArray</tt> of object values, or <tt>NULL</tt>
00441         *         if no <tt>ObjectArray</tt> is passed and there is no array
00442         *         data in the POF stream
00443         *
00444         * @throws coherence::lang::IllegalArgumentException if the property
00445         *         index is invalid, or is less than or equal to the index of
00446         *         the previous property read from the POF stream
00447         * @throws coherence::io::IOException if an I/O error occurs
00448         */
00449         virtual ObjectArray::Handle readObjectArray(int32_t iProp) = 0;
00450 
00451 
00452     // ----- collection support ---------------------------------------------
00453 
00454     public:
00455         /**
00456         * Read a <tt>LongArray</tt> of object values from the POF stream.
00457         *
00458         * @param iProp  the property index to read
00459         * @param hla    the optional <tt>LongArray</tt> to use to store the
00460         *               values; may be <tt>NULL</tt>
00461         *
00462         * @return a <tt>LongArray</tt> of object values, or <tt>NULL</tt> if
00463         *         no <tt>LongArray</tt> is passed and there is no key/value
00464         *         data available in the POF stream
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 read from the POF stream
00469         * @throws coherence::io::IOException if an I/O error occurs
00470         */
00471         virtual LongArray::View readLongArray(int32_t iProp,
00472                 LongArray::Handle hla = NULL) = 0;
00473 
00474         /**
00475         * Read a <tt>Collection</tt> of object values from the POF stream.
00476         *
00477         * @param iProp  the property index to read
00478         * @param hCol   the optional <tt>Collection</tt> to use to store the
00479         *               values; may be <tt>NULL</tt>
00480         *
00481         * @return a <tt>Collection</tt> of object values, or <tt>NULL</tt> if
00482         *         no <tt>Collection</tt> is passed and there is no collection
00483         *         data available in the POF stream
00484         *
00485         * @throws coherence::lang::IllegalArgumentException if the property
00486         *         index is invalid, or is less than or equal to the index of
00487         *         the previous property read from the POF stream
00488         * @throws coherence::io::IOException if an I/O error occurs
00489         */
00490         virtual Collection::View readCollection(int32_t iProp,
00491                 Collection::Handle hCol = NULL) = 0;
00492 
00493         /**
00494         * Read a <tt>Map</tt> of key/value pairs from the POF stream.
00495         *
00496         * @param iProp  the property index to read
00497         * @param hMap   the optional <tt>Map</tt> to initialize; the handle
00498         *               may be <tt>NULL</tt>
00499         *
00500         * @return a <tt>Map</tt> of key/value pairs, or <tt>NULL</tt> if no
00501         *         <tt>Map</tt> is passed and there is no key/value data in
00502         *         the POF stream
00503         *
00504         * @throws coherence::lang::IllegalArgumentException if the property
00505         *         index is invalid, or is less than or equal to the index of
00506         *         the previous property read from the POF stream
00507         * @throws coherence::io::IOException if an I/O error occurs
00508         */
00509         virtual Map::View readMap(int32_t iProp, Map::Handle hMap = NULL) = 0;
00510 
00511 
00512     // ----- POF user type support ------------------------------------------
00513 
00514     public:
00515         /**
00516         * Return the PofContext object used by this PofReader to deserialize
00517         * user types from a POF stream.
00518         *
00519         * @return the PofContext object that contains user type meta-data
00520         */
00521         virtual PofContext::View getPofContext() const = 0;
00522 
00523         /**
00524         * Configure the PofContext object used by this PofReader to
00525         * deserialize user types from a POF stream.
00526         *
00527         * Note: this is an advanced method that should be used with care. For
00528         * example, if this method is being used to switch to another
00529         * PofContext mid-POF stream, it is important to eventually restore
00530         * the original PofContext. For example:
00531         * <pre>
00532         * PofContext::View vCtxOrig = hReader->getPofContext();
00533         *
00534         * // switch to another PofContext
00535         * PofContext::View vCtxNew = ...;
00536         * hReader->setContext(vCtxNew);
00537         *
00538         * // read POF data using the reader
00539         * ...
00540         *
00541         * // restore the original PofContext
00542         * hReader->setPofContext(vCtxOrig);
00543         * </pre>
00544         *
00545         * @param vCtx  the new PofContext; must not be <tt>NULL</tt>
00546         */
00547         virtual void setPofContext(PofContext::View vCtx) = 0;
00548 
00549         /**
00550         * Determine the user type that is currently being parsed.
00551         *
00552         * @return the user type information, or -1 if the PofReader is not
00553         *         currently parsing a user type
00554         */
00555         virtual int32_t getUserTypeId() const = 0;
00556 
00557         /**
00558         * Determine the version identifier of the user type that is currently
00559         * being parsed.
00560         *
00561         * @return the integer version ID read from the POF stream; always
00562         *         non-negative
00563         *
00564         * @throws coherence::lang::IllegalStateException if no user type is
00565         *         being parsed
00566         */
00567         virtual int32_t getVersionId() const = 0;
00568 
00569         /**
00570         * Read all remaining indexed properties of the current user type from
00571         * the POF stream. As part of reading in a user type, this method must
00572         * be called by the PofSerializer that is reading the user type, or
00573         * the read position within the POF stream will be corrupted.
00574         *
00575         * Subsequent calls to the various <tt>readXYZ</tt> methods of this
00576         * interface will fail after this method is called.
00577         *
00578         * @return a buffer containing zero or more indexed properties in
00579         *         binary POF encoded form
00580         *
00581         * @throws coherence::lang::IllegalStateException if no user type is
00582         *         being parsed
00583         * @throws coherence::io::IOException if an I/O error occurs
00584         */
00585         virtual Binary::View readRemainder() = 0;
00586     };
00587 
00588 COH_CLOSE_NAMESPACE3
00589 
00590 #endif // COH_POF_READER_HPP
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.