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_READ_BUFFER_HPP 00008 #define COH_READ_BUFFER_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 // ----- forward declarations ----------------------------------------------- 00013 00014 COH_OPEN_NAMESPACE2(coherence,util) 00015 00016 class Binary; 00017 00018 COH_CLOSE_NAMESPACE2 00019 00020 COH_OPEN_NAMESPACE2(coherence,io) 00021 00022 00023 /** 00024 * The ReadBuffer interface represents an in-memory block of binary data. 00025 * 00026 * @author jh 2007.12.20 00027 */ 00028 class COH_EXPORT ReadBuffer 00029 : public interface_spec<ReadBuffer> 00030 { 00031 // ----- handle definitions (needed for nested classes) ----------------- 00032 00033 public: 00034 typedef this_spec::Handle Handle; 00035 typedef this_spec::View View; 00036 typedef this_spec::Holder Holder; 00037 00038 /** 00039 * Binary View definition. 00040 */ 00041 typedef TypedHandle<const coherence::util::Binary> BinaryView; 00042 00043 00044 // ----- ReadBuffer interface ------------------------------------------- 00045 00046 public: 00047 /** 00048 * Determine the length of the buffer. 00049 * 00050 * @return the number of octets of data represented by this ReadBuffer 00051 */ 00052 virtual size32_t length() const = 0; 00053 00054 /** 00055 * Returns the octet at the specified offset. An offset ranges 00056 * from <code>0</code> to <code>length() - 1</code>. The first octet 00057 * of the sequence is at offset <code>0</code>, the next at offset 00058 * <code>1</code>, and so on, as for array indexing. 00059 * 00060 * @param of the offset (index) of the octet 00061 * 00062 * @return the octet at the specified offset in this ReadBuffer 00063 * 00064 * @throws IndexOutOfBoundsException if the <code>of</code> argument 00065 * is not less than the length of this ReadBuffer 00066 */ 00067 virtual octet_t read(size32_t of) const = 0; 00068 00069 /** 00070 * Copies octets from this ReadBuffer into the destination octet 00071 * array. 00072 * <p> 00073 * The first octet to be copied is at offset <code>ofBegin</code>; 00074 * the last octet to be copied is at offset <code>ofEnd-1</code> 00075 * (thus the total number of octets to be copied is <code>ofEnd - 00076 * ofBegin</code>). The octets are copied into the subarray of 00077 * <code>habDest</code> starting at offset <code>ofDest</code> and 00078 * ending at index: 00079 * <pre> 00080 * ofDest + (ofEnd - ofBegin) - 1 00081 * </pre> 00082 * This method allows the caller to extract a chunk of octets into the 00083 * caller's own array. 00084 * 00085 * @param ofBegin offset of the first octet in the ReadBuffer to copy 00086 * @param ofEnd offset after the last octet in the ReadBuffer to 00087 * copy 00088 * @param habDest the destination octet array 00089 * @param ofDest the offset in the destination octet array to copy 00090 * the first octet to 00091 * 00092 * @throws IndexOutOfBoundsException if any of the following is true: 00093 * <ul> 00094 * <li><code>ofBegin</code> is greater than <code>ofEnd</code> 00095 * <li><code>ofEnd</code> is greater than the length of this 00096 * ReadBuffer; 00097 * <li><code>ofDest + (ofEnd - ofBegin)</code> is larger than 00098 * <code>habDest->length</code> 00099 * </ul> 00100 * @throws NullPointerException if <code>habDest</code> is NULL 00101 */ 00102 virtual void read(size32_t ofBegin, size32_t ofEnd, 00103 Array<octet_t>::Handle habDest, size32_t ofDest) const = 0; 00104 00105 /** 00106 * Obtain a ReadBuffer for a portion of this ReadBuffer. 00107 * 00108 * @param of the beginning index, inclusive 00109 * @param cb the number of octets to include in the resulting 00110 * ReadBuffer 00111 * 00112 * @return a ReadBuffer that represents a portion of this ReadBuffer 00113 * 00114 * @throws IndexOutOfBoundsException if <code>of + cb</code> is 00115 * larger than the length of this ReadBuffer 00116 */ 00117 virtual ReadBuffer::View getReadBuffer(size32_t of, size32_t cb) const = 0; 00118 00119 /** 00120 * Returns a new Binary object that holds the complete contents of 00121 * this ReadBuffer. 00122 * <p> 00123 * This is the equivalent of <code>toBinary(0, length())</code>. 00124 * 00125 * @return the contents of this ReadBuffer as a Binary object 00126 * 00127 * @since Coherence 3.7.1 00128 */ 00129 virtual BinaryView toBinary() const = 0; 00130 00131 /** 00132 * Returns a Binary object that holds the specified portion of this 00133 * ReadBuffer. 00134 * <p> 00135 * This is the equivalent of 00136 * <code>getReadBuffer(of, cb)->toBinary()</code>. 00137 * 00138 * @param of the beginning index, inclusive 00139 * @param cb the number of octets to include in the Binary object 00140 * 00141 * @return a Binary object containing the specified portion of this 00142 * ReadBuffer 00143 * 00144 * @throws IndexOutOfBoundsException if <code>of + cb</code> is 00145 * larger than the length of this <code>ReadBuffer</code> 00146 * object 00147 * 00148 * @since Coherence 3.7.1 00149 */ 00150 virtual BinaryView toBinary(size32_t of, size32_t cb) const = 0; 00151 00152 /** 00153 * Get the contents of the ReadBuffer as an octet array. 00154 * <p> 00155 * This is the equivalent of <code>toOctetArray(0, length())</code>. 00156 * 00157 * @return an octet array with the contents of this ReadBuffer object 00158 */ 00159 virtual Array<octet_t>::View toOctetArray() const = 0; 00160 00161 /** 00162 * Get a portion of the contents of the ReadBuffer as an octet array. 00163 * 00164 * @param of the beginning index, inclusive 00165 * @param cb the number of octets to include in the resulting array 00166 * 00167 * @return an octet array containing the specified portion of this 00168 * ReadBuffer 00169 * 00170 * @throws IndexOutOfBoundsException if <code>of + cb</code> is 00171 * larger than the length of this ReadBuffer 00172 */ 00173 virtual Array<octet_t>::View toOctetArray(size32_t of, size32_t cb) const = 0; 00174 00175 00176 // ----- BufferInput inner interface ------------------------------------ 00177 00178 public: 00179 /** 00180 * The BufferInput interface represents a data input stream on top of 00181 * a ReadBuffer. 00182 * 00183 * @author jh 2007.12.20 00184 */ 00185 class COH_EXPORT BufferInput 00186 : public interface_spec<BufferInput> 00187 { 00188 // ----- BufferInput interface ------------------------------ 00189 00190 public: 00191 /** 00192 * Get the ReadBuffer object that this BufferInput is reading 00193 * from. 00194 * 00195 * @return the underlying ReadBuffer object 00196 */ 00197 virtual ReadBuffer::View getBuffer() const = 0; 00198 00199 /** 00200 * Determine the current offset of this BufferInput within the 00201 * underlying ReadBuffer. 00202 * 00203 * @return the offset of the next octet to read from the 00204 * ReadBuffer 00205 */ 00206 virtual size32_t getOffset() const = 0; 00207 00208 /** 00209 * Specify the offset of the next octet to read from the 00210 * underlying ReadBuffer. 00211 * 00212 * @param of the offset of the next octet to read from the 00213 * ReadBuffer 00214 * 00215 * @throws IndexOutOfBoundsException if 00216 * <code>of > getBuffer()->length()</code> 00217 */ 00218 virtual void setOffset(size32_t of) = 0; 00219 00220 /** 00221 * Returns the number of octets that can be read (or skipped 00222 * over) from this input stream before the end of the stream 00223 * is reached. 00224 * 00225 * @return the number of octets that can be read (or skipped 00226 * over) from this BufferInput 00227 */ 00228 virtual size32_t available() const = 0; 00229 00230 /** 00231 * Skips over the specified number of octets of data. 00232 * 00233 * @param cb the number of octets to skip over 00234 * 00235 * @throws EOFException if the stream is exhausted before the 00236 * number of octets indicated could be skipped 00237 * @throws IOException if an I/O error occurs 00238 */ 00239 virtual void skip(size32_t cb) = 0; 00240 00241 /** 00242 * Read an octet value. 00243 * 00244 * @return an <code>octet_t</code> value 00245 * 00246 * @throws EOFException if the value could not be read because 00247 * no more data remains to be read 00248 * @throws IOException if an I/O error occurs 00249 */ 00250 virtual octet_t read() = 0; 00251 00252 /** 00253 * Read <code>hab->length</code> octets and store them in 00254 * <code>hab</code>. 00255 * 00256 * @param hab the array to store the octets which are read 00257 * from the stream 00258 * 00259 * @throws NullPointerException if the passed array is NULL 00260 * @throws EOFException if the stream is exhausted before the 00261 * number of octets indicated by the array length could 00262 * be read 00263 * @throws IOException if an I/O error occurs 00264 */ 00265 virtual void read(Array<octet_t>::Handle hab) = 0; 00266 00267 /** 00268 * Read <code>cb</code> octets from the input stream and store 00269 * them into the passed array <code>hab</code> starting at 00270 * offset <code>of</code>. 00271 * 00272 * @param hab the array to store the octets which are read 00273 * from the stream 00274 * @param of the offset into the array that the read octets 00275 * will be stored 00276 * @param cb the number of octets to read 00277 * 00278 * @throws NullPointerException if the passed array is NULL 00279 * @throws IndexOutOfBoundsException if <code>of+cb</code> 00280 * is greater than the length of the <code>hab</code> 00281 * @throws EOFException if the stream is exhausted before the 00282 * number of octets indicated could be read 00283 * @throws IOException if an I/O error occurs 00284 */ 00285 virtual void read(Array<octet_t>::Handle hab, size32_t of, 00286 size32_t cb) = 0; 00287 00288 /** 00289 * Read <code>cb</code> octets and return them as a ReadBuffer 00290 * object. 00291 * 00292 * @param cb the number of octets to read 00293 * 00294 * @return a ReadBuffer object composed of <code>cb</code> 00295 * octets read from the BufferInput 00296 * 00297 * @throws EOFException if the stream is exhausted before the 00298 * number of octets indicated could be read 00299 * @throws IOException if an I/O error occurs 00300 */ 00301 virtual ReadBuffer::View readBuffer(size32_t cb) = 0; 00302 00303 /** 00304 * Read a boolean value. 00305 * 00306 * @return either <code>true</code> or <code>false</code> 00307 * 00308 * @throws EOFException if the value could not be read because 00309 * no more data remains to be read 00310 * @throws IOException if an I/O error occurs 00311 */ 00312 virtual bool readBoolean() = 0; 00313 00314 /** 00315 * Read a 16-bit Unicode character value. 00316 * 00317 * @return a 16-bit Unicode character as a 00318 * <code>wchar16_t</code> value 00319 * 00320 * @throws EOFException if the value could not be read because 00321 * no more data remains to be read 00322 * @throws IOException if an I/O error occurs 00323 */ 00324 virtual wchar16_t readChar16() = 0; 00325 00326 /** 00327 * Read a sequence of UTF-8 encoded 16-bit Unicode characters. 00328 * 00329 * @return a String value; may be NULL 00330 * 00331 * @throws IOException if an I/O error occurs 00332 */ 00333 virtual String::View readString() = 0; 00334 00335 /** 00336 * Read a 16-bit integer value. 00337 * 00338 * @return an <code>int16_t</code> value 00339 * 00340 * @throws EOFException if the value could not be read because 00341 * no more data remains to be read 00342 * @throws IOException if an I/O error occurs 00343 */ 00344 virtual int16_t readInt16() = 0; 00345 00346 /** 00347 * Read a 32-bit integer value. 00348 * 00349 * @return an <code>int32_t</code> value 00350 * 00351 * @throws EOFException if the value could not be read because 00352 * no more data remains to be read 00353 * @throws IOException if an I/O error occurs 00354 */ 00355 virtual int32_t readInt32() = 0; 00356 00357 /** 00358 * Read a 64-bit integer value. 00359 * 00360 * @return an <code>int64_t</code> value 00361 * 00362 * @throws EOFException if the value could not be read because 00363 * no more data remains to be read 00364 * @throws IOException if an I/O error occurs 00365 */ 00366 virtual int64_t readInt64() = 0; 00367 00368 /** 00369 * Read a 32-bit floating-point value. 00370 * 00371 * @return a <code>float32_t</code> value 00372 * 00373 * @throws EOFException if the value could not be read because 00374 * no more data remains to be read 00375 * @throws IOException if an I/O error occurs 00376 */ 00377 virtual float32_t readFloat32() = 0; 00378 00379 /** 00380 * Read a 64-bit floating-point value. 00381 * 00382 * @return a <code>float64_t</code> value 00383 * 00384 * @throws EOFException if the value could not be read because 00385 * no more data remains to be read 00386 * @throws IOException if an I/O error occurs 00387 */ 00388 virtual float64_t readFloat64() = 0; 00389 }; 00390 00391 /** 00392 * Get a BufferInput object to read data from this buffer. Note that 00393 * each call to this method will return a new BufferInput object, with 00394 * the possible exception being that a zero-length ReadBuffer could 00395 * always return the same instance (since there is nothing to read). 00396 * 00397 * @return a BufferInput that is reading from this buffer starting at 00398 * offset zero 00399 */ 00400 virtual BufferInput::Handle getBufferInput() const = 0; 00401 }; 00402 00403 COH_CLOSE_NAMESPACE2 00404 00405 #endif // COH_READ_BUFFER_HPP