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