Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/io/pof/PofHandler.hpp

00001 /*
00002 * PofHandler.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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_HANDLER_HPP
00017 #define COH_POF_HANDLER_HPP
00018 
00019 #include "coherence/lang.ns"
00020 
00021 #include "coherence/util/Binary.hpp"
00022 
00023 COH_OPEN_NAMESPACE3(coherence,io,pof)
00024 
00025 using coherence::util::Binary;
00026 
00027 
00028 /**
00029 * This interface defines the handler for an event-driven approach to parsing
00030 * (or assembling) a POF stream.
00031 *
00032 * @author jh  2008.01.23
00033 */
00034 class COH_EXPORT PofHandler
00035     : public interface_spec<PofHandler>
00036     {
00037     // ----- PofHandler interface -------------------------------------------
00038 
00039     public:
00040         /**
00041         * This method is invoked when an identity is encountered in the POF
00042         * stream. The identity is used to uniquely identify the next value in
00043         * the POF stream, and can be later referenced by the
00044         * {@link #onIdentityReference} method.
00045         *
00046         * @param nId  if <tt>(nId >= 0)</tt>, then this is the identity
00047         *             encountered in the POF stream, otherwise it is an
00048         *             indicator that the following value <i>could</i> have
00049         *             been assigned an identifier but was not (i.e. that the
00050         *             subsequent value is of a referenceable data type)
00051         */
00052         virtual void registerIdentity(int32_t nId) = 0;
00053 
00054         /**
00055         * Specifies that a NULL value has been encountered in the POF stream.
00056         *
00057         * @param iPos  context-sensitive position information: property index
00058         *              within a user type, array index within an array,
00059         *              element counter within a collection, entry counter
00060         *              within a map, -1 otherwise
00061         */
00062         virtual void onNullReference(int32_t iPos) = 0;
00063 
00064         /**
00065         * Specifies that a reference to a previously-identified value has
00066         * been encountered in the POF stream.
00067         *
00068         * @param iPos  context-sensitive position information: property index
00069         *              within a user type, array index within an array,
00070         *              element counter within a collection, entry counter
00071         *              within a map, -1 otherwise
00072         * @param nId   the identity of the previously encountered value, as
00073         *              was specified in a previous call to {@link
00074         *              #registerIdentity}
00075         */
00076         virtual void onIdentityReference(int32_t iPos, int32_t nId) = 0;
00077 
00078         /**
00079         * Report that a short integer value has been encountered in the POF
00080         * stream.
00081         *
00082         * @param iPos  context-sensitive position information: property index
00083         *              within a user type, array index within an array,
00084         *              element counter within a collection, entry counter
00085         *              within a map, -1 otherwise
00086         * @param n     the integer value as a short
00087         */
00088         virtual void onInt16(int32_t iPos, int16_t n) = 0;
00089 
00090         /**
00091         * Report that an integer value has been encountered in the POF stream.
00092         *
00093         * @param iPos  context-sensitive position information: property index
00094         *              within a user type, array index within an array,
00095         *              element counter within a collection, entry counter
00096         *              within a map, -1 otherwise
00097         * @param n     the integer value as an int32_t
00098         */
00099         virtual void onInt32(int32_t iPos, int32_t n) = 0;
00100 
00101         /**
00102         * Report that a long integer value has been encountered in the POF
00103         * stream.
00104         *
00105         * @param iPos  context-sensitive position information: property index
00106         *              within a user type, array index within an array,
00107         *              element counter within a collection, entry counter
00108         *              within a map, -1 otherwise
00109         * @param n     the integer value as a long
00110         */
00111         virtual void onInt64(int32_t iPos, int64_t n) = 0;
00112 
00113         /**
00114         * Report that a base-2 single-precision floating-point value has been
00115         * encountered in the POF stream.
00116         *
00117         * @param iPos  context-sensitive position information: property index
00118         *              within a user type, array index within an array,
00119         *              element counter within a collection, entry counter
00120         *              within a map, -1 otherwise
00121         * @param fl    the floating-point value as a float32_t
00122         */
00123         virtual void onFloat32(int32_t iPos, float32_t fl) = 0;
00124 
00125         /**
00126         * Report that a base-2 double-precision floating-point value has been
00127         * encountered in the POF stream.
00128         *
00129         * @param iPos  context-sensitive position information: property index
00130         *              within a user type, array index within an array,
00131         *              element counter within a collection, entry counter
00132         *              within a map, -1 otherwise
00133         * @param dfl   the floating-point value as a float64_t
00134         */
00135         virtual void onFloat64(int32_t iPos, float64_t dfl) = 0;
00136 
00137         /**
00138         * Report that a boolean value has been encountered in the POF stream.
00139         *
00140         * @param iPos  context-sensitive position information: property index
00141         *              within a user type, array index within an array,
00142         *              element counter within a collection, entry counter
00143         *              within a map, -1 otherwise
00144         * @param f     the boolean value
00145         */
00146         virtual void onBoolean(int32_t iPos, bool f) = 0;
00147 
00148         /**
00149         * Report that an octet value (a byte) has been encountered in the POF
00150         * stream.
00151         *
00152         * @param iPos  context-sensitive position information: property index
00153         *              within a user type, array index within an array,
00154         *              element counter within a collection, entry counter
00155         *              within a map, -1 otherwise
00156         * @param b     the octet value
00157         */
00158         virtual void onOctet(int32_t iPos, octet_t b) = 0;
00159 
00160         /**
00161         * Report that a octet string value has been encountered in the POF
00162         * stream.
00163         *
00164         * @param iPos  context-sensitive position information: property index
00165         *              within a user type, array index within an array,
00166         *              element counter within a collection, entry counter
00167         *              within a map, -1 otherwise
00168         * @param vBin  the octect string value as a Binary object
00169         */
00170         virtual void onOctetString(int32_t iPos, Binary::View vBin) = 0;
00171 
00172         /**
00173         * Report that a character value has been encountered in the POF
00174         * stream.
00175         *
00176         * @param iPos  context-sensitive position information: property index
00177         *              within a user type, array index within an array,
00178         *              element counter within a collection, entry counter
00179         *              within a map, -1 otherwise
00180         * @param ch    the character value as a char16_t
00181         */
00182         virtual void onChar(int32_t iPos, char16_t ch) = 0;
00183 
00184         /**
00185         * Report that a character string value has been encountered in the
00186         * POF stream.
00187         *
00188         * @param iPos  context-sensitive position information: property index
00189         *              within a user type, array index within an array,
00190         *              element counter within a collection, entry counter
00191         *              within a map, -1 otherwise
00192         * @param vs    the character string value as a String object
00193         */
00194         virtual void onCharString(int32_t iPos, String::View vs) = 0;
00195 
00196         /**
00197         * Report that a date value has been encountered in the POF stream.
00198         *
00199         * @param iPos    context-sensitive position information: property
00200         *                index within a user type, array index within an
00201         *                array, element counter within a collection, entry
00202         *                counter within a map, -1 otherwise
00203         * @param nYear   the year number as defined by ISO8601
00204         * @param nMonth  the month number between 1 and 12 inclusive as
00205         *                defined by ISO8601
00206         * @param nDay    the day number between 1 and 31 inclusive as defined
00207         *                by ISO8601
00208         */
00209         virtual void onDate(int32_t iPos, int32_t nYear, int32_t nMonth,
00210                 int32_t nDay) = 0;
00211 
00212         /**
00213         * Report that a year-month interval value has been encountered in the
00214         * POF stream.
00215         *
00216         * @param iPos     context-sensitive position information: property
00217         *                 index within a user type, array index within an
00218         *                 array, element counter within a collection, entry
00219         *                 counter within a map, -1 otherwise
00220         * @param cYears   the number of years in the year-month interval
00221         * @param cMonths  the number of months in the year-month interval
00222         */
00223         virtual void onYearMonthInterval(int32_t iPos, int32_t cYears,
00224                 int32_t cMonths) = 0;
00225 
00226         /**
00227         * Report that a time value has been encountered in the POF stream.
00228         *
00229         * @param iPos     context-sensitive position information: property
00230         *                 index within a user type, array index within an
00231         *                 array, element counter within a collection, entry
00232         *                 counter within a map, -1 otherwise
00233         * @param nHour    the hour between 0 and 23 inclusive
00234         * @param nMinute  the minute value between 0 and 59 inclusive
00235         * @param nSecond  the second value between 0 and 59 inclusive (and
00236         *                 theoretically 60 for a leap-second)
00237         * @param nNano    the nanosecond value between 0 and 999999999
00238         *                 inclusive
00239         * @param fUTC     true if the time value is UTC or false if the time
00240         *                 value does not have an explicit time zone
00241         */
00242         virtual void onTime(int32_t iPos, int32_t nHour, int32_t nMinute,
00243                 int32_t nSecond, int32_t nNano, bool fUTC) = 0;
00244 
00245         /**
00246         * Report that a time value (with a timezone offset) has been
00247         * encountered in the POF stream.
00248         *
00249         * @param iPos           context-sensitive position information:
00250         *                       property index within a user type, array
00251         *                       index within an array, element counter within
00252         *                       a collection, entry counter within a map, -1
00253         *                       otherwise
00254         * @param nHour          the hour between 0 and 23 inclusive
00255         * @param nMinute        the minute value between 0 and 59 inclusive
00256         * @param nSecond        the second value between 0 and 59 inclusive
00257         *                       (and theoretically 60 for a leap-second)
00258         * @param nNano          the nanosecond value between 0 and 999999999
00259         *                       inclusive
00260         * @param nHourOffset    the timezone offset in hours from UTC, for
00261         *                       example 0 for BST, -5 for EST and 1 for CET
00262         * @param nMinuteOffset  the timezone offset in minutes, for example 0
00263         *                       (in most cases) or 30
00264         *
00265         * @see <a href="http://www.worldtimezone.com/faq.html">worldtimezone.com</a>
00266         */
00267         virtual void onTime(int32_t iPos, int32_t nHour, int32_t nMinute,
00268                 int32_t nSecond, int32_t nNano, int32_t nHourOffset,
00269                 int32_t nMinuteOffset) = 0;
00270 
00271         /**
00272         * Report that a time interval value has been encountered in the POF
00273         * stream.
00274         *
00275         * @param iPos      context-sensitive position information: property
00276         *                  index within a user type, array index within an
00277         *                  array, element counter within a collection, entry
00278         *                  counter within a map, -1 otherwise
00279         * @param cHours    the number of hours in the time interval
00280         * @param cMinutes  the number of minutes in the time interval, from 0
00281         *                  to 59 inclusive
00282         * @param cSeconds  the number of seconds in the time interval, from 0
00283         *                  to 59 inclusive
00284         * @param cNanos    the number of nanoseconds, from 0 to 999999999
00285         *                  inclusive
00286         */
00287         virtual void onTimeInterval(int32_t iPos, int32_t cHours,
00288                 int32_t cMinutes, int32_t cSeconds, int32_t cNanos) = 0;
00289 
00290         /**
00291         * Report that a date-time value has been encountered in the POF
00292         * stream.
00293         *
00294         * @param iPos     context-sensitive position information: property
00295         *                 index within a user type, array index within an
00296         *                 array, element counter within a collection, entry
00297         *                 counter within a map, -1 otherwise
00298         * @param nYear    the year number as defined by ISO8601
00299         * @param nMonth   the month number between 1 and 12 inclusive as
00300         *                 defined by ISO8601
00301         * @param nDay     the day number between 1 and 31 inclusive as
00302         *                 defined by ISO8601
00303         * @param nHour    the hour between 0 and 23 inclusive
00304         * @param nMinute  the minute value between 0 and 59 inclusive
00305         * @param nSecond  the second value between 0 and 59 inclusive (and
00306         *                 theoretically 60 for a leap-second)
00307         * @param nNano    the nanosecond value between 0 and 999999999
00308         *                 inclusive
00309         * @param fUTC     true if the time value is UTC or false if the time
00310         *                 value does not have an explicit time zone
00311         */
00312         virtual void onDateTime(int32_t iPos, int32_t nYear, int32_t nMonth,
00313                 int32_t nDay, int32_t nHour, int32_t nMinute, int32_t nSecond,
00314                 int32_t nNano, bool fUTC) = 0;
00315 
00316         /**
00317         * Report that a date-time value (with a timezone offset) has been
00318         * encountered in the POF stream.
00319         *
00320         * @param iPos           context-sensitive position information:
00321         *                       property index within a user type, array
00322         *                       index within an array, element counter within
00323         *                       a collection, entry counter within a map, -1
00324         *                       otherwise
00325         * @param nYear          the year number as defined by ISO8601
00326         * @param nMonth         the month number between 1 and 12 inclusive
00327         *                       as defined by ISO8601
00328         * @param nDay           the day number between 1 and 31 inclusive as
00329         *                       defined by ISO8601
00330         * @param nHour          the hour between 0 and 23 inclusive
00331         * @param nMinute        the minute value between 0 and 59 inclusive
00332         * @param nSecond        the second value between 0 and 59 inclusive
00333         *                       (and theoretically 60 for a leap-second)
00334         * @param nNano          the nanosecond value between 0 and 999999999
00335         *                       inclusive
00336         * @param nHourOffset    the timezone offset in hours from UTC, for
00337         *                       example 0 for BST, -5 for EST and 1 for CET
00338         * @param nMinuteOffset  the timezone offset in minutes, for example 0
00339         *                       (in most cases) or 30
00340         */
00341         virtual void onDateTime(int32_t iPos, int32_t nYear, int32_t nMonth,
00342                 int32_t nDay, int32_t nHour, int32_t nMinute, int32_t nSecond,
00343                 int32_t nNano, int32_t nHourOffset, int32_t nMinuteOffset) = 0;
00344 
00345         /**
00346         * Report that a day-time interval value has been encountered in the POF
00347         * stream.
00348         *
00349         * @param iPos      context-sensitive position information: property
00350         *                  index within a user type, array index within an
00351         *                  array, element counter within a collection, entry
00352         *                  counter within a map, -1 otherwise
00353         * @param cDays     the number of days in the day-time interval
00354         * @param cHours    the number of hours in the day-time interval, from
00355         *                  0 to 23 inclusive
00356         * @param cMinutes  the number of minutes in the day-time interval,
00357         *                  from 0 to 59 inclusive
00358         * @param cSeconds  the number of seconds in the day-time interval,
00359         *                  from 0 to 59 inclusive
00360         * @param cNanos    the number of nanoseconds in the day-time interval,
00361         *                  from 0 to 999999999 inclusive
00362         */
00363         virtual void onDayTimeInterval(int32_t iPos, int32_t cDays,
00364                 int32_t cHours, int32_t cMinutes, int32_t cSeconds,
00365                 int32_t cNanos) = 0;
00366 
00367         /**
00368         * Report that a collection of values has been encountered in the POF
00369         * stream.
00370         *
00371         * This method call will be followed by a separate call to an "on" or
00372         * "begin" method for each of the <tt>cElements</tt> elements in the
00373         * collection, and the collection extent will then be terminated by a
00374         * call to {@link #endComplexValue()}.
00375         *
00376         * @param iPos       context-sensitive position information: property
00377         *                   index within a user type, array index within an
00378         *                   array, element counter within a collection, entry
00379         *                   counter within a map, -1 otherwise
00380         * @param cElements  the exact number of values (elements) in the
00381         *                   collection
00382         */
00383         virtual void beginCollection(int32_t iPos, size32_t cElements) = 0;
00384 
00385         /**
00386         * Report that a uniform collection of values has been encountered in
00387         * the POF stream.
00388         *
00389         * This method call will be followed by a separate call to an "on" or
00390         * "begin" method for each of the <tt>cElements</tt> elements in the
00391         * collection, and the collection extent will then be terminated by a
00392         * call to {@link #endComplexValue()}.
00393         *
00394         * @param iPos       context-sensitive position information: property
00395         *                   index within a user type, array index within an
00396         *                   array, element counter within a collection, entry
00397         *                   counter within a map, -1 otherwise
00398         * @param cElements  the exact number of values (elements) in the
00399         *                   collection
00400         * @param nType      the type identifier for all of the values in the
00401         *                   uniform collection
00402         */
00403         virtual void beginUniformCollection(int32_t iPos, size32_t cElements,
00404                 int32_t nType) = 0;
00405 
00406         /**
00407         * Report that an array of values has been encountered in the POF
00408         * stream.
00409         * This method call will be followed by a separate call to an "on" or
00410         * "begin" method for each of the <tt>cElements</tt> elements in the
00411         * array, and the array extent will then be terminated by a call to
00412         * {@link #endComplexValue()}.
00413         *
00414         * @param iPos       context-sensitive position information: property
00415         *                   index within a user type, array index within an
00416         *                   array, element counter within a collection, entry
00417         *                   counter within a map, -1 otherwise
00418         * @param cElements  the exact number of values (elements) in the
00419         *                   array
00420         */
00421         virtual void beginArray(int32_t iPos, size32_t cElements) = 0;
00422 
00423         /**
00424         * Report that a uniform array of values has been encountered in the
00425         * POF stream.
00426         *
00427         * This method call will be followed by a separate call to an "on" or
00428         * "begin" method for each of the <tt>cElements</tt> elements in the
00429         * array, and the array extent will then be terminated by a call to
00430         * {@link #endComplexValue()}.
00431         *
00432         * @param iPos       context-sensitive position information: property
00433         *                   index within a user type, array index within an
00434         *                   array, element counter within a collection, entry
00435         *                   counter within a map, -1 otherwise
00436         * @param cElements  the exact number of values (elements) in the
00437         *                   array
00438         * @param nType      the type identifier for all of the values in the
00439         *                   uniform array
00440         */
00441         virtual void beginUniformArray(int32_t iPos, size32_t cElements,
00442                 int32_t nType) = 0;
00443 
00444         /**
00445         * Report that a sparse array of values has been encountered in the
00446         * POF stream.
00447         *
00448         * This method call will be followed by a separate call to an "on" or
00449         * "begin" method for present element in the sparse array (up to
00450         * <tt>cElements</tt> elements), and the array extent will then be
00451         * terminated by a call to {@link #endComplexValue()}.
00452         *
00453         * @param iPos       context-sensitive position information: property
00454         *                   index within a user type, array index within an
00455         *                   array, element counter within a collection, entry
00456         *                   counter within a map, -1 otherwise
00457         * @param cElements  the exact number of elements in the array, which
00458         *                   is greater than or equal to the number of values
00459         *                   in the sparse POF stream; in other words, the
00460         *                   number of values that will subsequently be
00461         *                   reported will not exceed this number
00462         */
00463         virtual void beginSparseArray(int32_t iPos, size32_t cElements) = 0;
00464 
00465         /**
00466         * Report that a uniform sparse array of values has been encountered
00467         * in the POF stream.
00468         *
00469         * This method call will be followed by a separate call to an "on" or
00470         * "begin" method for present element in the sparse array (up to
00471         * <tt>cElements</tt> elements), and the array extent will then be
00472         * terminated by a call to {@link #endComplexValue()}.
00473         *
00474         * @param iPos       context-sensitive position information: property
00475         *                   index within a user type, array index within an
00476         *                   array, element counter within a collection, entry
00477         *                   counter within a map, -1 otherwise
00478         * @param cElements  the exact number of elements in the array, which
00479         *                   is greater than or equal to the number of values
00480         *                   in the sparse POF stream; in other words, the
00481         *                   number of values that will subsequently be
00482         *                   reported will not exceed this number
00483         * @param nType      the type identifier for all of the values in the
00484         *                   uniform sparse array
00485         */
00486         virtual void beginUniformSparseArray(int32_t iPos, size32_t cElements,
00487                 int32_t nType) = 0;
00488 
00489         /**
00490         * Report that a map of key/value pairs has been encountered in the
00491         * POF stream.
00492         *
00493         * This method call will be followed by a separate call to an "on" or
00494         * "begin" method for each of the <tt>cElements</tt> elements in the
00495         * map, and the map extent will then be terminated by a call to
00496         * {@link #endComplexValue()}.
00497         *
00498         * @param iPos       context-sensitive position information: property
00499         *                   index within a user type, array index within an
00500         *                   array, element counter within a collection, entry
00501         *                   counter within a map, -1 otherwise
00502         * @param cElements  the exact number of key/value pairs (entries) in
00503         *                   the map
00504         */
00505         virtual void beginMap(int32_t iPos, size32_t cElements) = 0;
00506 
00507         /**
00508         * Report that a map of key/value pairs (with the keys being of a
00509         * uniform type) has been encountered in the POF stream.
00510         *
00511         * This method call will be followed by a separate call to an "on" or
00512         * "begin" method for each of the <tt>cElements</tt> elements in the
00513         * map, and the map extent will then be terminated by a call to
00514         * {@link #endComplexValue()}.
00515         *
00516         * @param iPos       context-sensitive position information: property
00517         *                   index within a user type, array index within an
00518         *                   array, element counter within a collection, entry
00519         *                   counter within a map, -1 otherwise
00520         * @param cElements  the exact number of key/value pairs (entries) in
00521         *                   the map
00522         * @param nTypeKeys  the type identifier for all of the keys in the
00523         *                   uniform-keys map
00524         */
00525         virtual void beginUniformKeysMap(int32_t iPos, size32_t cElements,
00526                 int32_t nTypeKeys) = 0;
00527 
00528         /**
00529         * Report that a map of key/value pairs (with the keys being of a
00530         * uniform type and the values being of a uniform type) has been
00531         * encountered in the POF stream.
00532         *
00533         * This method call will be followed by a separate call to an "on" or
00534         * "begin" method for each of the <tt>cElements</tt> elements in the
00535         * map, and the map extent will then be terminated by a call to
00536         * {@link #endComplexValue()}.
00537         *
00538         * @param iPos         context-sensitive position information:
00539         *                     property index within a user type, array index
00540         *                     within an array, element counter within a
00541         *                     collection, entry counter within a map, -1
00542         *                     otherwise
00543         * @param cElements    the exact number of key/value pairs (entries)
00544         *                     in the map
00545         * @param nTypeKeys    the type identifier for all of the keys in the
00546         *                     uniform map
00547         * @param nTypeValues  the type identifier for all of the values in
00548         *                     the uniform map
00549         */
00550         virtual void beginUniformMap(int32_t iPos, size32_t cElements,
00551                 int32_t nTypeKeys, int32_t nTypeValues) = 0;
00552 
00553         /**
00554         * Report that a value of a "user type" has been encountered in the
00555         * POF stream. A user type is analogous to a "class", and a value of a
00556         * user type is analogous to an "object".
00557         *
00558         * This method call will be followed by a separate call to an "on" or
00559         * "begin" method for each of the property values in the user type,
00560         * and the user type will then be terminated by a call to
00561         * {@link #endComplexValue()}.
00562         *
00563         * @param iPos         context-sensitive position information:
00564         *                     property index within a user type, array index
00565         *                     within an array, element counter within a
00566         *                     collection, entry counter within a map, -1
00567         *                     otherwise
00568         * @param nUserTypeId  the user type identifier,
00569         *                     <tt>(nUserTypeId &gt;= 0)</tt>
00570         * @param nVersionId   the version identifier for the user data type
00571         *                     data in the POF stream, <tt>(nVersionId &gt;=
00572         *                     0)</tt>
00573         */
00574         virtual void beginUserType(int32_t iPos, int32_t nUserTypeId,
00575                 int32_t nVersionId) = 0;
00576 
00577         /**
00578         * Signifies the termination of the current complex value. Complex
00579         * values are any of the collection, array, map and user types. For
00580         * each call to one of the "begin" methods, there will be a
00581         * corresponding call to this method, even if there were no contents
00582         * in the complex value.
00583         */
00584         virtual void endComplexValue() = 0;
00585     };
00586 
00587 COH_CLOSE_NAMESPACE3
00588 
00589 #endif // COH_POF_HANDLER_HPP
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.