00001 /* 00002 * PofHandler.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_HANDLER_HPP 00017 #define COH_POF_HANDLER_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Binary.hpp" 00022 00023 COH_OPEN_NAMESPACE3(coherence,io,pof) 00024 00025 using coherence::util::Binary; 00026 00027 00028 /** 00029 * This interface defines the handler for an event-driven approach to parsing 00030 * (or assembling) a POF stream. 00031 * 00032 * @author jh 2008.01.23 00033 */ 00034 class COH_EXPORT PofHandler 00035 : public interface_spec<PofHandler> 00036 { 00037 // ----- PofHandler interface ------------------------------------------- 00038 00039 public: 00040 /** 00041 * This method is invoked when an identity is encountered in the POF 00042 * stream. The identity is used to uniquely identify the next value in 00043 * the POF stream, and can be later referenced by the 00044 * {@link #onIdentityReference} method. 00045 * 00046 * @param nId if <tt>(nId >= 0)</tt>, then this is the identity 00047 * encountered in the POF stream, otherwise it is an 00048 * indicator that the following value <i>could</i> have 00049 * been assigned an identifier but was not (i.e. that the 00050 * subsequent value is of a referenceable data type) 00051 */ 00052 virtual void registerIdentity(int32_t nId) = 0; 00053 00054 /** 00055 * Specifies that a NULL value has been encountered in the POF stream. 00056 * 00057 * @param iPos context-sensitive position information: property index 00058 * within a user type, array index within an array, 00059 * element counter within a collection, entry counter 00060 * within a map, -1 otherwise 00061 */ 00062 virtual void onNullReference(int32_t iPos) = 0; 00063 00064 /** 00065 * Specifies that a reference to a previously-identified value has 00066 * been encountered in the POF stream. 00067 * 00068 * @param iPos context-sensitive position information: property index 00069 * within a user type, array index within an array, 00070 * element counter within a collection, entry counter 00071 * within a map, -1 otherwise 00072 * @param nId the identity of the previously encountered value, as 00073 * was specified in a previous call to {@link 00074 * #registerIdentity} 00075 */ 00076 virtual void onIdentityReference(int32_t iPos, int32_t nId) = 0; 00077 00078 /** 00079 * Report that a short integer value has been encountered in the POF 00080 * stream. 00081 * 00082 * @param iPos context-sensitive position information: property index 00083 * within a user type, array index within an array, 00084 * element counter within a collection, entry counter 00085 * within a map, -1 otherwise 00086 * @param n the integer value as a short 00087 */ 00088 virtual void onInt16(int32_t iPos, int16_t n) = 0; 00089 00090 /** 00091 * Report that an integer value has been encountered in the POF stream. 00092 * 00093 * @param iPos context-sensitive position information: property index 00094 * within a user type, array index within an array, 00095 * element counter within a collection, entry counter 00096 * within a map, -1 otherwise 00097 * @param n the integer value as an int32_t 00098 */ 00099 virtual void onInt32(int32_t iPos, int32_t n) = 0; 00100 00101 /** 00102 * Report that a long integer value has been encountered in the POF 00103 * stream. 00104 * 00105 * @param iPos context-sensitive position information: property index 00106 * within a user type, array index within an array, 00107 * element counter within a collection, entry counter 00108 * within a map, -1 otherwise 00109 * @param n the integer value as a long 00110 */ 00111 virtual void onInt64(int32_t iPos, int64_t n) = 0; 00112 00113 /** 00114 * Report that a base-2 single-precision floating-point value has been 00115 * encountered in the POF stream. 00116 * 00117 * @param iPos context-sensitive position information: property index 00118 * within a user type, array index within an array, 00119 * element counter within a collection, entry counter 00120 * within a map, -1 otherwise 00121 * @param fl the floating-point value as a float32_t 00122 */ 00123 virtual void onFloat32(int32_t iPos, float32_t fl) = 0; 00124 00125 /** 00126 * Report that a base-2 double-precision floating-point value has been 00127 * encountered in the POF stream. 00128 * 00129 * @param iPos context-sensitive position information: property index 00130 * within a user type, array index within an array, 00131 * element counter within a collection, entry counter 00132 * within a map, -1 otherwise 00133 * @param dfl the floating-point value as a float64_t 00134 */ 00135 virtual void onFloat64(int32_t iPos, float64_t dfl) = 0; 00136 00137 /** 00138 * Report that a boolean value has been encountered in the POF stream. 00139 * 00140 * @param iPos context-sensitive position information: property index 00141 * within a user type, array index within an array, 00142 * element counter within a collection, entry counter 00143 * within a map, -1 otherwise 00144 * @param f the boolean value 00145 */ 00146 virtual void onBoolean(int32_t iPos, bool f) = 0; 00147 00148 /** 00149 * Report that an octet value (a byte) has been encountered in the POF 00150 * stream. 00151 * 00152 * @param iPos context-sensitive position information: property index 00153 * within a user type, array index within an array, 00154 * element counter within a collection, entry counter 00155 * within a map, -1 otherwise 00156 * @param b the octet value 00157 */ 00158 virtual void onOctet(int32_t iPos, octet_t b) = 0; 00159 00160 /** 00161 * Report that a octet string value has been encountered in the POF 00162 * stream. 00163 * 00164 * @param iPos context-sensitive position information: property index 00165 * within a user type, array index within an array, 00166 * element counter within a collection, entry counter 00167 * within a map, -1 otherwise 00168 * @param vBin the octect string value as a Binary object 00169 */ 00170 virtual void onOctetString(int32_t iPos, Binary::View vBin) = 0; 00171 00172 /** 00173 * Report that a character value has been encountered in the POF 00174 * stream. 00175 * 00176 * @param iPos context-sensitive position information: property index 00177 * within a user type, array index within an array, 00178 * element counter within a collection, entry counter 00179 * within a map, -1 otherwise 00180 * @param ch the character value as a char16_t 00181 */ 00182 virtual void onChar(int32_t iPos, char16_t ch) = 0; 00183 00184 /** 00185 * Report that a character string value has been encountered in the 00186 * POF stream. 00187 * 00188 * @param iPos context-sensitive position information: property index 00189 * within a user type, array index within an array, 00190 * element counter within a collection, entry counter 00191 * within a map, -1 otherwise 00192 * @param vs the character string value as a String object 00193 */ 00194 virtual void onCharString(int32_t iPos, String::View vs) = 0; 00195 00196 /** 00197 * Report that a date value has been encountered in the POF stream. 00198 * 00199 * @param iPos context-sensitive position information: property 00200 * index within a user type, array index within an 00201 * array, element counter within a collection, entry 00202 * counter within a map, -1 otherwise 00203 * @param nYear the year number as defined by ISO8601 00204 * @param nMonth the month number between 1 and 12 inclusive as 00205 * defined by ISO8601 00206 * @param nDay the day number between 1 and 31 inclusive as defined 00207 * by ISO8601 00208 */ 00209 virtual void onDate(int32_t iPos, int32_t nYear, int32_t nMonth, 00210 int32_t nDay) = 0; 00211 00212 /** 00213 * Report that a year-month interval value has been encountered in the 00214 * POF stream. 00215 * 00216 * @param iPos context-sensitive position information: property 00217 * index within a user type, array index within an 00218 * array, element counter within a collection, entry 00219 * counter within a map, -1 otherwise 00220 * @param cYears the number of years in the year-month interval 00221 * @param cMonths the number of months in the year-month interval 00222 */ 00223 virtual void onYearMonthInterval(int32_t iPos, int32_t cYears, 00224 int32_t cMonths) = 0; 00225 00226 /** 00227 * Report that a time value has been encountered in the POF stream. 00228 * 00229 * @param iPos context-sensitive position information: property 00230 * index within a user type, array index within an 00231 * array, element counter within a collection, entry 00232 * counter within a map, -1 otherwise 00233 * @param nHour the hour between 0 and 23 inclusive 00234 * @param nMinute the minute value between 0 and 59 inclusive 00235 * @param nSecond the second value between 0 and 59 inclusive (and 00236 * theoretically 60 for a leap-second) 00237 * @param nNano the nanosecond value between 0 and 999999999 00238 * inclusive 00239 * @param fUTC true if the time value is UTC or false if the time 00240 * value does not have an explicit time zone 00241 */ 00242 virtual void onTime(int32_t iPos, int32_t nHour, int32_t nMinute, 00243 int32_t nSecond, int32_t nNano, bool fUTC) = 0; 00244 00245 /** 00246 * Report that a time value (with a timezone offset) has been 00247 * encountered in the POF stream. 00248 * 00249 * @param iPos context-sensitive position information: 00250 * property index within a user type, array 00251 * index within an array, element counter within 00252 * a collection, entry counter within a map, -1 00253 * otherwise 00254 * @param nHour the hour between 0 and 23 inclusive 00255 * @param nMinute the minute value between 0 and 59 inclusive 00256 * @param nSecond the second value between 0 and 59 inclusive 00257 * (and theoretically 60 for a leap-second) 00258 * @param nNano the nanosecond value between 0 and 999999999 00259 * inclusive 00260 * @param nHourOffset the timezone offset in hours from UTC, for 00261 * example 0 for BST, -5 for EST and 1 for CET 00262 * @param nMinuteOffset the timezone offset in minutes, for example 0 00263 * (in most cases) or 30 00264 * 00265 * @see <a href="http://www.worldtimezone.com/faq.html">worldtimezone.com</a> 00266 */ 00267 virtual void onTime(int32_t iPos, int32_t nHour, int32_t nMinute, 00268 int32_t nSecond, int32_t nNano, int32_t nHourOffset, 00269 int32_t nMinuteOffset) = 0; 00270 00271 /** 00272 * Report that a time interval value has been encountered in the POF 00273 * stream. 00274 * 00275 * @param iPos context-sensitive position information: property 00276 * index within a user type, array index within an 00277 * array, element counter within a collection, entry 00278 * counter within a map, -1 otherwise 00279 * @param cHours the number of hours in the time interval 00280 * @param cMinutes the number of minutes in the time interval, from 0 00281 * to 59 inclusive 00282 * @param cSeconds the number of seconds in the time interval, from 0 00283 * to 59 inclusive 00284 * @param cNanos the number of nanoseconds, from 0 to 999999999 00285 * inclusive 00286 */ 00287 virtual void onTimeInterval(int32_t iPos, int32_t cHours, 00288 int32_t cMinutes, int32_t cSeconds, int32_t cNanos) = 0; 00289 00290 /** 00291 * Report that a date-time value has been encountered in the POF 00292 * stream. 00293 * 00294 * @param iPos context-sensitive position information: property 00295 * index within a user type, array index within an 00296 * array, element counter within a collection, entry 00297 * counter within a map, -1 otherwise 00298 * @param nYear the year number as defined by ISO8601 00299 * @param nMonth the month number between 1 and 12 inclusive as 00300 * defined by ISO8601 00301 * @param nDay the day number between 1 and 31 inclusive as 00302 * defined by ISO8601 00303 * @param nHour the hour between 0 and 23 inclusive 00304 * @param nMinute the minute value between 0 and 59 inclusive 00305 * @param nSecond the second value between 0 and 59 inclusive (and 00306 * theoretically 60 for a leap-second) 00307 * @param nNano the nanosecond value between 0 and 999999999 00308 * inclusive 00309 * @param fUTC true if the time value is UTC or false if the time 00310 * value does not have an explicit time zone 00311 */ 00312 virtual void onDateTime(int32_t iPos, int32_t nYear, int32_t nMonth, 00313 int32_t nDay, int32_t nHour, int32_t nMinute, int32_t nSecond, 00314 int32_t nNano, bool fUTC) = 0; 00315 00316 /** 00317 * Report that a date-time value (with a timezone offset) has been 00318 * encountered in the POF stream. 00319 * 00320 * @param iPos context-sensitive position information: 00321 * property index within a user type, array 00322 * index within an array, element counter within 00323 * a collection, entry counter within a map, -1 00324 * otherwise 00325 * @param nYear the year number as defined by ISO8601 00326 * @param nMonth the month number between 1 and 12 inclusive 00327 * as defined by ISO8601 00328 * @param nDay the day number between 1 and 31 inclusive as 00329 * defined by ISO8601 00330 * @param nHour the hour between 0 and 23 inclusive 00331 * @param nMinute the minute value between 0 and 59 inclusive 00332 * @param nSecond the second value between 0 and 59 inclusive 00333 * (and theoretically 60 for a leap-second) 00334 * @param nNano the nanosecond value between 0 and 999999999 00335 * inclusive 00336 * @param nHourOffset the timezone offset in hours from UTC, for 00337 * example 0 for BST, -5 for EST and 1 for CET 00338 * @param nMinuteOffset the timezone offset in minutes, for example 0 00339 * (in most cases) or 30 00340 */ 00341 virtual void onDateTime(int32_t iPos, int32_t nYear, int32_t nMonth, 00342 int32_t nDay, int32_t nHour, int32_t nMinute, int32_t nSecond, 00343 int32_t nNano, int32_t nHourOffset, int32_t nMinuteOffset) = 0; 00344 00345 /** 00346 * Report that a day-time interval value has been encountered in the POF 00347 * stream. 00348 * 00349 * @param iPos context-sensitive position information: property 00350 * index within a user type, array index within an 00351 * array, element counter within a collection, entry 00352 * counter within a map, -1 otherwise 00353 * @param cDays the number of days in the day-time interval 00354 * @param cHours the number of hours in the day-time interval, from 00355 * 0 to 23 inclusive 00356 * @param cMinutes the number of minutes in the day-time interval, 00357 * from 0 to 59 inclusive 00358 * @param cSeconds the number of seconds in the day-time interval, 00359 * from 0 to 59 inclusive 00360 * @param cNanos the number of nanoseconds in the day-time interval, 00361 * from 0 to 999999999 inclusive 00362 */ 00363 virtual void onDayTimeInterval(int32_t iPos, int32_t cDays, 00364 int32_t cHours, int32_t cMinutes, int32_t cSeconds, 00365 int32_t cNanos) = 0; 00366 00367 /** 00368 * Report that a collection of values has been encountered in the POF 00369 * stream. 00370 * 00371 * This method call will be followed by a separate call to an "on" or 00372 * "begin" method for each of the <tt>cElements</tt> elements in the 00373 * collection, and the collection extent will then be terminated by a 00374 * call to {@link #endComplexValue()}. 00375 * 00376 * @param iPos context-sensitive position information: property 00377 * index within a user type, array index within an 00378 * array, element counter within a collection, entry 00379 * counter within a map, -1 otherwise 00380 * @param cElements the exact number of values (elements) in the 00381 * collection 00382 */ 00383 virtual void beginCollection(int32_t iPos, size32_t cElements) = 0; 00384 00385 /** 00386 * Report that a uniform collection of values has been encountered in 00387 * the POF stream. 00388 * 00389 * This method call will be followed by a separate call to an "on" or 00390 * "begin" method for each of the <tt>cElements</tt> elements in the 00391 * collection, and the collection extent will then be terminated by a 00392 * call to {@link #endComplexValue()}. 00393 * 00394 * @param iPos context-sensitive position information: property 00395 * index within a user type, array index within an 00396 * array, element counter within a collection, entry 00397 * counter within a map, -1 otherwise 00398 * @param cElements the exact number of values (elements) in the 00399 * collection 00400 * @param nType the type identifier for all of the values in the 00401 * uniform collection 00402 */ 00403 virtual void beginUniformCollection(int32_t iPos, size32_t cElements, 00404 int32_t nType) = 0; 00405 00406 /** 00407 * Report that an array of values has been encountered in the POF 00408 * stream. 00409 * This method call will be followed by a separate call to an "on" or 00410 * "begin" method for each of the <tt>cElements</tt> elements in the 00411 * array, and the array extent will then be terminated by a call to 00412 * {@link #endComplexValue()}. 00413 * 00414 * @param iPos context-sensitive position information: property 00415 * index within a user type, array index within an 00416 * array, element counter within a collection, entry 00417 * counter within a map, -1 otherwise 00418 * @param cElements the exact number of values (elements) in the 00419 * array 00420 */ 00421 virtual void beginArray(int32_t iPos, size32_t cElements) = 0; 00422 00423 /** 00424 * Report that a uniform array of values has been encountered in the 00425 * POF stream. 00426 * 00427 * This method call will be followed by a separate call to an "on" or 00428 * "begin" method for each of the <tt>cElements</tt> elements in the 00429 * array, and the array extent will then be terminated by a call to 00430 * {@link #endComplexValue()}. 00431 * 00432 * @param iPos context-sensitive position information: property 00433 * index within a user type, array index within an 00434 * array, element counter within a collection, entry 00435 * counter within a map, -1 otherwise 00436 * @param cElements the exact number of values (elements) in the 00437 * array 00438 * @param nType the type identifier for all of the values in the 00439 * uniform array 00440 */ 00441 virtual void beginUniformArray(int32_t iPos, size32_t cElements, 00442 int32_t nType) = 0; 00443 00444 /** 00445 * Report that a sparse array of values has been encountered in the 00446 * POF stream. 00447 * 00448 * This method call will be followed by a separate call to an "on" or 00449 * "begin" method for present element in the sparse array (up to 00450 * <tt>cElements</tt> elements), and the array extent will then be 00451 * terminated by a call to {@link #endComplexValue()}. 00452 * 00453 * @param iPos context-sensitive position information: property 00454 * index within a user type, array index within an 00455 * array, element counter within a collection, entry 00456 * counter within a map, -1 otherwise 00457 * @param cElements the exact number of elements in the array, which 00458 * is greater than or equal to the number of values 00459 * in the sparse POF stream; in other words, the 00460 * number of values that will subsequently be 00461 * reported will not exceed this number 00462 */ 00463 virtual void beginSparseArray(int32_t iPos, size32_t cElements) = 0; 00464 00465 /** 00466 * Report that a uniform sparse array of values has been encountered 00467 * in the POF stream. 00468 * 00469 * This method call will be followed by a separate call to an "on" or 00470 * "begin" method for present element in the sparse array (up to 00471 * <tt>cElements</tt> elements), and the array extent will then be 00472 * terminated by a call to {@link #endComplexValue()}. 00473 * 00474 * @param iPos context-sensitive position information: property 00475 * index within a user type, array index within an 00476 * array, element counter within a collection, entry 00477 * counter within a map, -1 otherwise 00478 * @param cElements the exact number of elements in the array, which 00479 * is greater than or equal to the number of values 00480 * in the sparse POF stream; in other words, the 00481 * number of values that will subsequently be 00482 * reported will not exceed this number 00483 * @param nType the type identifier for all of the values in the 00484 * uniform sparse array 00485 */ 00486 virtual void beginUniformSparseArray(int32_t iPos, size32_t cElements, 00487 int32_t nType) = 0; 00488 00489 /** 00490 * Report that a map of key/value pairs has been encountered in the 00491 * POF stream. 00492 * 00493 * This method call will be followed by a separate call to an "on" or 00494 * "begin" method for each of the <tt>cElements</tt> elements in the 00495 * map, and the map extent will then be terminated by a call to 00496 * {@link #endComplexValue()}. 00497 * 00498 * @param iPos context-sensitive position information: property 00499 * index within a user type, array index within an 00500 * array, element counter within a collection, entry 00501 * counter within a map, -1 otherwise 00502 * @param cElements the exact number of key/value pairs (entries) in 00503 * the map 00504 */ 00505 virtual void beginMap(int32_t iPos, size32_t cElements) = 0; 00506 00507 /** 00508 * Report that a map of key/value pairs (with the keys being of a 00509 * uniform type) has been encountered in the POF stream. 00510 * 00511 * This method call will be followed by a separate call to an "on" or 00512 * "begin" method for each of the <tt>cElements</tt> elements in the 00513 * map, and the map extent will then be terminated by a call to 00514 * {@link #endComplexValue()}. 00515 * 00516 * @param iPos context-sensitive position information: property 00517 * index within a user type, array index within an 00518 * array, element counter within a collection, entry 00519 * counter within a map, -1 otherwise 00520 * @param cElements the exact number of key/value pairs (entries) in 00521 * the map 00522 * @param nTypeKeys the type identifier for all of the keys in the 00523 * uniform-keys map 00524 */ 00525 virtual void beginUniformKeysMap(int32_t iPos, size32_t cElements, 00526 int32_t nTypeKeys) = 0; 00527 00528 /** 00529 * Report that a map of key/value pairs (with the keys being of a 00530 * uniform type and the values being of a uniform type) has been 00531 * encountered in the POF stream. 00532 * 00533 * This method call will be followed by a separate call to an "on" or 00534 * "begin" method for each of the <tt>cElements</tt> elements in the 00535 * map, and the map extent will then be terminated by a call to 00536 * {@link #endComplexValue()}. 00537 * 00538 * @param iPos context-sensitive position information: 00539 * property index within a user type, array index 00540 * within an array, element counter within a 00541 * collection, entry counter within a map, -1 00542 * otherwise 00543 * @param cElements the exact number of key/value pairs (entries) 00544 * in the map 00545 * @param nTypeKeys the type identifier for all of the keys in the 00546 * uniform map 00547 * @param nTypeValues the type identifier for all of the values in 00548 * the uniform map 00549 */ 00550 virtual void beginUniformMap(int32_t iPos, size32_t cElements, 00551 int32_t nTypeKeys, int32_t nTypeValues) = 0; 00552 00553 /** 00554 * Report that a value of a "user type" has been encountered in the 00555 * POF stream. A user type is analogous to a "class", and a value of a 00556 * user type is analogous to an "object". 00557 * 00558 * This method call will be followed by a separate call to an "on" or 00559 * "begin" method for each of the property values in the user type, 00560 * and the user type will then be terminated by a call to 00561 * {@link #endComplexValue()}. 00562 * 00563 * @param iPos context-sensitive position information: 00564 * property index within a user type, array index 00565 * within an array, element counter within a 00566 * collection, entry counter within a map, -1 00567 * otherwise 00568 * @param nUserTypeId the user type identifier, 00569 * <tt>(nUserTypeId >= 0)</tt> 00570 * @param nVersionId the version identifier for the user data type 00571 * data in the POF stream, <tt>(nVersionId >= 00572 * 0)</tt> 00573 */ 00574 virtual void beginUserType(int32_t iPos, int32_t nUserTypeId, 00575 int32_t nVersionId) = 0; 00576 00577 /** 00578 * Signifies the termination of the current complex value. Complex 00579 * values are any of the collection, array, map and user types. For 00580 * each call to one of the "begin" methods, there will be a 00581 * corresponding call to this method, even if there were no contents 00582 * in the complex value. 00583 */ 00584 virtual void endComplexValue() = 0; 00585 }; 00586 00587 COH_CLOSE_NAMESPACE3 00588 00589 #endif // COH_POF_HANDLER_HPP