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