com.sun.labs.minion.util.buffer
Interface WriteableBuffer

All Superinterfaces:
Buffer
All Known Implementing Classes:
ArrayBuffer, FileWriteableBuffer, NIOBuffer, StdBufferImpl

public interface WriteableBuffer
extends Buffer

An interface for buffers that can be written to. The main operations supported by such buffers are the put methods that allow a single byte to be placed on the buffer, and the various byteEncode methods that allow a single integer to be encoded using a specified number of bytes or to be encoded in the minimal number of bytes using a 7 bit encoding. Additionally, we allow strings to be encoded onto a buffer using a UTF-8 encoding.

Writeable buffers can be written to a number of different outputs. Implementing classes may check for specific instances of the various outputs in order to provide faster output.

It is an absolute requirement that implementations be able to grow as needed: users of the buffers will expect this to be the case.


Method Summary
 WriteableBuffer append(ReadableBuffer b)
          Appends a readable buffer onto this buffer.
 WriteableBuffer append(ReadableBuffer b, int n)
          Appends a given number of bytes from a readable buffer onto this buffer.
 WriteableBuffer byteEncode(int pos, long n, int nBytes)
          Encodes a positive long directly, using a given number of bytes, starting at the given position in the buffer.
 int byteEncode(long n)
          Encodes an integer in a byte-aligned fashion, using the minimal number of bytes.
 WriteableBuffer byteEncode(long n, int nBytes)
          Encodes a long directly, using a given number of bytes.
 WriteableBuffer capacity(int n)
          Sets the capacity of the buffer to the given amount.
 WriteableBuffer clear()
          Clears out the buffer.
 WriteableBuffer encode(java.lang.CharSequence s)
          Encodes a character sequence onto this buffer.
 WriteableBuffer encode(float f)
          Encodes a floating point value in 4 bytes.
 ReadableBuffer getReadableBuffer()
          Gets a readable buffer from this writeable one.
 WriteableBuffer or(ReadableBuffer b)
          Computes the logical OR of this buffer and another.
 WriteableBuffer put(byte b)
          Puts a single byte onto this buffer.
 WriteableBuffer put(int p, byte b)
          Puts a single byte onto this buffer at the given position.
 WriteableBuffer set(int bitIndex)
          Sets the given bit to 1.
 void write(java.nio.ByteBuffer b)
          Write the buffer to a new IO buffer.
 void write(java.io.DataOutput o)
          Write the buffer to a data output.
 void write(java.io.OutputStream os)
          Write the buffer to a stream.
 void write(java.nio.channels.WritableByteChannel chan)
          Write the buffer to a channel.
 WriteableBuffer xor(ReadableBuffer b)
          Computes the logical XOR of this buffer and another.
 
Methods inherited from interface com.sun.labs.minion.util.buffer.Buffer
limit, limit, position, position, remaining
 

Method Detail

capacity

WriteableBuffer capacity(int n)
Sets the capacity of the buffer to the given amount.

Parameters:
n - The number of bytes that the buffer must be able to store.
Returns:
The buffer, for chained invocations.

put

WriteableBuffer put(byte b)
Puts a single byte onto this buffer.

Parameters:
b - The byte to put on the buffer
Returns:
This buffer, for chained invocations.

put

WriteableBuffer put(int p,
                    byte b)
Puts a single byte onto this buffer at the given position.

Parameters:
p - The position where the byte should be put.
b - The byte to put on the buffer
Returns:
This buffer, for chained invocations.

byteEncode

WriteableBuffer byteEncode(long n,
                           int nBytes)
Encodes a long directly, using a given number of bytes. Note that if n is negative, and nBytes is less than 8, it's likely that you will not be able to recover the actual number.

Parameters:
n - The number to encode.
nBytes - The number of bytes to use in the encoding.
Returns:
The buffer, to allow chained invocations.

byteEncode

