00001 /* 00002 * PofReader.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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 * @param ha the optional <tt>ObjectArray</tt> to use to store 00440 * the values, or to use as a typed template for 00441 * creating an array to store the values; may be 00442 * <tt>NULL</tt> 00443 * 00444 * @return an <tt>ObjectArray</tt> of object values, or <tt>NULL</tt> 00445 * if no <tt>ObjectArray</tt> is passed and there is no array 00446 * data in the POF stream 00447 * 00448 * @throws coherence::lang::IllegalArgumentException if the property 00449 * index is invalid, or is less than or equal to the index of 00450 * the previous property read from the POF stream 00451 * @throws coherence::io::IOException if an I/O error occurs 00452 */ 00453 virtual ObjectArray::Handle readObjectArray(int32_t iProp, 00454 ObjectArray::Handle ha = NULL) = 0; 00455 00456 00457 // ----- collection support --------------------------------------------- 00458 00459 public: 00460 /** 00461 * Read a <tt>LongArray</tt> of object values from the POF stream. 00462 * 00463 * @param iProp the property index to read 00464 * @param hla the optional <tt>LongArray</tt> to use to store the 00465 * values; may be <tt>NULL</tt> 00466 * 00467 * @return a <tt>LongArray</tt> of object values, or <tt>NULL</tt> if 00468 * no <tt>LongArray</tt> is passed and there is no key/value 00469 * data available in the POF stream 00470 * 00471 * @throws coherence::lang::IllegalArgumentException if the property 00472 * index is invalid, or is less than or equal to the index of 00473 * the previous property read from the POF stream 00474 * @throws coherence::io::IOException if an I/O error occurs 00475 */ 00476 virtual LongArray::View readLongArray(int32_t iProp, 00477 LongArray::Handle hla = NULL) = 0; 00478 00479 /** 00480 * Read a <tt>Collection</tt> of object values from the POF stream. 00481 * 00482 * @param iProp the property index to read 00483 * @param hCol the optional <tt>Collection</tt> to use to store the 00484 * values; may be <tt>NULL</tt> 00485 * 00486 * @return a <tt>Collection</tt> of object values, or <tt>NULL</tt> if 00487 * no <tt>Collection</tt> is passed and there is no collection 00488 * data available in the POF stream 00489 * 00490 * @throws coherence::lang::IllegalArgumentException if the property 00491 * index is invalid, or is less than or equal to the index of 00492 * the previous property read from the POF stream 00493 * @throws coherence::io::IOException if an I/O error occurs 00494 */ 00495 virtual Collection::View readCollection(int32_t iProp, 00496 Collection::Handle hCol = NULL) = 0; 00497 00498 /** 00499 * Read a <tt>Map</tt> of key/value pairs from the POF stream. 00500 * 00501 * @param iProp the property index to read 00502 * @param hMap the optional <tt>Map</tt> to initialize; the handle 00503 * may be <tt>NULL</tt> 00504 * 00505 * @return a <tt>Map</tt> of key/value pairs, or <tt>NULL</tt> if no 00506 * <tt>Map</tt> is passed and there is no key/value data in 00507 * the POF stream 00508 * 00509 * @throws coherence::lang::IllegalArgumentException if the property 00510 * index is invalid, or is less than or equal to the index of 00511 * the previous property read from the POF stream 00512 * @throws coherence::io::IOException if an I/O error occurs 00513 */ 00514 virtual Map::View readMap(int32_t iProp, Map::Handle hMap = NULL) = 0; 00515 00516 00517 // ----- POF user type support ------------------------------------------ 00518 00519 public: 00520 /** 00521 * Return the PofContext object used by this PofReader to deserialize 00522 * user types from a POF stream. 00523 * 00524 * @return the PofContext object that contains user type meta-data 00525 */ 00526 virtual PofContext::View getPofContext() const = 0; 00527 00528 /** 00529 * Configure the PofContext object used by this PofReader to 00530 * deserialize user types from a POF stream. 00531 * 00532 * Note: this is an advanced method that should be used with care. For 00533 * example, if this method is being used to switch to another 00534 * PofContext mid-POF stream, it is important to eventually restore 00535 * the original PofContext. For example: 00536 * <pre> 00537 * PofContext::View vCtxOrig = hReader->getPofContext(); 00538 * 00539 * // switch to another PofContext 00540 * PofContext::View vCtxNew = ...; 00541 * hReader->setContext(vCtxNew); 00542 * 00543 * // read POF data using the reader 00544 * ... 00545 * 00546 * // restore the original PofContext 00547 * hReader->setPofContext(vCtxOrig); 00548 * </pre> 00549 * 00550 * @param vCtx the new PofContext; must not be <tt>NULL</tt> 00551 */ 00552 virtual void setPofContext(PofContext::View vCtx) = 0; 00553 00554 /** 00555 * Determine the user type that is currently being parsed. 00556 * 00557 * @return the user type information, or -1 if the PofReader is not 00558 * currently parsing a user type 00559 */ 00560 virtual int32_t getUserTypeId() const = 0; 00561 00562 /** 00563 * Determine the version identifier of the user type that is currently 00564 * being parsed. 00565 * 00566 * @return the integer version ID read from the POF stream; always 00567 * non-negative 00568 * 00569 * @throws coherence::lang::IllegalStateException if no user type is 00570 * being parsed 00571 */ 00572 virtual int32_t getVersionId() const = 0; 00573 00574 /** 00575 * Register an identity for a newly created user type instance. 00576 * 00577 * If identity/reference types are enabled, an identity is used to 00578 * uniquely identify a user type instance within a POF stream. The 00579 * identity immediately proceeds the instance value in the POF stream and 00580 * can be used later in the stream to reference the instance. 00581 * 00582 * PofSerializer implementations must call this method with the user 00583 * type instance instantiated during deserialization prior to reading any 00584 * properties of the instance which are user type instances themselves. 00585 * 00586 * @param oh the object to register the identity for 00587 * 00588 * @see PofSerializer::deserialize(PofReaderHandle) 00589 * 00590 * @since Coherence 3.7.1 00591 */ 00592 virtual void registerIdentity(Object::Holder oh) = 0; 00593 00594 /** 00595 * Obtain a PofReader that can be used to read a set of properties from a 00596 * single property of the current user type. The returned PofReader is 00597 * only valid from the time that it is returned until the next call is 00598 * made to this PofReader. 00599 * 00600 * @param iProp the property index to read from 00601 * 00602 * @return a PofReader that reads its contents from a single property of 00603 * this PofReader 00604 * 00605 * @throws coherence::lang::IllegalArgumentException if the property index 00606 * is invalid, or is less than or equal to the index of the previous 00607 * property read from the POF stream 00608 * @throws coherence::lang::IllegalStateException if no user type is 00609 * being parsed 00610 * @throws coherence::io::IOException if an I/O error occurs 00611 * 00612 * @since Coherence 3.6 00613 */ 00614 virtual PofReader::Handle createNestedPofReader(int32_t iProp) = 0; 00615 00616 /** 00617 * Read all remaining indexed properties of the current user type from 00618 * the POF stream. As part of reading in a user type, this method must 00619 * be called by the PofSerializer that is reading the user type, or 00620 * the read position within the POF stream will be corrupted. 00621 * 00622 * Subsequent calls to the various <tt>readXYZ</tt> methods of this 00623 * interface will fail after this method is called. 00624 * 00625 * @return a buffer containing zero or more indexed properties in 00626 * binary POF encoded form 00627 * 00628 * @throws coherence::lang::IllegalStateException if no user type is 00629 * being parsed 00630 * @throws coherence::io::IOException if an I/O error occurs 00631 */ 00632 virtual Binary::View readRemainder() = 0; 00633 }; 00634 00635 COH_CLOSE_NAMESPACE3 00636 00637 #endif // COH_POF_READER_HPP