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