jespa.io

Class ByteBuffer

java.lang.Object

jespa.io.ByteBuffer

public class ByteBuffer
extends java.lang.Object

This class encapsulates a byte array with start, index and length state and is used to encode and decode arbitrary binary formats. The data in the buffer may simultaneously be written to and read from IO streams.

When encoding (or reading) data into a ByteBuffer, the underlying byte array will automatically be resized as necessary.

In practice subclasses should define methods that are ideal for the target format (ASN.1, MPEG, PDF, ... etc) but methods for encoding and decoding integers are included.

This class is similar in purpose to java.nio.ByteBuffer, java.io.ByteArray{InputStream,OutputStream} and java.io.Data{InputStream,OutputStream}.

Field Summary

Fields

Modifier and Type	Field and Description
protected byte[]	buf
protected int	db
protected int	de
protected int	di
protected int	frame
protected ByteBuffer	master
protected int	start

Constructor Summary

Constructors

Constructor and Description
ByteBuffer() Create an empty buffer.
ByteBuffer(byte[] buf, int off, int len) Create a buffer with the supplied array with data at offset off of size len.

Method Summary

Modifier and Type	Method and Description
void	advance(int n) Advance the current buffer index by n.
int	align(int boundary) Advance the current buffer index to the next multiple of boundry.
int	align(int boundary, byte value) Advance the current buffer index to the next multiple of boundry and fill any padding bytes with the supplied byte value.
void	compact() This will invalidate any derived buffers.
void	decodeBytes(byte[] dst, int off, int len) Copy the bytes from the underlying byte array into the supplied byte array and advance the current buffer index.
int	decodeUint16be()
int	decodeUint16le()
int	decodeUint32be()
int	decodeUint32le()
long	decodeUint64be()
long	decodeUint64le()
byte	decodeUint8()
ByteBuffer	derive(int index) Return a new ByteBuffer that shares the same underlying buffer, start and length but with an independent index.
void	encodeBytes(byte[] src, int off, int len) Copy the supplied bytes into the underlying byte array and advance the current buffer index.
void	encodeUint16be(int u16)
void	encodeUint16le(int u16)
void	encodeUint32be(int u32)
void	encodeUint32le(int u32)
void	encodeUint64be(long u64)
void	encodeUint64le(long u64)
void	encodeUint8(int u8)
protected void	ensureSpace(int len) If necessary, the underlying byte array to be resized to accommodate the specified amount of space relative to the current buffer index.
byte[]	getBuffer()
int	getFrame() Get the frame index relative to the "start" position.
int	getIndex() Get the current index relative to the "start" position.
int	getLength() Get the length of the data in the buffer.
int	getRemaining() Return the amount of data in the buffer relative to the current index.
int	getStart() Return the "start" position.
int	getTailspace() Return the amount of space available at the end of the buffer.
void	hexdump(java.io.PrintStream out, int index, int len)
int	read(java.io.InputStream in)
void	reset()
void	setFrame(int index) Set the frame index relative to the "start" position.
void	setIndex(int index) Set the current index relative to the "start" position.
void	setStart() Set the "start" position of the underlying byte[] array to the current index.
int	shift(int index, boolean compact)
byte[]	toByteArray()
java.lang.String	toString()
int	write(java.io.OutputStream out, int index, boolean advance)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

master

protected ByteBuffer master

buf

protected byte[] buf

start

protected int start

db

protected int db

di

protected int di

de

protected int de

frame

protected int frame

Constructor Detail

ByteBuffer

public ByteBuffer(byte[] buf,
                  int off,
                  int len)

Create a buffer with the supplied array with data at offset off of size len.

Parameters:

buf - the underlying byte array of this buffer.

off - the offset within buf to the data of interest.

len - the length of data starting at off.

ByteBuffer

public ByteBuffer()

Create an empty buffer.

Method Detail

reset

public void reset()

derive

public ByteBuffer derive(int index)

Return a new ByteBuffer that shares the same underlying buffer, start and length but with an independent index. A derived ByteBuffer may be used to encode or decode a sub-segment of a message without affecting the original buffer's index position.

Derived buffers are invalid if compact() is called.

getBuffer

public byte[] getBuffer()

setStart

public void setStart()

