You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@activemq.apache.org by ta...@apache.org on 2007/11/30 01:47:41 UTC
svn commit: r599664 -
/activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h
Author: tabish
Date: Thu Nov 29 16:47:39 2007
New Revision: 599664
URL: http://svn.apache.org/viewvc?rev=599664&view=rev
Log:
http://issues.apache.org/activemq/browse/AMQCPP-103
Working on the NIO package
Modified:
activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h
Modified: activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h
URL: http://svn.apache.org/viewvc/activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h?rev=599664&r1=599663&r2=599664&view=diff
==============================================================================
--- activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h (original)
+++ activemq/activemq-cpp/decaf/trunk/src/main/decaf/nio/CharBuffer.h Thu Nov 29 16:47:39 2007
@@ -74,6 +74,11 @@
virtual ~CharBuffer() {}
+ /**
+ * @returns a std::string describing this object
+ */
+ virtual std::string toString() const;
+
public:
/**
@@ -171,6 +176,24 @@
throw( decaf::lang::exceptions::IndexOutOfBoundsException );
/**
+ * Compacts this buffer
+ * <p>
+ * The bytes between the buffer's current position and its limit, if any, are
+ * copied to the beginning of the buffer. That is, the byte at index
+ * p = position() is copied to index zero, the byte at index p + 1 is copied
+ * to index one, and so forth until the byte at index limit() - 1 is copied
+ * to index n = limit() - 1 - p. The buffer's position is then set to n+1 and
+ * its limit is set to its capacity. The mark, if defined, is discarded.
+ * <p>
+ * The buffer's position is set to the number of bytes copied, rather than to
+ * zero, so that an invocation of this method can be followed immediately by
+ * an invocation of another relative put method.
+ * @returns a reference to this CharBuffer
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& compact() throw( ReadOnlyBufferException );
+
+ /**
* Creates a new char buffer that shares this buffer's content.
* <p>
* The content of the new buffer will be that of this buffer. Changes to this
@@ -182,25 +205,283 @@
* this buffer is read-only.
* @returns a new char Buffer which the caller owns.
*/
- virtual ByteBuffer* duplicate();
+ virtual CharBuffer* duplicate();
/**
- * Compacts this buffer
+ * Relative get method. Reads the character at this buffer's current position,
+ * and then increments the position.
+ * @returns the char at the current position
+ * @throws BufferUnderflowException if there no more data to return
+ */
+ char get() throw ( BufferUnderflowException );
+
+ /**
+ * Absolute get method. Reads the char at the given index.
+ * @param index - the index in the Buffer where the char is to be read
+ * @returns the char that is located at the given index
+ * @throws IndexOutOfBoundsException - If index is not smaller than the
+ * buffer's limit
+ */
+ virtual char get( std::size_t index ) const
+ throw ( lang::exceptions::IndexOutOfBoundsException );
+
+ /**
+ * Relative bulk get method.
* <p>
- * The bytes between the buffer's current position and its limit, if any, are
- * copied to the beginning of the buffer. That is, the byte at index
- * p = position() is copied to index zero, the byte at index p + 1 is copied
- * to index one, and so forth until the byte at index limit() - 1 is copied
- * to index n = limit() - 1 - p. The buffer's position is then set to n+1 and
- * its limit is set to its capacity. The mark, if defined, is discarded.
+ * This method transfers chars from this buffer into the given destination
+ * vector. An invocation of this method of the form src.get(a) behaves in
+ * exactly the same way as the invocation. The vector must be sized to the
+ * amount of data that is to be read, that is to say, the caller should call
+ * buffer.resize( N ) before calling this get method.
+ * @returns a reference to this CharBuffer
+ * @throws BufferUnderflowException - If there are fewer than length chars
+ * remaining in this buffer
+ */
+ virtual CharBuffer& get( std::vector<char> buffer )
+ throw ( BufferUnderflowException );
+
+ /**
+ * Relative bulk get method.
* <p>
- * The buffer's position is set to the number of bytes copied, rather than to
- * zero, so that an invocation of this method can be followed immediately by
- * an invocation of another relative put method.
+ * This method transfers chars from this buffer into the given destination array.
+ * If there are fewer chars remaining in the buffer than are required to satisfy
+ * the request, that is, if length > remaining(), then no bytes are transferred
+ * and a BufferUnderflowException is thrown.
+ * <p>
+ * Otherwise, this method copies length chars from this buffer into the given
+ * array, starting at the current position of this buffer and at the given offset
+ * in the array. The position of this buffer is then incremented by length.
+ * <p>
+ * @param buffer - pointer to an allocated buffer to fill
+ * @param offset - position in the buffer to start filling
+ * @param length - amount of data to put in the passed buffer
+ * @returns a reference to this Buffer
+ * @throws BufferUnderflowException - If there are fewer than length chars
+ * remaining in this buffer
+ * @throws NullPointerException if the passed buffer is null.
+ */
+ virtual CharBuffer& get( char* buffer,
+ std::size_t offset,
+ std::size_t length )
+ throw( BufferUnderflowException,
+ lang::exceptions::NullPointerException );
+
+ /**
+ * Tells whether or not this buffer is backed by an accessible char array.
+ * If this method returns true then the array and arrayOffset methods may safely
+ * be invoked. Subclasses should override this method if they do not have a
+ * backing array as this class always returns true.
+ * @returns true if, and only if, this buffer is backed by an array and is not
+ * read-only
+ */
+ virtual bool hasArray() const { return true; }
+
+ /**
+ * Returns the length of this character buffer.
+ * @returns the length of this buffer from the position to the limit.
+ */
+ int length();
+
+ /**
+ * This method transfers the chars remaining in the given source buffer into
+ * this buffer. If there are more chars remaining in the source buffer than in
+ * this buffer, that is, if src.remaining() > remaining(), then no chars are
+ * transferred and a BufferOverflowException is thrown.
+ * <p>
+ * Otherwise, this method copies n = src.remaining() chars from the given
+ * buffer into this buffer, starting at each buffer's current position. The
+ * positions of both buffers are then incremented by n.
+ * @param src - the buffer to take chars from an place in this one.
+ * @returns a reference to this buffer
+ * @throws BufferOverflowException - If there is insufficient space in this
+ * buffer for the remaining chars in the source buffer
+ * @throws IllegalArgumentException - If the source buffer is this buffer
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& put( CharBuffer& src )
+ throw( BufferOverflowException, ReadOnlyBufferException,
+ lang::exceptions::IllegalArgumentException );
+
+ /**
+ * This method transfers chars into this buffer from the given source array.
+ * If there are more chars to be copied from the array than remain in this buffer,
+ * that is, if length > remaining(), then no chars are transferred and a
+ * BufferOverflowException is thrown.
+ * <p>
+ * Otherwise, this method copies length bytes from the given array into this
+ * buffer, starting at the given offset in the array and at the current position
+ * of this buffer. The position of this buffer is then incremented by length.
+ * @param buffer- The array from which chars are to be read
+ * @param offset- The offset within the array of the first char to be read;
+ * @param length - The number of chars to be read from the given array
+ * @returns a reference to this buffer
+ * @throws BufferOverflowException - If there is insufficient space in this buffer
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ * @throws NullPointerException if the passed buffer is null.
+ */
+ virtual CharBuffer& put( const char* buffer,
+ std::size_t offset,
+ std::size_t length )
+ throw( BufferOverflowException, ReadOnlyBufferException,
+ lang::exceptions::NullPointerException );
+
+ /**
+ * This method transfers the entire content of the given source char array into
+ * this buffer. This is the same as calling put( &buffer[0], 0, buffer.size()
+ * @pparam buffer - The buffer whose contents are copied to this CharBuffer
+ * @returns a reference to this buffer
+ * @throws BufferOverflowException - If there is insufficient space in this buffer
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& put( std::vector<char>& buffer )
+ throw( BufferOverflowException, ReadOnlyBufferException );
+
+ /**
+ * Writes the given char into this buffer at the current position, and then
+ * increments the position.
+ * @param value - the char value to be written
+ * @returns a reference to this buffer
+ * @throws BufferOverflowException - If this buffer's current position is not
+ * smaller than its limit
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& put( char value )
+ throw( BufferOverflowException, ReadOnlyBufferException );
+
+ /**
+ * Writes the given char into this buffer at the given index.
+ * @param index - position in the Buffer to write the data
+ * @param value - the char to write.
+ * @returns a reference to this buffer
+ * @throws IndexOutOfBoundsException - If index greater than the buffer's limit
+ * minus the size of the type being written.
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& put( std::size_t index, char value )
+ throw( lang::exceptions::IndexOutOfBoundsException,
+ ReadOnlyBufferException );
+
+ /**
+ * Relative bulk put method (optional operation).
+ * <p>
+ * This method transfers characters from the given string into this buffer. If
+ * there are more characters to be copied from the string than remain in this
+ * buffer, that is, if end - start > remaining(), then no characters are
+ * transferred and a BufferOverflowException is thrown.
+ * @returns a reference to this buffer
+ * <p>
+ * Otherwise, this method copies n = end - start characters from the given string
+ * into this buffer, starting at the given start index and at the current position
+ * of this buffer. The position of this buffer is then incremented by n.
+ * @param src - the string to copy from
+ * @param start - position in src to start from
+ * @param end - the position in src to stop at
* @returns a reference to this CharBuffer
+ * @throws BufferOverflowException - If this buffer's current position is not
+ * @throws IndexOutOfBoundsException - If index greater than the buffer's limit
+ * minus the size of the type being written.
* @throws ReadOnlyBufferException - If this buffer is read-only
*/
- virtual CharBuffer& compact() throw( ReadOnlyBufferException );
+ virtual CharBuffer& put( const std::string& src,
+ std::size_t start, std::size_t end )
+ throw( BufferOverflowException, ReadOnlyBufferException,
+ decaf::lang::exceptions::IndexOutOfBoundsException );
+
+ /**
+ * Relative bulk put method (optional operation).
+ * <p>
+ * This method transfers the entire content of the given source string into this
+ * buffer. An invocation of this method of the form dst.put(s) behaves in exactly
+ * the same way as the invocation
+ * @param src - the string to copy from
+ * @returns a reference to this CharBuffer
+ * @throws BufferOverflowException - If this buffer's current position is not
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ virtual CharBuffer& put( const std::string src )
+ throw( BufferOverflowException, ReadOnlyBufferException );
+
+ /**
+ * Attempts to read characters into the specified character buffer. The buffer is
+ * used as a repository of characters as-is: the only changes made are the results
+ * of a put operation. No flipping or rewinding of the buffer is performed.
+ * @param target - the buffer to read characters into
+ * @returns The number of characters added to the buffer, or string::npos if this
+ * source of characters is at its end
+ * @throws IOException - IF an IO error occurs
+ * @throws NullPointerException - If target is Null
+ * @throws ReadOnlyBufferException - If this buffer is read-only
+ */
+ std::size_t read( CharBuffer* target )
+ throw ( decaf::lang::exceptions::NullPointerException,
+ decaf::io::IOException, ReadOnlyBufferException );
+
+ /**
+ * Creates a new character buffer that represents the specified subsequence of
+ * this buffer, relative to the current position.
+ * <p>
+ * The new buffer will share this buffer's content; that is, if the content of
+ * this buffer is mutable then modifications to one buffer will cause the other
+ * to be modified. The new buffer's capacity will be that of this buffer, its
+ * position will be position() + start, and its limit will be position() + end.
+ * The new Buffer will be read-only if, and only if, this buffer is read-only.
+ * @param start - The index, relative to the current position, of the first
+ * character in the subsequence; must be non-negative and no larger than
+ * remaining()
+ * @param end - The index, relative to the current position, of the character
+ * following the last character in the subsequence; must be no smaller than start
+ * and no larger than remaining()
+ * @return The new character buffer, caller owns
+ * @throws IndexOutOfBoundsException - If the preconditions on start and end fail
+ */
+ CharSequence* subSequence( std::size_t start, std::size_t end )
+ throw ( decaf::lang::exceptions::IndexOutOfBoundsException );
+
+ /**
+ * Creates a new CharBuffer whose content is a shared subsequence of this
+ * buffer's content. The content of the new buffer will start at this buffer's
+ * current position. Changes to this buffer's content will be visible in the new
+ * buffer, and vice versa; the two buffers' position, limit, and mark values will
+ * be independent.
+ * <p>
+ * The new buffer's position will be zero, its capacity and its limit will be the
+ * number of bytes remaining in this buffer, and its mark will be undefined. The
+ * new buffer will be read-only if, and only if, this buffer is read-only.
+ * @returns the newly create CharBuffer which the caller owns.
+ */
+ virtual CharBuffer* slice() const;
+
+ public: // Comparable
+
+ /**
+ * Compares this object with the specified object for order. Returns a
+ * negative integer, zero, or a positive integer as this object is less
+ * than, equal to, or greater than the specified object.
+ * @param value - the Object to be compared.
+ * @returns a negative integer, zero, or a positive integer as this
+ * object is less than, equal to, or greater than the specified object.
+ */
+ virtual int compareTo( const CharBuffer& value ) const;
+
+ /**
+ * @return true if this value is considered equal to the passed value.
+ */
+ virtual bool equals( const CharBuffer& value ) const;
+
+ /**
+ * Compares equality between this object and the one passed.
+ * @param value - the value to be compared to this one.
+ * @return true if this object is equal to the one passed.
+ */
+ virtual bool operator==( const CharBuffer& value ) const;
+
+ /**
+ * Compares this object to another and returns true if this object
+ * is considered to be less than the one passed. This
+ * @param value - the value to be compared to this one.
+ * @return true if this object is equal to the one passed.
+ */
+ virtual bool operator<( const CharBuffer& value ) const;
public: // Statics
@@ -214,6 +495,70 @@
* @returns the CharBuffer that was allocated, caller owns.
*/
static CharBuffer* allocate( std::size_t capacity );
+
+ /**
+ * Wraps the passed buffer with a new CharBuffer.
+ * <p>
+ * The new buffer will be backed by the given char array; that is, modifications
+ * to the buffer will cause the array to be modified and vice versa. The new
+ * buffer's capacity will be array.length, its position will be offset, its limit
+ * will be offset + length, and its mark will be undefined. Its backing array
+ * will be the given array, and its array offset will be zero.
+ * @param buffer - The array that will back the new buffer
+ * @param offset - The offset of the subarray to be used
+ * @param length - The length of the subarray to be used
+ * @returns a new CharBuffer that is backed by buffer, caller owns.
+ */
+ static CharBuffer* wrap( char* array, std::size_t offset, std::size_t length )
+ throw( lang::exceptions::NullPointerException );
+
+ /**
+ * Wraps the passed STL char Vector in a CharBuffer.
+ * <p>
+ * The new buffer will be backed by the given char array; modifications to the
+ * buffer will cause the array to be modified and vice versa. The new buffer's
+ * capacity and limit will be buffer.size(), its position will be zero, and its
+ * mark will be undefined. Its backing array will be the given array, and its
+ * array offset will be zero.
+ * @param buffer - The vector that will back the new buffer, the vector must
+ * have been sized to the desired size already by calling vector.resize( N ).
+ * @returns a new CharBuffer that is backed by buffer, caller owns.
+ */
+ static CharBuffer* wrap( std::vector<char>& buffer );
+
+ /**
+ * Wraps a character sequence into a buffer.
+ * <p>
+ * The content of the new, read-only buffer will be the content of the given
+ * character sequence. The buffer's capacity will be csq.length(), its position
+ * will be start, its limit will be end, and its mark will be undefined.
+ * @param csq - The CharSequence that will back the new buffer
+ * @param start - The index of the first character to be used; must be non-
+ * negative and no larger than csq.length(). The new buffer's position will be
+ * set to this value.
+ * @param end - The index of the character following the last character to be
+ * used; must be no smaller than start and no larger than
+ * @returns a nre ReadOnly CharBuffer, caller owns
+ * @throws NullPointerException if csq is null.
+ * @throws IndexOutOfBoundsException if the preconditions on start and end fail
+ */
+ static CharBuffer* wrap( CharSequence* csq, std::size_t start, std::size_t end )
+ throw( lang::exceptions::NullPointerException );
+
+ /**
+ * Wraps a full CharSequence into a buffer.
+ * <p>
+ * The content of the new, read-only buffer will be the content of the given
+ * string. The new buffer's capacity and limit will be csq.length(), its position
+ * will be zero, and its mark will be undefined.
+ * <p>
+ * @param csq - The character sequence from which the new character buffer is to
+ * be created, cannot be null
+ * @returns the newly created CharBuffer, caller owns.
+ * @throws NullPointerException if csq is null.
+ */
+ static CharBuffer* wrap( CharSequence* csq )
+ throw ( decaf::lang::exceptions::NullPointerException );
};