|
CoherenceTM v3.3 Copyright© 2000-2007 by Oracle Corporation |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface WriteBuffer
The WriteBuffer interface represents an in-memory block of binary data that is being accumulated (written to). It is analogous to the byte[] inside a Java ByteArrayOutputStream.
Nested Class Summary | |
---|---|
static interface |
WriteBuffer.BufferOutput
The BufferOutput interface represents a DataOutputStream on top of a WriteBuffer. |
Method Summary | |
---|---|
void |
clear()
Set the length of the buffer as indicated by the length()
method to zero. |
Object |
clone()
Create a clone of this WriteBuffer object. |
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. |
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. |
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. |
int |
length()
Determine the length of the data that is in the buffer. |
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 length() - 1, which is shifted to offset
length() - of - 1. |
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. |
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. |
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. |
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. |
Method Detail |
---|
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);
ofDest
- the offset within this buffer to store the passed datab
- the byte to store in this buffervoid 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);
ofDest
- the offset within this buffer to store the passed dataabSrc
- the array of bytes to store in this buffervoid write(int ofDest, byte[] abSrc, int ofSrc, int cbSrc)
As a result of this method, the buffer length as reported by the
length()
method will become
Math.max(length()
, ofDest + cbSrc).
As a result of this method, the buffer capacity as reported by the
getCapacity()
method will not change if the new value
returned by length()
would not exceed the old value
returned by getCapacity()
; otherwise, the capacity
will be increased such that
getCapacity()
>= length()
. Regardless, it is
always true that getCapacity()
>= length()
and getMaximumCapacity()
>= getCapacity()
.
If the buffer capacity cannot be increased due to resource constraints,
an undesignated Error or RuntimeException will be thrown, such as
OutOfMemoryError.
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 array
NullPointerException
- if abSrc
is
null
IndexOutOfBoundsException
- if ofDest,
ofSrc or cbSrc is negative, if
ofSrc + cbSrc is greater than
abSrc.length, or if ofDest + cbSrc is
greater than getMaximumCapacity()
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);
ofDest
- the offset within this buffer to store the passed databufSrc
- the array of bytes to store in this buffervoid 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);
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 ReadBuffervoid 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);
ofDest
- the offset within this buffer to store the passed datastream
- the stream of bytes to read and store in this buffer
IOException
- if an IOException occurs reading from the
passed streamvoid 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);
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 buffer
IOException
- if an IOException occurs reading from the
passed streamint length()
void retain(int of)
length()
- 1, which is shifted to offset
length()
- of - 1. After this method, the length of
of the buffer as indicated by the length()
method will be
equal to length()
- of.
This method is functionally equivalent to the following code:
retain(of, length() - of);
of
- the offset of the first byte within the WriteBuffer that
will be retained
IndexOutOfBoundsException
- if of is negative or if
of is greater than length()
void retain(int of, int cb)
length()
method will
be equal to cb.
Legal values for the offset of the first byte to retain of are
(of >= 0 && of <= length()
). Legal values for the
number of bytes to retain cb are
(cb >= 0 && cb <= length()
), such that
(of + cb <= 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.
of
- the offset of the first byte within the WriteBuffer that
will be retainedcb
- the number of bytes to retain
IndexOutOfBoundsException
- if of or cb is
negative of if of + cb is greater than
length()
void clear()
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.
int getCapacity()
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 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.
int getMaximumCapacity()
WriteBuffer getWriteBuffer(int of)
This is functionally equivalent to:
return getWriteBuffer(of, getMaximumCapacity() - of);
of
- the beginning index, inclusive
IndexOutOfBoundsException
- if of is
negative, or of is larger than the
getMaximumCapacity()
of this
WriteBuffer objectWriteBuffer 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
getMaximumCapacity()
must return the same value as
was passed in cb.
of
- the offset of the first byte within this BufferOutput
to map to offset 0 of the new BufferOutputcb
- the number of bytes to cover in the resulting WriteBuffer
IndexOutOfBoundsException
- if of or cb
is negative, or of + cb is larger than
the getMaximumCapacity()
of this
WriteBuffer objectWriteBuffer.BufferOutput getBufferOutput()
This is functionally equivalent to:
return getBufferOutput(0);
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;
of
- the offset of the first byte of this buffer that the
BufferOutput will write to
WriteBuffer.BufferOutput getAppendingBufferOutput()
length()
of this buffer.
This is functionally equivalent to:
return getBufferOutput(length());
ReadBuffer getReadBuffer()
This method is functionally equivalent to the following code:
ReadBuffer buf = getUnsafeReadBuffer();
byte[] ab = buf.toByteArray();
return new ByteArrayReadBuffer(ab);
ReadBuffer getUnsafeReadBuffer()
To get a snapshot, use the getReadBuffer()
method.
byte[] toByteArray()
This method is functionally equivalent to the following code:
return getUnsafeReadBuffer().toByteArray();
Binary toBinary()
This method is functionally equivalent to the following code:
return getUnsafeReadBuffer().toBinary();
Object clone()
|
CoherenceTM v3.3 Copyright© 2000-2007 by Oracle Corporation |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |