00001 /* 00002 * PofReader.hpp 00003 * 00004 * Copyright (c) 2000, 2016, 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, or zero if no 00063 * value was available in the POF stream 00064 * 00065 * @throws IllegalStateException if the POF 00066 * stream has already advanced past the desired property 00067 * @throws 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, or zero if no 00077 * value was available in the POF stream 00078 * 00079 * @throws IllegalStateException if the POF 00080 * stream has already advanced past the desired property 00081 * @throws 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>wchar16_t</tt> value, or zero if no value was 00092 * available in the POF stream 00093 * 00094 * @throws IllegalStateException if the POF 00095 * stream has already advanced past the desired property 00096 * @throws IOException if an I/O error occurs 00097 */ 00098 virtual wchar16_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, or zero if no value 00106 * was available in the POF stream 00107 * 00108 * @throws IllegalStateException if the POF 00109 * stream has already advanced past the desired property 00110 * @throws 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, or zero if no value 00120 * was available in the POF stream 00121 * 00122 * @throws IllegalStateException if the POF 00123 * stream has already advanced past the desired property 00124 * @throws 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, or zero if no value 00134 * was available in the POF stream 00135 * 00136 * @throws IllegalStateException if the POF 00137 * stream has already advanced past the desired property 00138 * @throws 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, or zero if no value 00148 * was available in the POF stream 00149 * 00150 * @throws IllegalStateException if the POF 00151 * stream has already advanced past the desired property 00152 * @throws 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, or zero if no value 00162 * was available in the POF stream 00163 * 00164 * @throws IllegalStateException if the POF 00165 * stream has already advanced past the desired property 00166 * @throws 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 IllegalStateException if the POF 00183 * stream has already advanced past the desired property 00184 * @throws IOException if an I/O error occurs 00185 */ 00186 virtual Array<bool>::Handle readBooleanArray(int32_t iProp) = 0; 00187 00188 /** 00189 * Read an octet array property from the POF stream. 00190 * 00191 * @param iProp the property index to read 00192 * 00193 * @return the <tt>octet_t</tt> array property value, or <tt>NULL</tt> 00194 * if no value was available in the POF stream 00195 * 00196 * @throws IllegalStateException if the POF 00197 * stream has already advanced past the desired property 00198 * @throws IOException if an I/O error occurs 00199 */ 00200 virtual Array<octet_t>::Handle readOctetArray(int32_t iProp) = 0; 00201 00202 /** 00203 * Read a 16-bit Unicode character array property from the POF stream. 00204 * 00205 * @param iProp the property index to read 00206 * 00207 * @return the <tt>wchar16_t</tt> array property value, or 00208 * <tt>NULL</tt> if no value was available in the POF stream 00209 * 00210 * @throws IllegalStateException if the POF 00211 * stream has already advanced past the desired property 00212 * @throws IOException if an I/O error occurs 00213 */ 00214 virtual Array<wchar16_t>::Handle readChar16Array(int32_t iProp) = 0; 00215 00216 /** 00217 * Read a 16-bit integer array property from the POF stream. 00218 * 00219 * @param iProp the property index to read 00220 * 00221 * @return the <tt>int16_t</tt> array property value, or <tt>NULL</tt> 00222 * if no value was available in the POF stream 00223 * 00224 * @throws IllegalStateException if the POF 00225 * stream has already advanced past the desired property 00226 * @throws IOException if an I/O error occurs 00227 */ 00228 virtual Array<int16_t>::Handle readInt16Array(int32_t iProp) = 0; 00229 00230 /** 00231 * Read a 32-bit integer array property from the POF stream. 00232 * 00233 * @param iProp the property index to read 00234 * 00235 * @return the <tt>int32_t</tt> array property value, or <tt>NULL</tt> 00236 * if no value was available in the POF stream 00237 * 00238 * @throws IllegalStateException if the POF 00239 * stream has already advanced past the desired property 00240 * @throws IOException if an I/O error occurs 00241 */ 00242 virtual Array<int32_t>::Handle readInt32Array(int32_t iProp) = 0; 00243 00244 /** 00245 * Read a 64-bit integer array property from the POF stream. 00246 * 00247 * @param iProp the property index to read 00248 * 00249 * @return the <tt>int64_t</tt> array property value, or <tt>NULL</tt> 00250 * if no value was available in the POF stream 00251 * 00252 * @throws IllegalStateException if the POF 00253 * stream has already advanced past the desired property 00254 * @throws IOException if an I/O error occurs 00255 */ 00256 virtual Array<int64_t>::Handle readInt64Array(int32_t iProp) = 0; 00257 00258 /** 00259 * Read a a 32-bit floating-point array property from the POF stream. 00260 * 00261 * @param iProp the property index to read 00262 * 00263 * @return the <tt>float32_t</tt> array property value, or 00264 * <tt>NULL</tt> if no value was available in the POF stream 00265 * 00266 * @throws IllegalStateException if the POF 00267 * stream has already advanced past the desired property 00268 * @throws IOException if an I/O error occurs 00269 */ 00270 virtual Array<float32_t>::Handle readFloat32Array(int32_t iProp) = 0; 00271 00272 /** 00273 * Read a a 64-bit floating-point array property from the POF stream. 00274 * 00275 * @param iProp the property index to read 00276 * 00277 * @return the <tt>float64_t</tt> array property value, or 00278 * <tt>NULL</tt> if no value was available in the POF stream 00279 * 00280 * @throws IllegalStateException if the POF 00281 * stream has already advanced past the desired property 00282 * @throws IOException if an I/O error occurs 00283 */ 00284 virtual Array<float64_t>::Handle readFloat64Array(int32_t iProp) = 0; 00285 00286 00287 // ----- object value support ------------------------------------------- 00288 00289 public: 00290 /** 00291 * Read a <tt>Binary</tt> property from the POF stream. 00292 * 00293 * @param iProp the property index to read 00294 * 00295 * @return the <tt>Binary</tt> property value, or <tt>NULL</tt> if no 00296 * value was available in the POF stream 00297 * 00298 * @throws IllegalStateException if the POF 00299 * stream has already advanced past the desired property 00300 * @throws IOException if an I/O error occurs 00301 */ 00302 virtual Binary::View readBinary(int32_t iProp) = 0; 00303 00304 /** 00305 * Read a <tt>String</tt> property from the POF stream. 00306 * 00307 * @param iProp the property index to read 00308 * 00309 * @return the <tt>String</tt> property value, or <tt>NULL</tt> if no 00310 * value was available in the POF stream 00311 * 00312 * @throws IllegalStateException if the POF 00313 * stream has already advanced past the desired property 00314 * @throws IOException if an I/O error occurs 00315 */ 00316 virtual String::View readString(int32_t iProp) = 0; 00317 00318 /** 00319 * Read a {@link RawDate} property from the POF stream. 00320 * 00321 * @param iProp the property index to read 00322 * 00323 * @return the <tt>RawDate</tt> property value, or <tt>NULL</tt> if no 00324 * value was available in the POF stream 00325 * 00326 * @throws IllegalStateException if the POF 00327 * stream has already advanced past the desired property 00328 * @throws IOException if an I/O error occurs 00329 */ 00330 virtual RawDate::View readRawDate(int32_t iProp) = 0; 00331 00332 /** 00333 * Read a {@link RawTime} property from the POF stream. 00334 * 00335 * @param iProp the property index to read 00336 * 00337 * @return the <tt>RawTime</tt> property value, or <tt>NULL</tt> if no 00338 * value was available in the POF stream 00339 * 00340 * @throws IllegalStateException if the POF 00341 * stream has already advanced past the desired property 00342 * @throws IOException if an I/O error occurs 00343 */ 00344 virtual RawTime::View readRawTime(int32_t iProp) = 0; 00345 00346 /** 00347 * Read a {@link RawDateTime} property from the POF stream. 00348 * 00349 * @param iProp the property index to read 00350 * 00351 * @return the <tt>RawDateTime</tt> property value, or <tt>NULL</tt> 00352 * if no value was available in the POF stream 00353 * 00354 * @throws IllegalStateException if the POF 00355 * stream has already advanced past the desired property 00356 * @throws IOException if an I/O error occurs 00357 */ 00358 virtual RawDateTime::View readRawDateTime(int32_t iProp) = 0; 00359 00360 /** 00361 * Read a {@link RawYearMonthInterval} property from the POF stream. 00362 * 00363 * @param iProp the property index to read 00364 * 00365 * @return the <tt>RawYearMonthInterval</tt> property value, or 00366 * <tt>NULL</tt> if no value was available in the POF stream 00367 * 00368 * @throws IllegalStateException if the POF 00369 * stream has already advanced past the desired property 00370 * @throws IOException if an I/O error occurs 00371 */ 00372 virtual RawYearMonthInterval::View readRawYearMonthInterval( 00373 int32_t iProp) = 0; 00374 00375 /** 00376 * Read a {@link RawTimeInterval} property from the POF stream. 00377 * 00378 * @param iProp the property index to read 00379 * 00380 * @return the <tt>RawTimeInterval</tt> property value, or 00381 * <tt>NULL</tt> if no value was available in the POF stream 00382 * 00383 * @throws IllegalStateException if the POF 00384 * stream has already advanced past the desired property 00385 * @throws IOException if an I/O error occurs 00386 */ 00387 virtual RawTimeInterval::View readRawTimeInterval(int32_t iProp) = 0; 00388 00389 /** 00390 * Read a {@link RawDayTimeInterval} property from the POF stream. 00391 * 00392 * @param iProp the property index to read 00393 * 00394 * @return the <tt>RawDayTimeInterval</tt> property value, or 00395 * <tt>NULL</tt> if no value was available in the POF stream 00396 * 00397 * @throws IllegalStateException if the POF 00398 * stream has already advanced past the desired property 00399 * @throws IOException if an I/O error occurs 00400 */ 00401 virtual RawDayTimeInterval::View readRawDayTimeInterval(int32_t iProp) = 0; 00402 00403 /** 00404 * Read a property of any type, including a user type, from the POF 00405 * stream. 00406 * 00407 * @param iProp the property index to read 00408 * 00409 * @return the Object value, or <tt>NULL</tt> if no value was 00410 * available in the POF stream 00411 * 00412 * @throws IllegalStateException if the POF 00413 * stream has already advanced past the desired property 00414 * @throws IOException if an I/O error occurs 00415 */ 00416 virtual Object::Holder readObject(int32_t iProp) = 0; 00417 00418 /** 00419 * Read an <tt>ObjectArray</tt> property from the POF stream. 00420 * 00421 * @param iProp the property index to read 00422 * @param ha the optional <tt>ObjectArray</tt> to use to store 00423 * the values, or to use as a typed template for 00424 * creating an array to store the values; may be 00425 * <tt>NULL</tt> 00426 * 00427 * @return an <tt>ObjectArray</tt> of object values, or <tt>NULL</tt> 00428 * if no <tt>ObjectArray</tt> is passed and there is no array 00429 * data in the POF stream 00430 * 00431 * @throws IllegalStateException if the POF 00432 * stream has already advanced past the desired property 00433 * @throws IOException if an I/O error occurs 00434 */ 00435 virtual ObjectArray::Handle readObjectArray(int32_t iProp, 00436 ObjectArray::Handle ha = NULL) = 0; 00437 00438 00439 // ----- collection support --------------------------------------------- 00440 00441 public: 00442 /** 00443 * Read a <tt>LongArray</tt> of object values from the POF stream. 00444 * 00445 * @param iProp the property index to read 00446 * @param hla the optional <tt>LongArray</tt> to use to store the 00447 * values; may be <tt>NULL</tt> 00448 * 00449 * @return a <tt>LongArray</tt> of object values, or <tt>NULL</tt> if 00450 * no <tt>LongArray</tt> is passed and there is no key/value 00451 * data available in the POF stream 00452 * 00453 * @throws IllegalStateException if the POF 00454 * stream has already advanced past the desired property 00455 * @throws IOException if an I/O error occurs 00456 */ 00457 virtual LongArray::View readLongArray(int32_t iProp, 00458 LongArray::Handle hla = NULL) = 0; 00459 00460 /** 00461 * Read a <tt>Collection</tt> of object values from the POF stream. 00462 * 00463 * @param iProp the property index to read 00464 * @param hCol the optional <tt>Collection</tt> to use to store the 00465 * values; may be <tt>NULL</tt> 00466 * 00467 * @return a <tt>Collection</tt> of object values, or <tt>NULL</tt> if 00468 * no <tt>Collection</tt> is passed and there is no collection 00469 * data available in the POF stream 00470 * 00471 * @throws IllegalStateException if the POF 00472 * stream has already advanced past the desired property 00473 * @throws IOException if an I/O error occurs 00474 */ 00475 virtual Collection::View readCollection(int32_t iProp, 00476 Collection::Handle hCol = NULL) = 0; 00477 00478 /** 00479 * Read a <tt>Map</tt> of key/value pairs from the POF stream. 00480 * 00481 * @param iProp the property index to read 00482 * @param hMap the optional <tt>Map</tt> to initialize; the handle 00483 * may be <tt>NULL</tt> 00484 * 00485 * @return a <tt>Map</tt> of key/value pairs, or <tt>NULL</tt> if no 00486 * <tt>Map</tt> is passed and there is no key/value data in 00487 * the POF stream 00488 * 00489 * @throws IllegalStateException if the POF 00490 * stream has already advanced past the desired property 00491 * @throws IOException if an I/O error occurs 00492 */ 00493 virtual Map::View readMap(int32_t iProp, Map::Handle hMap = NULL) = 0; 00494 00495 00496 // ----- POF user type support ------------------------------------------ 00497 00498 public: 00499 /** 00500 * Return the PofContext object used by this PofReader to deserialize 00501 * user types from a POF stream. 00502 * 00503 * @return the PofContext object that contains user type meta-data 00504 */ 00505 virtual PofContext::View getPofContext() const = 0; 00506 00507 /** 00508 * Configure the PofContext object used by this PofReader to 00509 * deserialize user types from a POF stream. 00510 * 00511 * Note: this is an advanced method that should be used with care. For 00512 * example, if this method is being used to switch to another 00513 * PofContext mid-POF stream, it is important to eventually restore 00514 * the original PofContext. For example: 00515 * <pre> 00516 * PofContext::View vCtxOrig = hReader->getPofContext(); 00517 * 00518 * // switch to another PofContext 00519 * PofContext::View vCtxNew = ...; 00520 * hReader->setContext(vCtxNew); 00521 * 00522 * // read POF data using the reader 00523 * ... 00524 * 00525 * // restore the original PofContext 00526 * hReader->setPofContext(vCtxOrig); 00527 * </pre> 00528 * 00529 * @param vCtx the new PofContext; must not be <tt>NULL</tt> 00530 */ 00531 virtual void setPofContext(PofContext::View vCtx) = 0; 00532 00533 /** 00534 * Determine the user type that is currently being parsed. 00535 * 00536 * @return the user type information, or -1 if the PofReader is not 00537 * currently parsing a user type 00538 */ 00539 virtual int32_t getUserTypeId() const = 0; 00540 00541 /** 00542 * Determine the version identifier of the user type that is currently 00543 * being parsed. 00544 * 00545 * @return the integer version ID read from the POF stream; always 00546 * non-negative 00547 * 00548 * @throws IllegalStateException if no user type is 00549 * being parsed 00550 */ 00551 virtual int32_t getVersionId() const = 0; 00552 00553 /** 00554 * Register an identity for a newly created user type instance. 00555 * 00556 * If identity/reference types are enabled, an identity is used to 00557 * uniquely identify a user type instance within a POF stream. The 00558 * identity immediately proceeds the instance value in the POF stream and 00559 * can be used later in the stream to reference the instance. 00560 * 00561 * PofSerializer implementations must call this method with the user 00562 * type instance instantiated during deserialization prior to reading any 00563 * properties of the instance which are user type instances themselves. 00564 * 00565 * @param oh the object to register the identity for 00566 * 00567 * @see PofSerializer::deserialize(PofReaderHandle) 00568 * 00569 * @since Coherence 3.7.1 00570 */ 00571 virtual void registerIdentity(Object::Holder oh) = 0; 00572 00573 /** 00574 * Obtain a PofReader that can be used to read a set of properties from a 00575 * single property of the current user type. The returned PofReader is 00576 * only valid from the time that it is returned until the next call is 00577 * made to this PofReader. 00578 * 00579 * @param iProp the property index to read from 00580 * 00581 * @return a PofReader that reads its contents from a single property of 00582 * this PofReader 00583 * 00584 * @throws IllegalStateException if the POF 00585 * stream has already advanced past the desired property, 00586 * or if no user type is being parsed 00587 * @throws IOException if an I/O error occurs 00588 * 00589 * @since Coherence 3.6 00590 */ 00591 virtual PofReader::Handle createNestedPofReader(int32_t iProp) = 0; 00592 00593 /** 00594 * Read all remaining indexed properties of the current user type from 00595 * the POF stream. As part of reading in a user type, this method must 00596 * be called by the PofSerializer that is reading the user type, or 00597 * the read position within the POF stream will be corrupted. 00598 * 00599 * Subsequent calls to the various <tt>readXYZ</tt> methods of this 00600 * interface will fail after this method is called. 00601 * 00602 * @return a buffer containing zero or more indexed properties in 00603 * binary POF encoded form, may be <tt>NULL</tt> 00604 * 00605 * @throws IllegalStateException if no user type is 00606 * being parsed 00607 * @throws IOException if an I/O error occurs 00608 */ 00609 virtual Binary::View readRemainder() = 0; 00610 }; 00611 00612 COH_CLOSE_NAMESPACE3 00613 00614 #endif // COH_POF_READER_HPP