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