org.mortbay.io
Interface Buffer

All Superinterfaces:
Cloneable
All Known Implementing Classes:
AbstractBuffer, BufferCache.CachedBuffer, ByteArrayBuffer, ByteArrayBuffer.CaseInsensitive, NIOBuffer, View

public interface Buffer
extends Cloneable

Byte Buffer interface. This is a byte buffer that is designed to work like a FIFO for bytes. Puts and Gets operate on different pointers into the buffer and the valid _content of the buffer is always between the getIndex and the putIndex. This buffer interface is designed to be similar, but not dependant on the java.nio buffers, which may be used to back an implementation of this Buffer. The main difference is that NIO buffer after a put have their valid _content before the position and a flip is required to access that data. For this buffer it is always true that: markValue <= getIndex <= putIndex <= capacity

Version:
1.0
Author:
gregw

Nested Class Summary
static interface Buffer.CaseInsensitve
           
 
Field Summary
static int IMMUTABLE
           
static boolean NON_VOLATILE
           
static int READONLY
           
static int READWRITE
           
static boolean VOLATILE
           
 
Method Summary
 byte[] array()
          Get the underlying array, if one exists.
 byte[] asArray()
           
 Buffer asImmutableBuffer()
           
 Buffer asMutableBuffer()
           
 Buffer asNonVolatileBuffer()
           
 Buffer asReadOnlyBuffer()
           
 Buffer buffer()
          Get the unerlying buffer.
 int capacity()
          The capacity of the buffer.
 void clear()
          Clear the buffer.
 void compact()
          Compact the buffer by discarding bytes before the postion (or mark if set).
 boolean equalsIgnoreCase(Buffer buffer)
           
 byte get()
          Get the byte at the current getIndex and increment it.
 int get(byte[] b, int offset, int length)
          Get bytes from the current postion and put them into the passed byte array.
 Buffer get(int length)
           
 int getIndex()
          The index within the buffer that will next be read or written.
 boolean hasContent()
           
 boolean isImmutable()
           
 boolean isReadOnly()
           
 boolean isVolatile()
           
 int length()
          The number of bytes from the getIndex to the putIndex
 void mark()
          Set the mark to the current getIndex.
 void mark(int offset)
          Set the mark relative to the current getIndex
 int markIndex()
          The current index of the mark.
 byte peek()
          Get the byte at the current getIndex without incrementing the getIndex.
 byte peek(int index)
          Get the byte at a specific index in the buffer.
 int peek(int index, byte[] b, int offset, int length)
           
 Buffer peek(int index, int length)
           
 int poke(int index, Buffer src)
          Put the contents of the buffer at the specific index.
 void poke(int index, byte b)
          Put a specific byte to a specific getIndex.
 int poke(int index, byte[] b, int offset, int length)
          Put a specific byte to a specific getIndex.
 int put(Buffer src)
          Write the bytes from the source buffer to the current getIndex.
 void put(byte b)
          Put a byte to the current getIndex and increment the getIndex.
 int put(byte[] b)
          Put a byte to the current getIndex and increment the getIndex.
 int put(byte[] b, int offset, int length)
          Put a byte to the current getIndex and increment the getIndex.
 int putIndex()
          The index of the first element that should not be read.
 int readFrom(InputStream in, int max)
          Read the buffer's contents from the input stream
 void reset()
          Reset the current getIndex to the mark
 void setGetIndex(int newStart)
          Set the buffers start getIndex.
 void setMarkIndex(int newMark)
          Set a specific value for the mark.
 void setPutIndex(int newLimit)
           
 int skip(int n)
          Skip _content.
 Buffer slice()
           
 Buffer sliceFromMark()
           
 Buffer sliceFromMark(int length)
           
 int space()
          the space remaining in the buffer.
 String toDetailString()
           
 void writeTo(OutputStream out)
          Write the buffer's contents to the output stream
 

Field Detail

IMMUTABLE

static final int IMMUTABLE
See Also:
Constant Field Values

READONLY

static final int READONLY
See Also:
Constant Field Values

READWRITE

static final int READWRITE
See Also:
Constant Field Values

VOLATILE

static final boolean VOLATILE
See Also:
Constant Field Values

NON_VOLATILE

static final boolean NON_VOLATILE
See Also:
Constant Field Values
Method Detail

array

byte[] array()
Get the underlying array, if one exists.

Returns:
a byte[] backing this buffer or null if none exists.

asArray

byte[] asArray()
Returns:
a byte[] value of the bytes from the getIndex to the putIndex.

buffer

Buffer buffer()
Get the unerlying buffer. If this buffer wraps a backing buffer.

Returns:
The root backing buffer or this if there is no backing buffer;

asNonVolatileBuffer

Buffer asNonVolatileBuffer()
Returns:
a non volitile version of this Buffer value

asReadOnlyBuffer

Buffer asReadOnlyBuffer()
Returns:
a readonly version of this Buffer.

asImmutableBuffer

Buffer asImmutableBuffer()
Returns:
an immutable version of this Buffer.

asMutableBuffer

Buffer asMutableBuffer()
Returns:
an immutable version of this Buffer.

capacity

int capacity()
The capacity of the buffer. This is the maximum putIndex that may be set.

Returns:
an int value

space

int space()
the space remaining in the buffer.

Returns:
capacity - putIndex

clear

void clear()
Clear the buffer. getIndex=0, putIndex=0.