WriteableBuffer byteEncode(int pos,
                           long n,
                           int nBytes)
Encodes a positive long directly, using a given number of bytes, starting at the given position in the buffer.

Parameters:
pos - The position in the buffer where we should start encoding.
n - The number to encode.
nBytes - The number of bytes to use in the encoding.
Returns:
The buffer, to allow chained invocations.
Throws:
java.lang.ArithmeticException - if the integer to encode is less than 0.

byteEncode

int byteEncode(long n)
               throws java.lang.ArithmeticException
Encodes an integer in a byte-aligned fashion, using the minimal number of bytes. The basic idea: use the 7 lower order bits of a byte to encode a number. If the 8th bit is 0, then there are no further bytes in this number. If the 8th bit is one, then the next byte continues the number. Note that this means that a number that would completly fill an integer will take 5 bytes to encode.

Parameters:
n - The number to encode.
Returns:
the number of bytes used to encode the number.
Throws:
java.lang.ArithmeticException - if the integer to encode is less than 0.

encode

WriteableBuffer encode(float f)
Encodes a floating point value in 4 bytes.

Parameters:
f - the floating point number to encode
Returns:
the buffer

append

WriteableBuffer append(ReadableBuffer b)
Appends a readable buffer onto this buffer.

Parameters:
b - The buffer that we wish to append onto this buffer.
Returns:
The buffer, to allow chained invocations.

append

WriteableBuffer append(ReadableBuffer b,
                       int n)
Appends a given number of bytes from a readable buffer onto this buffer.

Parameters:
b - The buffer that we wish to append onto this buffer.
n - The number of bytes to append onto this buffer.
Returns:
The buffer, to allow chained invocations.

or

WriteableBuffer or(ReadableBuffer b)
Computes the logical OR of this buffer and another.

Parameters:
b - The buffer to or with this one.
Returns:
The buffer, to allow chained invocations.

xor

WriteableBuffer xor(ReadableBuffer b)
Computes the logical XOR of this buffer and another.

Parameters:
b - The buffer to or with this one.
Returns:
The buffer, to allow chained invocations.

encode

WriteableBuffer encode(java.lang.CharSequence s)
Encodes a character sequence onto this buffer. The sequence is encoded in the following way: first, the number of bytes used to encode the string is encoded using the byteEncode method. Then, the characters in the sequence are encoded using a UTF-8 encoding.

Parameters:
s - The sequence to encode
Returns:
The buffer, to allow chained invocations.

set

WriteableBuffer set(int bitIndex)
Sets the given bit to 1.

Parameters:
bitIndex - the index of the bit to set to 1.
Returns:
This buffer, for chained invocations.

clear

WriteableBuffer clear()
Clears out the buffer.

Returns:
This buffer, for chained invocations.

getReadableBuffer

ReadableBuffer getReadableBuffer()
Gets a readable buffer from this writeable one. It is OK for the readable version of the buffer to share the representation of the buffer contents.

Returns:
A version of this buffer as a readable buffer. The readable buffer may share the underlying representation with the writeable buffer, but this is not required.

write

void write(java.nio.ByteBuffer b)
Write the buffer to a new IO buffer.

Parameters:
b - The java.nio buffer to which we will write this buffer.

write

void write(java.nio.channels.WritableByteChannel chan)
           throws java.io.IOException
Write the buffer to a channel.

Parameters:
chan - The channel to which the buffer should be written.
Throws:
java.io.IOException - if there is any error writing the buffer.

write

void write(java.io.DataOutput o)
           throws java.io.IOException
Write the buffer to a data output.

Parameters:
o - The output to which the buffer should be written.
Throws:
java.io.IOException - If there is any error writing the buffer.

write

void write(java.io.OutputStream os)
           throws java.io.IOException
Write the buffer to a stream.

Parameters:
os - The stream to which the buffer should be written.
Throws:
java.io.IOException - If there is any error writing the buffer.