Set the "start" position of the underlying byte[] array to the current index. All indexes used by other methods of this class are relative to the "start". Alignment is computed relative to the "start" position. A series of buffer transformations should yield the same result even though the start position within the underlying byte[] array may be different.

getStart

public int getStart()

Return the "start" position. The start index is relative to the underlying byte array whereas all other indexes used by other methods of this class are relative to the "start" index. Alignment is computed relative to the "start" position.

Note: The start position can be negative. For example, this buffer might be used to manage only a small fragment of a potentially large disk file without reading the enture file into memory.

setIndex

public void setIndex(int index)

Set the current index relative to the "start" position.

getIndex

public int getIndex()

Get the current index relative to the "start" position.

setFrame

public void setFrame(int index)

Set the frame index relative to the "start" position.

The "frame" index value has no impact on the behavior of other methods of this class. However, the intent is that it be used to mark the position up to which data may be written out with write(java.io.OutputStream, int, boolean). Framing is used for I/O multiplexing.

Parameters:

index - the index marking the end of the "frame".

getFrame

public int getFrame()

Get the frame index relative to the "start" position.

getLength

public int getLength()

Get the length of the data in the buffer. The length of the data in the buffer is the data end minus the data begining. The data end is advanced as new data is encoded into the buffer with the encode* methods or read into the buffer with read(java.io.InputStream). The data begining is only advanced by write(java.io.OutputStream, int, boolean) or shift(int, boolean).

getTailspace

public int getTailspace()

Return the amount of space available at the end of the buffer. This method is used to determine how much data can be encoded (or read) into the buffer without causing the underlying byte array to be resized.

getRemaining

public int getRemaining()

Return the amount of data in the buffer relative to the current index. This method is used to determine how much data remains to be decoded (or written).

ensureSpace

protected void ensureSpace(int len)

If necessary, the underlying byte array to be resized to accommodate the specified amount of space relative to the current buffer index. The byte array size is always increased by a power of 2.

For example, with an underlying byte array size of 64 and current buffer index of 50, calling ensureSpace(200) would cause the underlying byte array to resized to 256 bytes because 50 + 200 is 250 and 256 is the next power of 2 that hold 250 bytes.

advance

public void advance(int n)

Advance the current buffer index by n.

Parameters:

n - the number of bytes to advance the index.

align

public int align(int boundary)

Advance the current buffer index to the next multiple of boundry.

align

public int align(int boundary,
                 byte value)

Advance the current buffer index to the next multiple of boundry and fill any padding bytes with the supplied byte value.

encodeBytes

public void encodeBytes(byte[] src,
                        int off,
                        int len)
                 throws EncodingException

Copy the supplied bytes into the underlying byte array and advance the current buffer index.

Throws:

EncodingException

decodeBytes

public void decodeBytes(byte[] dst,
                        int off,
                        int len)
                 throws EncodingException

Copy the bytes from the underlying byte array into the supplied byte array and advance the current buffer index. It is an error to attempt to read more data than there is available.

Parameters:

dst -

Throws:

EncodingException - if the len parameter exceeds the amount of remaining data.

encodeUint8

public void encodeUint8(int u8)

encodeUint16le

public void encodeUint16le(int u16)

encodeUint16be

public void encodeUint16be(int u16)

encodeUint32le

public void encodeUint32le(int u32)

encodeUint32be

public void encodeUint32be(int u32)

encodeUint64le

public void encodeUint64le(long u64)

encodeUint64be

public void encodeUint64be(long u64)

decodeUint8

public byte decodeUint8()

decodeUint16le

public int decodeUint16le()

decodeUint16be

public int decodeUint16be()

decodeUint32le

public int decodeUint32le()

decodeUint32be

public int decodeUint32be()

decodeUint64le

public long decodeUint64le()

decodeUint64be

public long decodeUint64be()

compact

public void compact()

This will invalidate any derived buffers.

write

public int write(java.io.OutputStream out,
                 int index,
                 boolean advance)
          throws java.io.IOException

Throws:

java.io.IOException

shift

public int shift(int index,
                 boolean compact)

read

public int read(java.io.InputStream in)
         throws java.io.IOException

Throws:

java.io.IOException

toByteArray

public byte[] toByteArray()

hexdump

public void hexdump(java.io.PrintStream out,
                    int index,
                    int len)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object