00001 /* 00002 * PofReader.hpp 00003 * 00004 * Copyright 2001-2008 by Oracle. 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 hao the optional <tt>ObjectArray</tt> to use to store the 00440 * values; if the supplied <tt>ObjectArray</tt> is not 00441 * large enough to store all read values, a new one will 00442 * be created and returned 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) = 0; 00454 00455 00456 // ----- collection support --------------------------------------------- 00457 00458 public: 00459 /** 00460 * Read a <tt>LongArray</tt> of object values from the POF stream. 00461 * 00462 * @param iProp the property index to read 00463 * @param hla the optional <tt>LongArray</tt> to use to store the 00464 * values; may be <tt>NULL</tt> 00465 * 00466 * @return a <tt>LongArray</tt> of object values, or <tt>NULL</tt> if 00467 * no <tt>LongArray</tt> is passed and there is no key/value 00468 * data available in the POF stream 00469 * 00470 * @throws coherence::lang::IllegalArgumentException if the property 00471 * index is invalid, or is less than or equal to the index of 00472 * the previous property read from the POF stream 00473 * @throws coherence::io::IOException if an I/O error occurs 00474 */ 00475 virtual LongArray::View readLongArray(int32_t iProp, 00476 LongArray::Handle hla = NULL) = 0; 00477 00478 /** 00479 * Read a <tt>Collection</tt> of object values from the POF stream. 00480 * 00481 * @param iProp the property index to read 00482 * @param hCol the optional <tt>Collection</tt> to use to store the 00483 * values; may be <tt>NULL</tt> 00484 * 00485 * @return a <tt>Collection</tt> of object values, or <tt>NULL</tt> if 00486 * no <tt>Collection</tt> is passed and there is no collection 00487 * data available in the POF stream 00488 * 00489 * @throws coherence::lang::IllegalArgumentException if the property 00490 * index is invalid, or is less than or equal to the index of 00491 * the previous property read from the POF stream 00492 * @throws coherence::io::IOException if an I/O error occurs 00493 */ 00494 virtual Collection::View readCollection(int32_t iProp, 00495 Collection::Handle hCol = NULL) = 0; 00496 00497 /** 00498 * Read a <tt>Map</tt> of key/value pairs from the POF stream. 00499 * 00500 * @param iProp the property index to read 00501 * @param hMap the optional <tt>Map</tt> to initialize; the handle 00502 * may be <tt>NULL</tt> 00503 * 00504 * @return a <tt>Map</tt> of key/value pairs, or <tt>NULL</tt> if no 00505 * <tt>Map</tt> is passed and there is no key/value data in 00506 * the POF stream 00507 * 00508 * @throws coherence::lang::IllegalArgumentException if the property 00509 * index is invalid, or is less than or equal to the index of 00510 * the previous property read from the POF stream 00511 * @throws coherence::io::IOException if an I/O error occurs 00512 */ 00513 virtual Map::View readMap(int32_t iProp, Map::Handle hMap = NULL) = 0; 00514 00515 00516 // ----- POF user type support ------------------------------------------ 00517 00518 public: 00519 /** 00520 * Return the PofContext object used by this PofReader to deserialize 00521 * user types from a POF stream. 00522 * 00523 * @return the PofContext object that contains user type meta-data 00524 */ 00525 virtual PofContext::View getPofContext() const = 0; 00526 00527 /** 00528 * Configure the PofContext object used by this PofReader to 00529 * deserialize user types from a POF stream. 00530 * 00531 * Note: this is an advanced method that should be used with care. For 00532 * example, if this method is being used to switch to another 00533 * PofContext mid-POF stream, it is important to eventually restore 00534 * the original PofContext. For example: 00535 * <pre> 00536 * PofContext::View vCtxOrig = hReader->getPofContext(); 00537 * 00538 * // switch to another PofContext 00539 * PofContext::View vCtxNew = ...; 00540 * hReader->setContext(vCtxNew); 00541 * 00542 * // read POF data using the reader 00543 * ... 00544 * 00545 * // restore the original PofContext 00546 * hReader->setPofContext(vCtxOrig); 00547 * </pre> 00548 * 00549 * @param vCtx the new PofContext; must not be <tt>NULL</tt> 00550 */ 00551 virtual void setPofContext(PofContext::View vCtx) = 0; 00552 00553 /** 00554 * Determine the user type that is currently being parsed. 00555 * 00556 * @return the user type information, or -1 if the PofReader is not 00557 * currently parsing a user type 00558 */ 00559 virtual int32_t getUserTypeId() const = 0; 00560 00561 /** 00562 * Determine the version identifier of the user type that is currently 00563 * being parsed. 00564 * 00565 * @return the integer version ID read from the POF stream; always 00566 * non-negative 00567 * 00568 * @throws coherence::lang::IllegalStateException if no user type is 00569 * being parsed 00570 */ 00571 virtual int32_t getVersionId() const = 0; 00572 00573 /** 00574 * Read all remaining indexed properties of the current user type from 00575 * the POF stream. As part of reading in a user type, this method must 00576 * be called by the PofSerializer that is reading the user type, or 00577 * the read position within the POF stream will be corrupted. 00578 * 00579 * Subsequent calls to the various <tt>readXYZ</tt> methods of this 00580 * interface will fail after this method is called. 00581 * 00582 * @return a buffer containing zero or more indexed properties in 00583 * binary POF encoded form 00584 * 00585 * @throws coherence::lang::IllegalStateException if no user type is 00586 * being parsed 00587 * @throws coherence::io::IOException if an I/O error occurs 00588 */ 00589 virtual Binary::View readRemainder() = 0; 00590 }; 00591 00592 COH_CLOSE_NAMESPACE3 00593 00594 #endif // COH_POF_READER_HPP