C++ Client API Reference for Oracle Coherence
14c (14.1.2.0.0)

F79659-03

coherence/io/WriteBuffer.hpp

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
Copyright © 2000, 2025, Oracle and/or its affiliates. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.