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_WRITE_BUFFER_HPP 00008 #define COH_WRITE_BUFFER_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/io/ReadBuffer.hpp" 00013 00014 // ----- forward declarations ----------------------------------------------- 00015 00016 COH_OPEN_NAMESPACE2(coherence,util) 00017 00018 class Binary; 00019 00020 COH_CLOSE_NAMESPACE2 00021 00022 COH_OPEN_NAMESPACE2(coherence,io) 00023 00024 00025 /** 00026 * The WriteBuffer interface represents an in-memory block of binary data 00027 * that is being accumulated (written to). 00028 * 00029 * @author jh 2007.12.20 00030 */ 00031 class COH_EXPORT WriteBuffer 00032 : public interface_spec<WriteBuffer> 00033 { 00034 // ----- handle definitions (needed for nested classes) ----------------- 00035 00036 public: 00037 typedef this_spec::Handle Handle; 00038 typedef this_spec::View View; 00039 typedef this_spec::Holder Holder; 00040 00041 /** 00042 * Binary View definition. 00043 */ 00044 typedef TypedHandle<const coherence::util::Binary> BinaryView; 00045 00046 00047 // ----- WriteBuffer interface ------------------------------------------ 00048 00049 public: 00050 /** 00051 * Determine the length of the data that is in the buffer. This is the 00052 * actual number of octets of data that have been written to the 00053 * buffer, not the capacity of the buffer. 00054 * 00055 * @return the number of octets of data represented by this 00056 * WriteBuffer 00057 */ 00058 virtual size32_t length() const = 0; 00059 00060 /** 00061 * Determine the number of octets that the buffer can hold without 00062 * resizing itself. In other words, a WriteBuffer has <tt> 00063 * getCapacity() - #length()</tt> octets that can be written 00064 * to it without overflowing the current underlying buffer allocation. 00065 * Since the buffer is an abstract concept, the actual mechanism for 00066 * the underlying buffer is not known. 00067 * 00068 * Note that if the maximum size returned by 00069 * #getMaximumCapacity() is greater than the current size 00070 * returned by this method, then the WriteBuffer will automatically 00071 * resize itself to allocate more space when the amount of data 00072 * written to it passes the current size. 00073 * 00074 * @return the number of octets of data that this WriteBuffer can hold 00075 * without resizing its underlying buffer 00076 */ 00077 virtual size32_t getCapacity() const = 0; 00078 00079 /** 00080 * Determine the maximum number of octets that the buffer can hold. If 00081 * the maximum size is greater than the current size, then the buffer 00082 * is expected to resize itself as necessary up to the maximum size in 00083 * order to contain the data given to it. 00084 * 00085 * @return the maximum number of octets of data that the WriteBuffer 00086 * can hold 00087 */ 00088 virtual size32_t getMaximumCapacity() const = 0; 00089 00090 /** 00091 * Store the specified octet at the specified offset within the 00092 * buffer. 00093 * 00094 * For purposes of side-effects and potential exceptions, this method 00095 * is functionally equivalent to the following code: 00096 * <pre><code> 00097 * Array<octet_t>::Handle habSrc = Array<octet_t>::create(1); 00098 * habSrc[0] = b; 00099 * write(ofDest, habSrc, 0, 1); 00100 * </code></pre> 00101 * 00102 * @param ofDest the offset within this buffer to store the passed 00103 * data 00104 * @param b the octet to store in this buffer 00105 */ 00106 virtual void write(size32_t ofDest, octet_t b) = 0; 00107 00108 /** 00109 * Store the specified octets at the specified offset within the 00110 * buffer. 00111 * 00112 * For purposes of side-effects and potential exceptions, this method 00113 * is functionally equivalent to the following code: 00114 * <pre><code> 00115 * write(ofDest, vabSrc, 0, vabSrc.length); 00116 * </code></pre> 00117 * 00118 * @param ofDest the offset within this buffer to store the passed 00119 * data 00120 * @param vabSrc the array of octets to store in this buffer 00121 */ 00122 virtual void write(size32_t ofDest, Array<octet_t>::View vabSrc) = 0; 00123 00124 /** 00125 * Store the specified number of octets from the specified location 00126 * within the passed octet array at the specified offset within this 00127 * buffer. 00128 * 00129 * As a result of this method, the buffer length as reported by the 00130 * <tt>#length()</tt> method will become 00131 * <tt>max(#length(), ofDest + cbSrc)</tt>. 00132 * 00133 * As a result of this method, the buffer capacity as reported by the 00134 * <tt>#getCapacity()</tt> method will not change if the new 00135 * value returned by <tt>#length()</tt> would not exceed the 00136 * old value returned by <tt>#getCapacity()</tt>; otherwise, 00137 * the capacity will be increased such that <tt>{#getCapacity() 00138 * >= #length()</tt>. Regardless, it is always true that 00139 * <tt>#getCapacity() >= #length()</tt> and <tt> 00140 * #getMaximumCapacity() >= #getCapacity()</tt>. If the buffer 00141 * capacity cannot be increased due to resource constraints, an 00142 * undesignated Exception will be thrown. 00143 * 00144 * @param ofDest the offset within this buffer to store the passed 00145 * data 00146 * @param vabSrc the array containing the octets to store in this 00147 * buffer 00148 * @param ofSrc the offset within the passed octet array to copy 00149 * from 00150 * @param cbSrc the number of octets to copy from the passed octet 00151 * array 00152 * 00153 * @throws NullPointerException if <code>vabSrc</code> is NULL 00154 * @throws IndexOutOfBoundsException if <tt>ofSrc + cbSrc</tt> is 00155 * greater than <tt>vabSrc->length</tt>, or if 00156 * <tt>ofDest + cbSrc</tt> is greater than 00157 * <tt>#getMaximumCapacity()</tt> 00158 */ 00159 virtual void write(size32_t ofDest, Array<octet_t>::View vabSrc, 00160 size32_t ofSrc, size32_t cbSrc) = 0; 00161 00162 /** 00163 * Store the contents of the specified ReadBuffer at the specified 00164 * offset within this buffer. 00165 * 00166 * For purposes of side-effects and potential exceptions, this method 00167 * is functionally equivalent to the following code: 00168 * <pre><code> 00169 * Array<octet_t>::View vabSrc = vBufSrc->toOctetArray(); 00170 * write(ofDest, vabSrc, 0, vabSrc->length); 00171 * </code></pre> 00172 * 00173 * @param ofDest the offset within this buffer to store the passed 00174 * data 00175 * @param vBufSrc the array of octets to store in this buffer 00176 */ 00177 virtual void write(size32_t ofDest, ReadBuffer::View vBufSrc) = 0; 00178 00179 /** 00180 * Store the specified portion of the contents of the specified 00181 * ReadBuffer at the specified offset within this buffer. 00182 * 00183 * For purposes of side-effects and potential exceptions, this method 00184 * is functionally equivalent to the following code: 00185 * <pre><code> 00186 * Array<octet_t>::View vabSrc = vbufSrc.toOctetArray(ofSrc, cbSrc); 00187 * write(ofDest, vabSrc, 0, vabSrc->length); 00188 * </code></pre> 00189 * 00190 * @param ofDest the offset within this buffer to store the passed 00191 * data 00192 * @param vBufSrc the source ReadBuffer 00193 * @param ofSrc the offset within the passed ReadBuffer to copy 00194 * from 00195 * @param cbSrc the number of octets to copy from the passed 00196 * ReadBuffer 00197 */ 00198 virtual void write(size32_t ofDest, ReadBuffer::View vBufSrc, 00199 size32_t ofSrc, size32_t cbSrc) = 0; 00200 00201 /** 00202 * Starting with the octet at offset <tt>of</tt>, retain the remainder 00203 * of this WriteBuffer, such that the octet at offset <tt>of</tt> is 00204 * shifted to offset 0, the octet at offset <tt>of + 1</tt> is shifted 00205 * to offset 1, and so on up to the octet at offset 00206 * <tt>#length() - 1</tt>, which is shifted to offset 00207 * <tt>#length() - of - 1</tt>. After this method, the length 00208 * of of the buffer as indicated by the #length() method will 00209 * be equal to <tt>#length() - of</tt>. 00210 * 00211 * This method is functionally equivalent to the following code: 00212 * <pre><code> 00213 * retain(of, length() - of); 00214 * </code></pre> 00215 * 00216 * @param of the offset of the first octet within the WriteBuffer 00217 * that will be retained 00218 * 00219 * @throws IndexOutOfBoundsException if <tt>of</tt> is greater than 00220 * <tt>#length()</tt> 00221 */ 00222 virtual void retain(size32_t of) = 0; 00223 00224 /** 00225 * Starting with the octet at offset <tt>of</tt>, retain <tt>cb</tt> 00226 * octets in this WriteBuffer, such that the octet at offset 00227 * <tt>of</tt> is shifted to offset 0, the octet at offset <tt>of + 00228 * 1</tt> is shifted to offset 1, and so on up to the octet at offset 00229 * <tt>of + cb - 1</tt>, which is shifted to offset <tt>cb - 1</tt>. 00230 * After this method, the length of the buffer as indicated by the 00231 * #length() method will be equal to <tt>cb</tt>. 00232 * 00233 * Legal values for the offset of the first octet to retain 00234 * <tt>of</tt> are <tt>(of >= 0 && of <= #length())</tt>. 00235 * Legal values for the number of octets to retain <tt>cb</tt> are 00236 * <tt>(cb >= 0 && cb <= #length())</tt>, such that 00237 * <tt>(of + cb <= #length())</tt>. 00238 * 00239 * If <tt>cb</tt> is zero, then this method will have the same effect 00240 * as clear. If <tt>of</tt> is zero, then this method will have the 00241 * effect of truncating the data in the buffer, but no octets will be 00242 * shifted within the buffer. 00243 * 00244 * The effect on the capacity of the buffer is implementation- 00245 * specific; some implementations are expected to retain the same 00246 * capacity while others are expected to shrink accordingly. 00247 * 00248 * @param of the offset of the first octet within the WriteBuffer 00249 * that will be retained 00250 * @param cb the number of octets to retain 00251 * 00252 * @throws IndexOutOfBoundsException if <tt>of + cb</tt> is greater 00253 * than <tt>#length()</tt> 00254 */ 00255 virtual void retain(size32_t of, size32_t cb) = 0; 00256 00257 /** 00258 * Set the length of the buffer as indicated by the #length() 00259 * method to zero. 00260 * 00261 * The effect on the capacity of the buffer is implementation-specific; 00262 * some implementations are expected to retain the same capacity while 00263 * others are expected to shrink accordingly. 00264 */ 00265 virtual void clear() = 0; 00266 00267 /** 00268 * Obtain a WriteBuffer starting at a particular offset within this 00269 * WriteBuffer. 00270 * 00271 * This is functionally equivalent to: 00272 * <code><pre> 00273 * return getWriteBuffer(of, getMaximumCapacity() - of); 00274 * </pre></code> 00275 * 00276 * @param of the beginning index, inclusive 00277 * 00278 * @return a WriteBuffer that represents a portion of this WriteBuffer 00279 * 00280 * @throws IndexOutOfBoundsException if <tt>of</tt> is larger than the 00281 * <tt>#getMaximumCapacity()</tt> of this WriteBuffer 00282 */ 00283 virtual WriteBuffer::Handle getWriteBuffer(size32_t of) = 0; 00284 00285 /** 00286 * Obtain a WriteBuffer for a portion of this WriteBuffer. 00287 * 00288 * Use of the resulting buffer will correspond to using this buffer 00289 * directly but with the offset being passed to the buffer methods 00290 * automatically having <tt>of</tt> added. As a result, the length of 00291 * this buffer can be modified by writing to the new buffer; however, 00292 * changes made directly to this buffer will not affect the length of 00293 * the new buffer. 00294 * 00295 * Note that the resulting WriteBuffer is limited in the number of 00296 * octets that can be written to it; in other words, its 00297 * <tt>#getMaximumCapacity()</tt> must return the same value 00298 * as was passed in <tt>cb</tt>. 00299 * 00300 * @param of the offset of the first octet within this WriteBuffer to 00301 * map to offset 0 of the new WriteBuffer 00302 * @param cb the number of octets to cover in the resulting 00303 * WriteBuffer 00304 * 00305 * @return a WriteBuffer that represents a portion of this WriteBuffer 00306 * 00307 * @throws IndexOutOfBoundsException if <tt>of + cb</tt> is larger 00308 * than the <tt>#getMaximumCapacity()</tt> of this 00309 * WriteBuffer 00310 */ 00311 virtual WriteBuffer::Handle getWriteBuffer(size32_t of, size32_t cb) = 0; 00312 00313 /** 00314 * Get a ReadBuffer object that is a snapshot of this WriteBuffer's 00315 * data. 00316 * 00317 * This method is functionally equivalent to the following code: 00318 * <pre><code> 00319 * Array<octet_t>::View vab = toOctetArray(); 00320 * return OctetArrayReadBuffer::create(vab, 0, vab->length(), true); 00321 * </code></pre> 00322 * 00323 * @return a ReadBuffer that reflects the point-in-time contents of 00324 * this WriteBuffer; the returned ReadBuffer is inherently 00325 * immutable 00326 */ 00327 virtual ReadBuffer::View getReadBuffer() const = 0; 00328 00329 /** 00330 * Get a ReadBuffer object to read data from this buffer. This method 00331 * is not guaranteed to return a snapshot of this buffer's data, nor 00332 * is it guaranteed to return a live view of this buffer, which means 00333 * that subsequent changes to this WriteBuffer may or may not affect 00334 * the contents and / or the length of the returned ReadBuffer. 00335 * 00336 * To get a snapshot, use the #getReadBuffer() method. 00337 * 00338 * @return a ReadBuffer that reflects the contents of this WriteBuffer 00339 * but whose behavior is undefined if the WriteBuffer is 00340 * modified 00341 */ 00342 virtual ReadBuffer::View getUnsafeReadBuffer() const = 0; 00343 00344 /** 00345 * Returns an octet array that holds the complete contents of this 00346 * WriteBuffer. 00347 * 00348 * This method is functionally equivalent to the following code: 00349 * <pre><code> 00350 * return getUnsafeReadBuffer()->toOctetArray(); 00351 * </code></pre> 00352 * 00353 * @return the contents of this WriteBuffer as an octet array 00354 */ 00355 virtual Array<octet_t>::View toOctetArray() const = 0; 00356 00357 /** 00358 * Returns a new Binary object that holds the complete contents of 00359 * this WriteBuffer. 00360 * <p> 00361 * This method is functionally equivalent to the following code: 00362 * <pre><code> 00363 * return getUnsafeReadBuffer()->toBinary(); 00364 * </code></pre> 00365 * 00366 * @return the contents of this WriteBuffer as a Binary object 00367 * 00368 * @since Coherence 3.7.1 00369 */ 00370 virtual BinaryView toBinary() const = 0; 00371 00372 00373 // ----- BufferOutput inner interface ----------------------------------- 00374 00375 public: 00376 /** 00377 * The BufferOutput interface represents a data output stream on top 00378 * of a WriteBuffer. 00379 * 00380 * @author jh 2007.12.20 00381 */ 00382 class COH_EXPORT BufferOutput 00383 : public interface_spec<BufferOutput> 00384 { 00385 // ----- BufferOutput interface ----------------------------- 00386 00387 public: 00388 /** 00389 * Get the WriteBuffer object that this BufferOutput is 00390 * writing to. 00391 * 00392 * @return the underlying WriteBuffer object 00393 */ 00394 virtual WriteBuffer::Handle getBuffer() = 0; 00395 00396 /** 00397 * Get the WriteBuffer object that this BufferOutput is 00398 * writing to. 00399 * 00400 * @return the underlying WriteBuffer object 00401 */ 00402 virtual WriteBuffer::View getBuffer() const = 0; 00403 00404 /** 00405 * Determine the current offset of this BufferOutput within 00406 * the underlying WriteBuffer. 00407 * 00408 * @return the offset of the next octet to write to the 00409 * WriteBuffer 00410 */ 00411 virtual size32_t getOffset() const = 0; 00412 00413 /** 00414 * Specify the offset of the next octet to write to the 00415 * underlying WriteBuffer. 00416 * 00417 * @param of the offset of the next octet to write to the 00418 * WriteBuffer 00419 * 00420 * @throws IndexOutOfBoundsException if 00421 * <code>of > getBuffer()->getMaximumCapacity()</code> 00422 */ 00423 virtual void setOffset(size32_t of) = 0; 00424 00425 /** 00426 * Write the given octet. 00427 * 00428 * @param b the octet to write 00429 * 00430 * @throws IOException if an I/O error occurs 00431 */ 00432 virtual void write(octet_t b) = 0; 00433 00434 /** 00435 * Writes all the octets in the array <tt>vab</tt>. 00436 * 00437 * @param vab the octet array to write 00438 * 00439 * @throws IOException if an I/O error occurs 00440 * @throws NullPointerException if <tt>vab</tt> is NULL 00441 */ 00442 virtual void write(Array<octet_t>::View vab) = 0; 00443 00444 /** 00445 * Writes <code>cb</code> octets starting at offset 00446 * <code>of</code> from the array <code>vab</code>. 00447 * 00448 * @param vab the octet array to write from 00449 * @param of the offset into <code>vab</code> to start 00450 * writing from 00451 * @param cb the number of octets from <code>vab</code> to 00452 * write 00453 * 00454 * @throws IOException if an I/O error occurs 00455 * @throws NullPointerException if <code>vab</code> is NULL 00456 * @throws IndexOutOfBoundsException if <code>of+cb</code> is 00457 * greater than <code>vab->length</code> 00458 */ 00459 virtual void write(Array<octet_t>::View vab, size32_t of, 00460 size32_t cb) = 0; 00461 00462 /** 00463 * Write all the octets from the passed ReadBuffer object. 00464 * 00465 * This is functionally equivalent to the following code: 00466 * <code><pre> 00467 * getBuffer()->write(getOffset(), vBuf); 00468 * </pre></code> 00469 * 00470 * @param vBuf a ReadBuffer object 00471 * 00472 * @throws IOException if an I/O error occurs 00473 */ 00474 virtual void writeBuffer(ReadBuffer::View vBuf) = 0; 00475 00476 /** 00477 * Write <code>cb</code> octets from the passed ReadBuffer 00478 * object starting at offset <code>of</code> within the passed 00479 * ReadBuffer. 00480 * 00481 * This is functionally equivalent to the following code: 00482 * <code><pre> 00483 * getBuffer()->write(getOffset(), vbuf, of, cb); 00484 * </pre></code> 00485 * 00486 * @param vBuf a ReadBuffer object 00487 * @param of the offset within the ReadBuffer of the first 00488 * octet to write to this BufferOutput 00489 * @param cb the number of octets to write 00490 * 00491 * @throws IOException if an I/O error occurs 00492 */ 00493 virtual void writeBuffer(ReadBuffer::View vBuf, size32_t of, 00494 size32_t cb) = 0; 00495 00496 /** 00497 * Write a boolean value. 00498 * 00499 * @param f the <tt>bool</tt> to be written 00500 * 00501 * @throws IOException if an I/O error occurs 00502 */ 00503 virtual void writeBoolean(bool f) = 0; 00504 00505 /** 00506 * Write a 16-bit Unicode character value. 00507 * 00508 * @param ch the Unicode character as a <code>wchar16_t</code> 00509 * value 00510 * 00511 * @throws IOException if an I/O error occurs 00512 */ 00513 virtual void writeChar16(wchar16_t ch) = 0; 00514 00515 /** 00516 * Write a sequence of UTF-8 encoded 16-bit Unicode 00517 * characters. 00518 * 00519 * @param vs a String value to write; may be NULL 00520 * 00521 * @throws IOException if an I/O error occurs 00522 */ 00523 virtual void writeString(String::View vs) = 0; 00524 00525 /** 00526 * Write a 16-bit integer value. 00527 * 00528 * @param n the <code>int16_t</code> value to be written 00529 * 00530 * @throws IOException if an I/O error occurs 00531 */ 00532 virtual void writeInt16(int16_t n) = 0; 00533 00534 /** 00535 * Write a 32-bit integer value. 00536 * 00537 * @param n the <code>int32_t</code> value to be written 00538 * 00539 * @throws IOException if an I/O error occurs 00540 */ 00541 virtual void writeInt32(int32_t n) = 0; 00542 00543 /** 00544 * Write a 64-bit integer value. 00545 * 00546 * @param n the <code>int64_t</code> value to be written 00547 * 00548 * @throws IOException if an I/O error occurs 00549 */ 00550 virtual void writeInt64(int64_t n) = 0; 00551 00552 /** 00553 * Write a 32-bit floating-point value. 00554 * 00555 * @param fl the <code>float32_t</code> value to be written 00556 * 00557 * @throws IOException if an I/O error occurs 00558 */ 00559 virtual void writeFloat32(float32_t fl) = 0; 00560 00561 /** 00562 * Write a 64-bit floating-point value. 00563 * 00564 * @param dfl the <code>float64_t</code> value to be written 00565 * 00566 * @throws IOException if an I/O error occurs 00567 */ 00568 virtual void writeFloat64(float64_t dfl) = 0; 00569 }; 00570 00571 /** 00572 * Get a BufferOutput object to write data to this buffer starting at 00573 * a particular offset. 00574 * 00575 * Note that each call to this method will return a new BufferOutput 00576 * object, with the possible exception being that a zero-length 00577 * non-resizing WriteBuffer could always return the same instance 00578 * (since it is not writable). 00579 * 00580 * @param of the offset of the first octet of this buffer that the 00581 * BufferOutput will write to 00582 * 00583 * @return a BufferOutput that will write to this buffer 00584 */ 00585 virtual BufferOutput::Handle getBufferOutput(size32_t of = 0) = 0; 00586 00587 /** 00588 * Get a BufferOutput object to write data to this buffer. The 00589 * BufferOutput object returned by this method is set to append to the 00590 * WriteBuffer, meaning that its offset is pre-set to the 00591 * #length() of this buffer. 00592 * 00593 * This is functionally equivalent to: 00594 * <pre><code> 00595 * return getBufferOutput(length()); 00596 * </code></pre> 00597 * 00598 * @return a BufferOutput configured to append to this buffer 00599 */ 00600 virtual BufferOutput::Handle getAppendingBufferOutput() = 0; 00601 }; 00602 00603 COH_CLOSE_NAMESPACE2 00604 00605 #endif // COH_WRITE_BUFFER_HPP