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