public abstract class AbstractWriteBuffer extends Object implements WriteBuffer
This implementation is explicitly not thread-safe.
Modifier and Type | Class and Description |
---|---|
class |
AbstractWriteBuffer.AbstractBufferOutput
AbstractBufferOutput is a concrete implementation of BufferOutput for the non-concrete AbstractWriteBuffer implementation.
|
WriteBuffer.BufferOutput
Modifier and Type | Field and Description |
---|---|
protected static int |
CHAR_BUF_MASK
Bitmask used against a raw offset to determine the offset within the temporary character buffer.
|
protected static int |
CHAR_BUF_SIZE
Size of the temporary character buffer.
|
protected char[] |
m_achBuf
A lazily instantiated temp buffer used to avoid allocations from
String.toCharArray() and repeated calls to String.charAt(int) . |
static Binary |
NO_BINARY
An empty Binary object.
|
static byte[] |
NO_BYTES
An empty byte array (by definition immutable).
|
Constructor and Description |
---|
AbstractWriteBuffer() |
Modifier and Type | Method and Description |
---|---|
void |
clear()
Set the length of the buffer as indicated by the
WriteBuffer.length() method to zero. |
Object |
clone()
Create a clone of this WriteBuffer object.
|
protected void |
copyBufferInputPortion(int ofDest, ReadBuffer.BufferInput inSrc, int cbSrc)
Read a portion of the specified BufferInput and write it to the specified offset within this buffer.
|
protected int |
copyBufferInputRemainder(int ofDest, ReadBuffer.BufferInput inSrc, int cbMax)
Read the remaining contents of the specified BufferInput and write it to the specified offset within this buffer.
|
protected int |
copyStream(int ofDest, InputStreaming stream, int cbMax)
Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
|
WriteBuffer.BufferOutput |
getAppendingBufferOutput()
Get a BufferOutput object to write data to this buffer.
|
WriteBuffer.BufferOutput |
getBufferOutput()
Get a BufferOutput object to write data to this buffer, starting at the beginning of the WriteBuffer.
|
WriteBuffer.BufferOutput |
getBufferOutput(int of)
Get a BufferOutput object to write data to this buffer starting at a particular offset.
|
abstract int |
getCapacity()
Determine the number of bytes that the buffer can hold without resizing itself.
|
int |
getMaximumCapacity()
Determine the maximum number of bytes that the buffer can hold.
|
ReadBuffer |
getReadBuffer()
Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.
|
abstract ReadBuffer |
getUnsafeReadBuffer()
Get a ReadBuffer object to read data from this buffer.
|
WriteBuffer |
getWriteBuffer(int of)
Obtain a WriteBuffer starting at a particular offset within this WriteBuffer.
|
WriteBuffer |
getWriteBuffer(int of, int cb)
Obtain a WriteBuffer for a portion of this WriteBuffer.
|
abstract int |
length()
Determine the length of the data that is in the buffer.
|
protected void |
releaseBuffers()
Release the internal buffers held by the WriteBuffer.
|
void |
retain(int of)
Starting with the byte at offset of, retain the remainder of this WriteBuffer, such that the byte at offset of is shifted to offset 0, the byte at offset of + 1 is shifted to offset 1, and so on up to the byte at offset
WriteBuffer.length() - 1, which is shifted to offset WriteBuffer.length() - of - 1. |
abstract void |
retain(int of, int cb)
Starting with the byte at offset of, retain cb bytes in this WriteBuffer, such that the byte at offset of is shifted to offset 0, the byte at offset of + 1 is shifted to offset 1, and so on up to the byte at offset of + cb - 1, which is shifted to offset cb - 1.
|
protected byte[] |
tmpbuf()
Get a small buffer for formating data to bytes.
|
protected byte[] |
tmpbuf(int cb)
Get a buffer for formating data to bytes.
|
Binary |
toBinary()
Returns a new Binary object that holds the complete contents of this WriteBuffer.
|
byte[] |
toByteArray()
Returns a new byte array that holds the complete contents of this WriteBuffer.
|
abstract void |
write(int ofDest, byte b)
Store the specified byte at the specified offset within the buffer.
|
void |
write(int ofDest, byte[] abSrc)
Store the specified bytes at the specified offset within the buffer.
|
abstract void |
write(int ofDest, byte[] abSrc, int ofSrc, int cbSrc)
Store the specified number of bytes from the specified location within the passed byte array at the specified offset within this buffer.
|
void |
write(int ofDest, InputStreaming stream)
Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
|
void |
write(int ofDest, InputStreaming stream, int cbSrc)
Store the specified number of bytes from the specified InputStreaming object at the specified offset within this buffer.
|
void |
write(int ofDest, ReadBuffer bufSrc)
Store the contents of the specified ReadBuffer at the specified offset within this buffer.
|
void |
write(int ofDest, ReadBuffer bufSrc, int ofSrc, int cbSrc)
Store the specified portion of the contents of the specified ReadBuffer at the specified offset within this buffer.
|
public static final byte[] NO_BYTES
public static final Binary NO_BINARY
protected static final int CHAR_BUF_SIZE
Size is: 256 characters (.25 KB).
protected static final int CHAR_BUF_MASK
protected transient char[] m_achBuf
String.toCharArray()
and repeated calls to String.charAt(int)
.public abstract void write(int ofDest, byte b)
For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:
byte[] abSrc = new byte[1];
abSrc[0] = b;
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed datab
- the byte to store in this bufferpublic void write(int ofDest, byte[] abSrc)
For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed dataabSrc
- the array of bytes to store in this bufferpublic abstract void write(int ofDest, byte[] abSrc, int ofSrc, int cbSrc)
As a result of this method, the buffer length as reported by the WriteBuffer.length()
method will become Math.max(WriteBuffer.length()
, ofDest + cbSrc).
As a result of this method, the buffer capacity as reported by the WriteBuffer.getCapacity()
method will not change if the new value returned by WriteBuffer.length()
would not exceed the old value returned by WriteBuffer.getCapacity()
; otherwise, the capacity will be increased such that WriteBuffer.getCapacity()
>= WriteBuffer.length()
. Regardless, it is always true that WriteBuffer.getCapacity()
>= WriteBuffer.length()
and WriteBuffer.getMaximumCapacity()
>= WriteBuffer.getCapacity()
. If the buffer capacity cannot be increased due to resource constraints, an undesignated Error or RuntimeException will be thrown, such as OutOfMemoryError.
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed dataabSrc
- the array containing the bytes to store in this bufferofSrc
- the offset within the passed byte array to copy fromcbSrc
- the number of bytes to copy from the passed byte arraypublic void write(int ofDest, ReadBuffer bufSrc)
For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:
byte[] abSrc = bufSrc.toByteArray();
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed databufSrc
- the array of bytes to store in this bufferpublic void write(int ofDest, ReadBuffer bufSrc, int ofSrc, int cbSrc)
For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:
byte[] abSrc = bufSrc.toByteArray(ofSrc, cbSrc);
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed databufSrc
- the array of bytes to store in this bufferofSrc
- the offset within the passed ReadBuffer to copy fromcbSrc
- the number of bytes to copy from the passed ReadBufferpublic void write(int ofDest, InputStreaming stream) throws IOException
For purposes of side-effects and potential exceptions, this method is functionally similar to the following code:
ByteArrayOutputStream streamOut = new ByteArrayOutputStream();
int b;
while ((b = stream.read()) >= 0)
{
streamOut.write(b);
}
byte[] abSrc = streamOut.toByteArray();
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed datastream
- the stream of bytes to read and store in this bufferIOException
- if an IOException occurs reading from the passed streampublic void write(int ofDest, InputStreaming stream, int cbSrc) throws IOException
For purposes of side-effects and potential exceptions, this method is functionally similar to the following code:
DataInputStream streamData = new DataInputStream(
new WrapperInputStream(stream));
byte[] abSrc = new byte[cbSrc];
streamData.readFully(abSrc);
write(ofDest, abSrc, 0, abSrc.length);
write
in interface WriteBuffer
ofDest
- the offset within this buffer to store the passed datastream
- the stream of bytes to read and store in this buffercbSrc
- the exact number of bytes to read from the stream and put in this bufferIOException
- if an IOException occurs reading from the passed streampublic abstract int length()
length
in interface WriteBuffer
public void retain(int of)
WriteBuffer.length()
- 1, which is shifted to offset WriteBuffer.length()
- of - 1. After this method, the length of of the buffer as indicated by the WriteBuffer.length()
method will be equal to WriteBuffer.length()
- of.
This method is functionally equivalent to the following code:
retain(of, length() - of);
retain
in interface WriteBuffer
of
- the offset of the first byte within the WriteBuffer that will be retainedpublic abstract void retain(int of, int cb)
WriteBuffer.length()
method will be equal to cb.
Legal values for the offset of the first byte to retain of are (of >= 0 && of <= WriteBuffer.length()
). Legal values for the number of bytes to retain cb are (cb >= 0 && cb <= WriteBuffer.length()
), such that (of + cb <= WriteBuffer.length()
).
If cb is zero, then this method will have the same effect as clear. If of is zero, then this method will have the effect of truncating the data in the buffer, but no bytes will be shifted within the buffer.
The effect on the capacity of the buffer is implementation-specific; some implementations are expected to retain the same capacity while others are expected to shrink accordingly.
retain
in interface WriteBuffer
of
- the offset of the first byte within the WriteBuffer that will be retainedcb
- the number of bytes to retainpublic void clear()
WriteBuffer.length()
method to zero.
The effect on the capacity of the buffer is implementation-specific; some implementations are expected to retain the same capacity while others are expected to shrink accordingly.
clear
in interface WriteBuffer
public abstract int getCapacity()
WriteBuffer.length()
bytes that can be written to it without overflowing the current underlying buffer allocation. Since the buffer is an abstract concept, the actual mechanism for the underlying buffer is not known, but it could be a Java NIO buffer, or a byte array, etc.
Note that if the maximum size returned by WriteBuffer.getMaximumCapacity()
is greater than the current size returned by this method, then the WriteBuffer will automatically resize itself to allocate more space when the amount of data written to it passes the current size.
getCapacity
in interface WriteBuffer
public int getMaximumCapacity()
getMaximumCapacity
in interface WriteBuffer
public WriteBuffer getWriteBuffer(int of)
This is functionally equivalent to:
return getWriteBuffer(of, getMaximumCapacity() - of);
getWriteBuffer
in interface WriteBuffer
of
- the beginning index, inclusivepublic WriteBuffer getWriteBuffer(int of, int cb)
Use of the resulting buffer will correspond to using this buffer directly but with the offset being passed to the buffer methods automatically having of added. As a result, the length of this buffer can be modified by writing to the new buffer; however, changes made directly to this buffer will not affect the length of the new buffer.
Note that the resulting WriteBuffer is limited in the number of bytes that can be written to it; in other words, its WriteBuffer.getMaximumCapacity()
must return the same value as was passed in cb.
getWriteBuffer
in interface WriteBuffer
of
- the offset of the first byte within this WriteBuffer to map to offset 0 of the new WriteBuffercb
- the number of bytes to cover in the resulting WriteBufferpublic WriteBuffer.BufferOutput getBufferOutput()
This is functionally equivalent to:
return getBufferOutput(0);
getBufferOutput
in interface WriteBuffer
public WriteBuffer.BufferOutput getBufferOutput(int of)
Note that each call to this method will return a new BufferOutput object, with the possible exception being that a zero-length non-resizing WriteBuffer could always return the same instance (since it is not writable).
This is functionally equivalent to:
BufferOutput bufout = getBufferOutput();
bufout.setOffset(of);
return bufout;
getBufferOutput
in interface WriteBuffer
of
- the offset of the first byte of this buffer that the BufferOutput will write topublic WriteBuffer.BufferOutput getAppendingBufferOutput()
WriteBuffer.length()
of this buffer.
This is functionally equivalent to:
return getBufferOutput(length());
getAppendingBufferOutput
in interface WriteBuffer
public ReadBuffer getReadBuffer()
This method is functionally equivalent to the following code:
ReadBuffer buf = getUnsafeReadBuffer();
byte[] ab = buf.toByteArray();
return new ByteArrayReadBuffer(ab);
getReadBuffer
in interface WriteBuffer
public abstract ReadBuffer getUnsafeReadBuffer()
To get a snapshot, use the WriteBuffer.getReadBuffer()
method.
getUnsafeReadBuffer
in interface WriteBuffer
public byte[] toByteArray()
This method is functionally equivalent to the following code:
return getUnsafeReadBuffer().toByteArray();
toByteArray
in interface WriteBuffer
public Binary toBinary()
This method is functionally equivalent to the following code:
return getUnsafeReadBuffer().toBinary();
toBinary
in interface WriteBuffer
public Object clone()
clone
in interface WriteBuffer
clone
in class Object
protected void copyBufferInputPortion(int ofDest, ReadBuffer.BufferInput inSrc, int cbSrc) throws IOException
ofDest
- the offset within this buffer to store the passed datainSrc
- the BufferInput to read data from to copy to this buffercbSrc
- the exact number of bytes to read from the passed BufferInputIOException
- if an IOException occurs reading from the passed streamprotected int copyBufferInputRemainder(int ofDest, ReadBuffer.BufferInput inSrc, int cbMax) throws IOException
ofDest
- the offset within this buffer to store the passed datainSrc
- the BufferInput to read and store in this buffercbMax
- the maximum number of bytes to copyIOException
- if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source streamprotected int copyStream(int ofDest, InputStreaming stream, int cbMax) throws IOException
ofDest
- the offset within this buffer to store the passed datastream
- the stream of bytes to read and store in this buffercbMax
- the maximum number of bytes to copyIOException
- if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source streamprotected byte[] tmpbuf()
MIN_BUF
bytes longprotected byte[] tmpbuf(int cb)
protected final void releaseBuffers()