Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/io/WriteBuffer.hpp

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