compact

void compact()
Compact the buffer by discarding bytes before the postion (or mark if set). Bytes from the getIndex (or mark) to the putIndex are moved to the beginning of the buffer and the values adjusted accordingly.


get

byte get()
Get the byte at the current getIndex and increment it.

Returns:
The byte value from the current getIndex.

get

int get(byte[] b,
        int offset,
        int length)
Get bytes from the current postion and put them into the passed byte array. The getIndex is incremented by the number of bytes copied into the array.

Parameters:
b - The byte array to fill.
offset - Offset in the array.
length - The max number of bytes to read.
Returns:
The number of bytes actually read.

get

Buffer get(int length)
Parameters:
length - an int value
Returns:
a Buffer value

getIndex

int getIndex()
The index within the buffer that will next be read or written.

Returns:
an int value >=0 <= putIndex()

hasContent

boolean hasContent()
Returns:
true of putIndex > getIndex

equalsIgnoreCase

boolean equalsIgnoreCase(Buffer buffer)
Returns:
a boolean value true if case sensitive comparison on this buffer

isImmutable

boolean isImmutable()
Returns:
a boolean value true if the buffer is immutable and that neither the buffer contents nor the indexes may be changed.

isReadOnly

boolean isReadOnly()
Returns:
a boolean value true if the buffer is readonly. The buffer indexes may be modified, but the buffer contents may not. For example a View onto an immutable Buffer will be read only.

isVolatile

boolean isVolatile()
Returns:
a boolean value true if the buffer contents may change via alternate paths than this buffer. If the contents of this buffer are to be used outside of the current context, then a copy must be made.

length

int length()
The number of bytes from the getIndex to the putIndex

Returns:
an int == putIndex()-getIndex()

mark

void mark()
Set the mark to the current getIndex.


mark

void mark(int offset)
Set the mark relative to the current getIndex

Parameters:
offset - an int value to add to the current getIndex to obtain the mark value.

markIndex

int markIndex()
The current index of the mark.

Returns:
an int index in the buffer or -1 if the mark is not set.

peek

byte peek()
Get the byte at the current getIndex without incrementing the getIndex.

Returns:
The byte value from the current getIndex.

peek

byte peek(int index)
Get the byte at a specific index in the buffer.

Parameters:
index - an int value
Returns:
a byte value

peek

Buffer peek(int index,
            int length)
Parameters:
index - an int value
length - an int value
Returns:
The Buffer value from the requested getIndex.

peek

int peek(int index,
         byte[] b,
         int offset,
         int length)
Parameters:
index - an int value
b - The byte array to peek into
offset - The offset into the array to start peeking
length - an int value
Returns:
The number of bytes actually peeked

poke

int poke(int index,
         Buffer src)
Put the contents of the buffer at the specific index.

Parameters:
index - an int value
src - a Buffer. If the source buffer is not modified
Returns:
The number of bytes actually poked

poke

void poke(int index,
          byte b)
Put a specific byte to a specific getIndex.

Parameters:
index - an int value
b - a byte value

poke

int poke(int index,
         byte[] b,
         int offset,
         int length)
Put a specific byte to a specific getIndex.

Parameters:
index - an int value
b - a byte array value
Returns:
The number of bytes actually poked

put

int put(Buffer src)
Write the bytes from the source buffer to the current getIndex.

Parameters:
src - The source Buffer it is not modified.
Returns:
The number of bytes actually poked

put

void put(byte b)
Put a byte to the current getIndex and increment the getIndex.

Parameters:
b - a byte value

put

int put(byte[] b,
        int offset,
        int length)
Put a byte to the current getIndex and increment the getIndex.

Parameters:
b - a byte value
Returns:
The number of bytes actually poked

put

int put(byte[] b)
Put a byte to the current getIndex and increment the getIndex.

Parameters:
b - a byte value
Returns:
The number of bytes actually poked

putIndex

int putIndex()
The index of the first element that should not be read.

Returns:
an int value >= getIndex()

reset

void reset()
Reset the current getIndex to the mark


setGetIndex

void setGetIndex(int newStart)
Set the buffers start getIndex.

Parameters:
newStart - an int value

setMarkIndex

void setMarkIndex(int newMark)
Set a specific value for the mark.

Parameters:
newMark - an int value

setPutIndex

void setPutIndex(int newLimit)
Parameters:
newLimit - an int value

skip

int skip(int n)
Skip _content. The getIndex is updated by min(remaining(), n)

Parameters:
n - The number of bytes to skip
Returns:
the number of bytes skipped.

slice

Buffer slice()
Returns:
a volitile Buffer from the postion to the putIndex.

sliceFromMark

Buffer sliceFromMark()
Returns:
a volitile Buffer value from the mark to the putIndex

sliceFromMark

Buffer sliceFromMark(int length)
Parameters:
length - an int value
Returns:
a valitile Buffer value from the mark of the length requested.

toDetailString

String toDetailString()
Returns:
a String value describing the state and contents of the buffer.

writeTo

void writeTo(OutputStream out)
             throws IOException
Write the buffer's contents to the output stream

Parameters:
out -
Throws:
IOException

readFrom

int readFrom(InputStream in,
             int max)
             throws IOException
Read the buffer's contents from the input stream

Parameters:
in - input stream
max - maximum number of bytes that may be read
Returns:
actual number of bytes read or -1 for EOF
Throws:
IOException