Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/io/pof/PofHelper.hpp

    00001 /*
    00002 * PofHelper.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_HELPER_HPP
    00017 #define COH_POF_HELPER_HPP
    00018
    00019 #include "coherence/lang.ns"
    00020
    00021 #include "coherence/io/ReadBuffer.hpp"
    00022 #include "coherence/io/pof/PofConstants.hpp"
    00023 #include "coherence/io/pof/PofContext.hpp"
    00024 #include "coherence/io/pof/RawDate.hpp"
    00025 #include "coherence/io/pof/RawDateTime.hpp"
    00026 #include "coherence/io/pof/RawDayTimeInterval.hpp"
    00027 #include "coherence/io/pof/RawTime.hpp"
    00028 #include "coherence/io/pof/RawTimeInterval.hpp"
    00029 #include "coherence/io/pof/RawYearMonthInterval.hpp"
    00030 #include "coherence/util/AbstractMap.hpp"
    00031 #include "coherence/util/Binary.hpp"
    00032 #include "coherence/util/Collection.hpp"
    00033 #include "coherence/util/List.hpp"
    00034 #include "coherence/util/Set.hpp"
    00035
    00036 #include <limits>
    00037
    00038 COH_OPEN_NAMESPACE3(coherence,io,pof)
    00039
    00040 using coherence::io::ReadBuffer;
    00041 using coherence::util::AbstractMap;
    00042 using coherence::util::Binary;
    00043 using coherence::util::Collection;
    00044 using coherence::util::List;
    00045 using coherence::util::Set;
    00046
    00047
    00048 /**
    00049 * Collection of helper methods for POF streams.
    00050 *
    00051 * @author jh  2008.04.09
    00052 */
    00053 class COH_EXPORT PofHelper
    00054     : public abstract_spec<PofHelper,
    00055         extends<PofConstants> >
    00056     {
    00057     public:
    00058         /**
    00059         * Return an identifier that represents the C++ type of the specified
    00060         * object.
    00061         *
    00062         * @param v     an object to determine the type of
    00063         * @param vCtx  the PofContext used to determine if the object is an
    00064         *              instance of a valid user type; must not be NULL
    00065         *
    00066         * @return one of the {@link PofConstants} class <tt>C_*</tt>
    00067         *         constants
    00068         */
    00069         static int32_t getClassTypeId(Object::View v, PofContext::View vCtx);
    00070
    00071         /**
    00072         * Return an indentifier that represents the POF type of the specified
    00073         * class.
    00074         *
    00075         * @param vClass  the class; must not be NULL
    00076         * @param vCtx    the PofContext used to determine the type identifier
    00077         *                of a user type; must not be NULL
    00078         *
    00079         * @return one of the {@link PofConstants} class <tt>T_*</tt>
    00080         *         constants
    00081         *
    00082         * @throws IllegalArgumentException if the user type associated with
    00083         *         the given object is unknown to the specified PofContext
    00084         */
    00085         static int32_t getPofTypeId(Class::View vClass, PofContext::View vCtx);
    00086
    00087         /**
    00088         * Encode an int32_t value into one of the reserved single-byte
    00089         * combined type and value indicators.
    00090         *
    00091         * @param n  an int32_t between -1 and 22 inclusive
    00092         *
    00093         * @return the int32_t value that the int32_t is encoded as
    00094         */
    00095         static int32_t encodeTinyInt32(int32_t n);
    00096
    00097         /**
    00098         * Decode an int32_t value from one of the reserved single-byte
    00099         * combined type and value indicators.
    00100         *
    00101         * @param n  the int32_t value that the int32_t is encoded as
    00102         *
    00103         * @return an int32_t between -1 and 22 inclusive
    00104         */
    00105         static int32_t decodeTinyInt32(int32_t n);
    00106
    00107         /**
    00108         * Read a value of the specified encoding from the POF stream and
    00109         * convert it to a char16_t.
    00110         *
    00111         * @param hIn    the POF stream containing the value
    00112         * @param nType  the POF type of the value
    00113         *
    00114         * @return the POF value as an char
    00115         *
    00116         * @throws IOException if an I/O error occurs reading the POF stream,
    00117         *         or the POF value cannot be coerced to a char value
    00118         */
    00119         static char16_t readAsChar16(ReadBuffer::BufferInput::Handle hIn,
    00120                 int32_t nType);
    00121
    00122         /**
    00123         * Read a value of the specified encoding from the POF stream and
    00124         * convert it to an int32_t.
    00125         *
    00126         * @param hIn    the POF stream containing the value
    00127         * @param nType  the POF type of the value
    00128         *
    00129         * @return the POF value as an int32_t
    00130         *
    00131         * @throws IOException if an I/O error occurs reading the POF stream,
    00132         *         or the POF value cannot be coerced to an int32_t value
    00133         */
    00134         static int32_t readAsInt32(ReadBuffer::BufferInput::Handle hIn,
    00135                 int32_t nType);
    00136
    00137         /**
    00138         * Read a value of the specified encoding from the POF stream and
    00139         * convert it to an int64_t.
    00140         *
    00141         * @param hIn    the POF stream containing the value
    00142         * @param nType  the POF type of the value
    00143         *
    00144         * @return the POF value as an int64_t
    00145         *
    00146         * @throws IOException if an I/O error occurs reading the POF stream,
    00147         *         or the POF value cannot be coerced to an int64_t value
    00148         */
    00149         static int64_t readAsInt64(ReadBuffer::BufferInput::Handle hIn,
    00150                 int32_t nType);
    00151
    00152         /**
    00153         * Read a value of the specified encoding from the POF stream and
    00154         * convert it to a float32_t.
    00155         *
    00156         * @param hIn    the POF stream containing the value
    00157         * @param nType  the POF type of the value
    00158         *
    00159         * @return the POF value as a float32_t
    00160         *
    00161         * @throws IOException if an I/O error occurs reading the POF stream,
    00162         *         or the POF value cannot be coerced to a float32_t value
    00163         */
    00164         static float32_t readAsFloat32(ReadBuffer::BufferInput::Handle hIn,
    00165                 int32_t nType);
    00166
    00167         /**
    00168         * Read a value of the specified encoding from the POF stream and
    00169         * convert it to a float64_t.
    00170         *
    00171         * @param hIn    the POF stream containing the value
    00172         * @param nType  the POF type of the value
    00173         *
    00174         * @return the POF value as a float64_t
    00175         *
    00176         * @throws IOException if an I/O error occurs reading the POF stream,
    00177         *         or the POF value cannot be coerced to a float64_t value
    00178         */
    00179         static float64_t readAsFloat64(ReadBuffer::BufferInput::Handle hIn,
    00180                 int32_t nType);
    00181
    00182         /**
    00183         * Read a RawDate value from the passed BufferInput.
    00184         *
    00185         * @param hIn  the BufferInput object to read from
    00186         *
    00187         * @return the RawDate value
    00188         */
    00189         static RawDate::View readRawDate(
    00190                 ReadBuffer::BufferInput::Handle hIn);
    00191
    00192         /**
    00193         * Read a RawTime value from the passed BufferInput.
    00194         *
    00195         * @param hIn  the BufferInput object to read from
    00196         *
    00197         * @return the RawTime value
    00198         */
    00199         static RawTime::View readRawTime(
    00200                 ReadBuffer::BufferInput::Handle hIn);
    00201
    00202         /**
    00203         * Within the POF stream, skip the next POF value.
    00204         *
    00205         * @param hIn the BufferInput containing the POF stream
    00206         */
    00207         static void skipValue(ReadBuffer::BufferInput::Handle hIn);
    00208
    00209         /**
    00210         * Within the POF stream, skip the next POF value of the specified
    00211         * type.
    00212         *
    00213         * @param hIn    the BufferInput containing the POF stream
    00214         * @param nType  the type of the value to skip
    00215         */
    00216         static void skipUniformValue(ReadBuffer::BufferInput::Handle hIn,
    00217                 int32_t nType);
    00218
    00219         /**
    00220         * Skip the specified number of integers in the passed POF stream.
    00221         *
    00222         * @param hIn  the BufferInput containing the POF stream
    00223         * @param c    the number of integers to skip over
    00224         */
    00225         static void skipInts(ReadBuffer::BufferInput::Handle hIn, int32_t c);
    00226
    00227         /**
    00228         * Validate that the specified POF collection size as read from a POF
    00229         * stream is smaller than the largest value of the size32_t type, and if
    00230         * so, return the given size as a size32_t.
    00231         *
    00232         * @param cElements  the POF collection size
    00233         *
    00234         * @return the POF collection size as a size32_t
    00235         *
    00236         * @throws Exception if the given POF collection size is greater than
    00237         *         the largest value of the size32_t type
    00238         */
    00239         inline static size32_t validateIncomingSize(int32_t cElements)
    00240             {
    00241             COH_ENSURE(cElements >= 0);
    00242
    00243             size32_t nElements = (size32_t) cElements;
    00244             if (((int32_t) nElements) != cElements)
    00245                 {
    00246                 COH_THROW_STREAM (IllegalStateException,
    00247                         "incoming POF collection size overflow: " << cElements
    00248                         << " > " << std::numeric_limits<size32_t>::max());
    00249                 }
    00250             return nElements;
    00251             }
    00252
    00253         /**
    00254         * Validate that the specified Collection size is smaller than the
    00255         * largest value of the int32_t type, and if so, return the given size
    00256         * as an in32_t.
    00257         *
    00258         * @param cElements  the Collection size
    00259         *
    00260         * @return the Collection size as a int32_t
    00261         *
    00262         * @throws Exception if the given Collection size is greater than the
    00263         *         largest value of the int32_t type
    00264         */
    00265         inline static int32_t validateOutgoingSize(size32_t cElements)
    00266             {
    00267             int32_t nElements = (int32_t) cElements;
    00268             if (((size32_t) nElements) != cElements || nElements < 0)
    00269                 {
    00270                 COH_THROW_STREAM (IllegalStateException,
    00271                         "outgoing POF collection size overflow: " << cElements
    00272                         << " > " << Integer32::MAX_VALUE);
    00273                 }
    00274             return nElements;
    00275             }
    00276
    00277         /**
    00278         * Validate date information.
    00279         *
    00280         * @param nYear   the year number
    00281         * @param nMonth  the month number
    00282         * @param nDay    the day number
    00283         */
    00284         static void checkDate(int32_t nYear, int32_t nMonth, int32_t nDay);
    00285
    00286         /**
    00287         * Validate time information.
    00288         *
    00289         * @param nHour    the hour number
    00290         * @param nMinute  the minute number
    00291         * @param nSecond  the second number
    00292         * @param nNano    the nanosecond number
    00293         */
    00294         static void checkTime(int32_t nHour, int32_t nMinute, int32_t nSecond,
    00295                 int32_t nNano);
    00296
    00297         /**
    00298         * Check the specified timezone offset.
    00299         *
    00300         * @param nHourOffset    the hour offset
    00301         * @param nMinuteOffset  the minute offset
    00302         */
    00303         static void checkTimeZone(int32_t nHourOffset, int32_t nMinuteOffset);
    00304
    00305         /**
    00306         * Validate a time interval.
    00307         *
    00308         * @param cHours    the number of hours
    00309         * @param cMinutes  the number of minutes
    00310         * @param cSeconds  the number of seconds
    00311         * @param cNanos    the number of nanoseconds
    00312         */
    00313         static void checkTimeInterval(int32_t cHours, int32_t cMinutes,
    00314                 int32_t cSeconds, int32_t cNanos);
    00315
    00316         /**
    00317         * Validate a day-time interval.
    00318         *
    00319         * See http://www.builderau.com.au/architect/database/soa/SQL_basics_Datetime_and_interval_data_types/0,39024547,20269031,00.htm
    00320         *
    00321         * @param cDays     the number of days
    00322         * @param cHours    the number of hours
    00323         * @param cMinutes  the number of minutes
    00324         * @param cSeconds  the number of seconds
    00325         * @param cNanos    the number of nanoseconds
    00326         */
    00327         static void checkDayTimeInterval(int32_t cDays, int32_t cHours,
    00328                 int32_t cMinutes, int32_t cSeconds, int32_t cNanos);
    00329
    00330         /**
    00331         * Validate a year-month interval.
    00332         *
    00333         * @param cYears   the number of years
    00334         * @param cMonths  the number of months
    00335         */
    00336         static void checkYearMonthInterval(int32_t cYears, int32_t cMonths);
    00337
    00338         /**
    00339         * Format a date in the form YYYY-MM-DD.
    00340         *
    00341         * @param nYear   the year number
    00342         * @param nMonth  the month number
    00343         * @param nDay    the day number
    00344         */
    00345         static String::View formatDate(int32_t nYear, int32_t nMonth,
    00346                 int32_t nDay);
    00347
    00348         /**
    00349         * Format a time using the simplest applicable of the following
    00350         * formats:
    00351         * <ol>
    00352         * <li><tt>HH:MM</tt></li>
    00353         * <li><tt>HH:MM:SS</tt></li>
    00354         * <li><tt>HH:MM:SS.MMM</tt></li>
    00355         * <li><tt>HH:MM:SS.NNNNNNNNN</tt></li>
    00356         * </ol>
    00357         *
    00358         * @param nHour    the hour number
    00359         * @param nMinute  the minute number
    00360         * @param nSecond  the second number
    00361         * @param nNano    the nanosecond number
    00362         * @param fUTC     true for UTC, false for no time zone
    00363         *
    00364         * @return a time String
    00365         */
    00366         static String::View formatTime(int32_t nHour, int32_t nMinute,
    00367                 int32_t nSecond, int32_t nNano, bool fUTC);
    00368
    00369         /**
    00370         * Format a time using the simplest applicable of the following
    00371         * formats:
    00372         * <ol>
    00373         * <li><tt>HH:MM\xB1HH:MM</tt></li>
    00374         * <li><tt>HH:MM:SS\xB1HH:MM</tt></li>
    00375         * <li><tt>HH:MM:SS.MMM\xB1HH:MM</tt></li>
    00376         * <li><tt>HH:MM:SS.NNNNNNNNN\xB1HH:MM</tt></li>
    00377         * </ol>
    00378         *
    00379         * @param nHour          the hour number
    00380         * @param nMinute        the minute number
    00381         * @param nSecond        the second number
    00382         * @param nNano          the nanosecond number
    00383         * @param nHourOffset    the timezone offset in hours
    00384         * @param nMinuteOffset  the timezone offset in minutes
    00385         *
    00386         * @return a time String
    00387         */
    00388         static String::View formatTime(int32_t nHour, int32_t nMinute,
    00389                 int32_t nSecond, int32_t nNano, int32_t nHourOffset,
    00390                 int32_t nMinuteOffset);
    00391
    00392         /**
    00393         * Write a date value to a BufferOutput object.
    00394         *
    00395         * @param hOut    the BufferOutput to write to
    00396         * @param nYear   the year number as defined by ISO8601
    00397         * @param nMonth  the month number between 1 and 12 inclusive as
    00398         *                defined by ISO8601
    00399         * @param nDay    the day number between 1 and 31 inclusive as defined
    00400         *                by ISO8601
    00401         *
    00402         * @throws IOException thrown if the passed BufferOutput object throws
    00403         *         an IOException while the value is being written to it
    00404         */
    00405         static void writeDate(WriteBuffer::BufferOutput::Handle hOut,
    00406                 int32_t nYear, int32_t nMonth, int32_t nDay);
    00407
    00408         /**
    00409         * Write a time value to a BufferOutput object.
    00410         *
    00411         * @param hOut          the BufferOutput to write to
    00412         * @param nHour         the hour between 0 and 23 inclusive
    00413         * @param nMinute       the minute value between 0 and 59 inclusive
    00414         * @param nSecond       the second value between 0 and 59 inclusive
    00415         *                      (and theoretically 60 for a leap-second)
    00416         * @param nNano         the nanosecond value between 0 and 999999999
    00417         *                      inclusive
    00418         * @param nTimeZoneType 0 if the time value does not have an explicit
    00419         *                      time zone, 1 if the time value is UTC and 2 if
    00420         *                      the time zone has an explicit hour and minute
    00421         *                      offset
    00422         * @param nHourOffset   the timezone offset in hours from UTC, for
    00423         *                      example 0 for BST, -5 for EST and 1 for CET
    00424         * @param nMinuteOffset the timezone offset in minutes, for example 0
    00425         *                      (in most cases) or 30
    00426         *
    00427         * @throws IOException thrown if the passed BufferOutput object throws
    00428         *         an IOException while the value is being written to it
    00429         */
    00430         static void writeTime(WriteBuffer::BufferOutput::Handle hOut,
    00431                 int32_t nHour, int32_t nMinute, int32_t nSecond,
    00432                 int32_t nNano, int32_t nTimeZoneType, int32_t nHourOffset,
    00433                 int32_t nMinuteOffset);
    00434
    00435
    00436     // ----- inner class: WriteableEntrySetMap ------------------------------
    00437
    00438     public:
    00439         /**
    00440         * Immutable Map implementation backed by a Set of Map::Entry objects.
    00441         *
    00442         * @author jh  2008.05.05
    00443         */
    00444         class WriteableEntrySetMap
    00445             : public class_spec<WriteableEntrySetMap,
    00446                 extends<AbstractMap> >
    00447             {
    00448             friend class factory<WriteableEntrySetMap>;
    00449
    00450             // ----- constructors ---------------------------------------
    00451
    00452             protected:
    00453                 /**
    00454                 * Construct a new WriteableEntrySetMap that is backed by the
    00455                 * given Set of Map::Entry objects.
    00456                 *
    00457                 * @param vSetEntries  a Set of Map::Entry objects in the new
    00458                 *                     WriteableEntrySetMap; must not be NULL
    00459                 */
    00460                 WriteableEntrySetMap(Set::View vSetEntries);
    00461
    00462             // ----- Map interface --------------------------------------
    00463
    00464             public:
    00465                 /**
    00466                 * {@inheritDoc}
    00467                 */
    00468                 virtual Object::Holder put(Object::View vKey,
    00469                         Object::Holder ohValue);
    00470
    00471                 /**
    00472                 * {@inheritDoc}
    00473                 */
    00474                 virtual Object::Holder remove(Object::View vKey);
    00475
    00476                 /**
    00477                 * {@inheritDoc}
    00478                 */
    00479                 virtual void clear();
    00480
    00481                 /**
    00482                 * {@inheritDoc}
    00483                 */
    00484                 virtual Set::Handle entrySet();
    00485
    00486                 /**
    00487                 * {@inheritDoc}
    00488                 */
    00489                 virtual Set::View entrySet() const;
    00490
    00491             // ----- data members ---------------------------------------
    00492
    00493             protected:
    00494                 /**
    00495                 * The backing Set of Map::Entry objects.
    00496                 */
    00497                 FinalView<Set> m_vSetEntries;
    00498             };
    00499
    00500
    00501     // ----- inner class: ReadableEntrySetMap -------------------------------
    00502
    00503     public:
    00504         /**
    00505         * Map implementation backed by a List of Map.Entry objects.
    00506         *
    00507         * @author jh  2008.05.05
    00508         */
    00509         class ReadableEntrySetMap
    00510             : public class_spec<ReadableEntrySetMap,
    00511                 extends<AbstractMap> >
    00512             {
    00513             friend class factory<ReadableEntrySetMap>;
    00514
    00515             // ----- constructors ---------------------------------------
    00516
    00517             protected:
    00518                 /**
    00519                 * Construct a new ReadableEntrySetMap.
    00520                 */
    00521                 ReadableEntrySetMap();
    00522
    00523             // ----- Map interface --------------------------------------
    00524
    00525             public:
    00526                 /**
    00527                 * {@inheritDoc}
    00528                 */
    00529                 virtual Object::Holder put(Object::View vKey,
    00530                         Object::Holder ohValue);
    00531
    00532                 /**
    00533                 * {@inheritDoc}
    00534                 */
    00535                 virtual Object::Holder remove(Object::View vKey);
    00536
    00537                 /**
    00538                 * {@inheritDoc}
    00539                 */
    00540                 virtual void clear();
    00541
    00542                 /**
    00543                 * {@inheritDoc}
    00544                 */
    00545                 virtual Set::Handle entrySet();
    00546
    00547                 /**
    00548                 * {@inheritDoc}
    00549                 */
    00550                 virtual Set::View entrySet() const;
    00551
    00552             // ----- data members ---------------------------------------
    00553
    00554             protected:
    00555                 /**
    00556                 * The backing List of Map::Entry objects.
    00557                 */
    00558                 mutable FinalHandle<List> m_hListEntries;
    00559             };
    00560
    00561
    00562     // ----- constants ------------------------------------------------------
    00563
    00564     public:
    00565         /**
    00566         * @return an empty array of bool.
    00567         */
    00568         static Array<bool>::Handle getEmptyBooleanArray();
    00569
    00570         /**
    00571         * @return an empty array of octet_t.
    00572         */
    00573         static Array<octet_t>::Handle getEmptyOctetArray();
    00574
    00575         /**
    00576         * @return an empty array of char16_t.
    00577         */
    00578         static Array<char16_t>::Handle getEmptyChar16Array();
    00579
    00580         /**
    00581         * @return an empty array of int16_t.
    00582         */
    00583         static Array<int16_t>::Handle getEmptyInt16Array();
    00584
    00585         /**
    00586         * @return an empty array of int32_t.
    00587         */
    00588         static Array<int32_t>::Handle getEmptyInt32Array();
    00589
    00590         /**
    00591         * @return an empty array of int64_t.
    00592         */
    00593         static Array<int64_t>::Handle getEmptyInt64Array();
    00594
    00595         /**
    00596         * @return an empty array of float32_t.
    00597         */
    00598         static Array<float32_t>::Handle getEmptyFloat32Array();
    00599
    00600         /**
    00601         * @return an empty array of float64_t.
    00602         */
    00603         static Array<float64_t>::Handle getEmptyFloat64Array();
    00604
    00605         /**
    00606         * @return an empty array of objects.
    00607         */
    00608         static ObjectArray::Handle getEmptyObjectArray();
    00609
    00610         /**
    00611         * A zero-length Binary.
    00612         */
    00613         static Binary::View getEmptyBinary();
    00614
    00615         /**
    00616         * @return an empty and immutable Collection
    00617         */
    00618         static Collection::View getEmptyCollection();
    00619     };
    00620
    00621 COH_CLOSE_NAMESPACE3
    00622
    00623 #endif // COH_POF_HELPER_HPP

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