com.ibm.websphere.objectgrid.io
Class XsDataOutputStream

java.lang.Object
  java.io.OutputStream
      com.ibm.websphere.objectgrid.io.XsDataOutputStream

All Implemented Interfaces:

Closeable, Flushable

public abstract class XsDataOutputStream
extends OutputStream

An abstract extension of standard i/o stream for writing primitive types and string in random accessible, byte-oriented, cross-language manner specifically for internal usage of WebSphere eXtreme Scale plug-ins.
This stream combines the facilities of

• sequential, on-demand resource allocation of ByteArrayOutputStream
• primitive data writing of DataOutput
• random access capability of a ByteBuffer.

Resource Allocation: The stream must grow on demand as the bytes are being written. The actual bytes being written should be allocated in a a flexible manner that allows both in-memory and off-heap allocation.

The written bytes are accessible via toByteArray() methods as a single, contiguous array of bytes. Or can be transferred to a given ByteBuffer via toByteBuffer(ByteBuffer) method.

Random Access: The data is written at the current position(). The caller can, however, position the stream at any location. If the position is beyond the current size of the stream, new bytes must be allocated.

Data Type Support: The standard fixed-length, signed, primitive Java data types are supported as in DataOutput interface. However, for cross-language data portability, this Java based interface also supports unsigned value of Java primitive types via wider signed type value. For example, an unsigned 2-byte short could be written by writeUnsignedShort(int) supplying a 4-byte integer value as input.

String Encoding: Strings are written, by default, as encoded (by UTF-8 scheme) array of bytes preceded by a 2-byte integral number designating number of encoded bytes.
The encoding scheme can be specified per string basis or default scheme can be changed via setEncodingScheme(String) method. The default encoding scheme at construction is UTF-8.
Optionally, raw encoded bytes could be written without the length header.
Optionally, a single-byte null character could be appended after the encoded bytes.

Byte Arrays: byte arrays are written directly to the output stream with no conversion. Attempting to write a null byte array will result in a NullPointerException.

Null Handling: Null Strings or array can not be written and will throw NullPointerException when supplied as input.

Byte Ordering: Multi-byte data can be written in either BIG ENDIAN or LITTLE ENDIAN form. By default, the data is written in the BIG_ENDIAN order. The user can set the default byte order.

This class is not intended as a base class for user code to extend. Instances of XsDataInputStream are provided solely by the WebSphere eXtreme Scale runtime for use by plug-ins.

Since:

7.1.1

Constructor Summary

XsDataOutputStream()

Method Summary

abstract ByteOrder	getByteOrder() Gets the byte order for writing multi-byte data.
abstract String	getEncodingScheme() Gets canonical name of the current string encoding scheme.
abstract boolean	isClosed() Affirms if this stream has been closed.
abstract int	position() Gets the current position of this stream.
abstract XsDataOutputStream	position(int i) Sets the position of this stream at the given byte index.
abstract XsDataOutputStream	rewind() Restores this stream at the initial state at its construction.
abstract boolean	setByteOrder(ByteOrder order) Sets the byte order of the data.
abstract void	setEncodingScheme(String enc) Sets the current string encoding scheme.
abstract int	size() Gets the current size of this stream in number of bytes.
abstract byte[]	toByteArray() Gets a copy of the underlying bytes.
abstract ByteBuffer	toByteBuffer(ByteBuffer buf) Writes the content of this stream on to the given buffer starting at its current position.
abstract void	writeBoolean(boolean bool) Writes a single byte for the given boolean value.
abstract void	writeByte(byte b) Writes a single byte for the signed value of the given byte.
abstract void	writeChar(char c) Writes a 2-byte value for the given character in the current byte order.
abstract void	writeChars(char[] c) Writes an array of 2-byte values for the given character in the current byte order.
abstract void	writeDouble(double d) Writes a 8-byte value for the given floating point number in the current byte order.
abstract void	writeFloat(float f) Writes a 4-byte value for the given floating point number in the current byte order.
abstract void	writeInt(int i) Writes a 4-byte value for the given integral number in the current byte order.
abstract void	writeLong(long l) Writes a 8-byte value for the given integral number in the current byte order.
abstract void	writeShort(short s) Writes a 2-byte value for the given integral number in the current byte order.
abstract int	writeString(String s) Writes the given string as array of bytes encoded in current encoding scheme.
abstract int	writeString(String s, String encoding) Writes the given string as array of bytes encoded by given encoding scheme.
abstract int	writeString(String s, String encoding, boolean raw, boolean nullTerminate) Writes the given string as array of bytes encoded by the given encoding scheme.
abstract int	writeStringAsNullTerminated(String s) Writes the given string as array of bytes encoded by current encoding scheme.
abstract int	writeStringAsNullTerminated(String s, String encoding) Writes the given string as array of bytes encoded by the given encoding scheme.
abstract int	writeStringRaw(String s) Writes the given string as array of bytes encoded by the current encoding scheme.
abstract int	writeStringRaw(String s, String encoding) Writes the given string as array of bytes encoded by the given encoding scheme.
abstract void	writeUnsignedByte(int b) Writes a single byte as the unsigned byte value (i.e.
abstract void	writeUnsignedShort(int s) Writes 2-byte as the unsigned short value (i.e.
abstract int	writeUTF8String(String s) Writes the given string as an array of bytes encoded as UTF-8.
abstract void	writeVarint(int i) Writes a variable length integer value for the given integral number.
abstract void	writeVarint(long i) Writes a variable length integer value for the given integral number.

Methods inherited from class java.io.OutputStream

close, flush, write, write, write

Methods inherited from class java.lang.Object

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

Constructor Detail

XsDataOutputStream

public XsDataOutputStream()

Method Detail

size

public abstract int size()

Gets the current size of this stream in number of bytes. Size of the stream denotes the maximum position where a byte is ever written.

position

public abstract int position()

Gets the current position of this stream. The current position denotes where the next byte will be written.

position

public abstract XsDataOutputStream position(int i)
                                     throws IOException

Sets the position of this stream at the given byte index. The position denotes where the next byte will be written.

Throws:

IOException

rewind

public abstract XsDataOutputStream rewind()
                                   throws IOException

Restores this stream at the initial state at its construction.

Throws:

IOException

toByteArray

public abstract byte[] toByteArray()

Gets a copy of the underlying bytes.

Returns:

an array of bytes. Length of the array is equal to current size.

toByteBuffer

public abstract ByteBuffer toByteBuffer(ByteBuffer buf)
                                 throws IOException

Writes the content of this stream on to the given buffer starting at its current position.

Parameters:

buf - a buffer where the content of this stream will be written.

Returns:

the given buffer with modified content.

Throws:

IOException

writeBoolean

public abstract void writeBoolean(boolean bool)
                           throws IOException

Writes a single byte for the given boolean value.

Throws:

IOException

writeByte

public abstract void writeByte(byte b)
                        throws IOException

Writes a single byte for the signed value of the given byte.

Throws:

IOException

writeUnsignedByte

public abstract void writeUnsignedByte(int b)
                                throws IOException

Writes a single byte as the unsigned byte value (i.e. least significant byte) of the given integer.

Throws:

IOException

writeChar

public abstract void writeChar(char c)
                        throws IOException

Writes a 2-byte value for the given character in the current byte order.

Throws:

IOException

writeChars

public abstract void writeChars(char[] c)
                         throws IOException

Writes an array of 2-byte values for the given character in the current byte order.

Throws:

IOException

writeInt

public abstract void writeInt(int i)
                       throws IOException

Writes a 4-byte value for the given integral number in the current byte order.

Throws:

IOException

writeFloat

public abstract void writeFloat(float f)
                         throws IOException

Writes a 4-byte value for the given floating point number in the current byte order.

Throws:

IOException

writeDouble

public abstract void writeDouble(double d)
                          throws IOException

Writes a 8-byte value for the given floating point number in the current byte order.

Throws:

IOException

writeLong

public abstract void writeLong(long l)
                        throws IOException

Writes a 8-byte value for the given integral number in the current byte order.

Throws:

IOException

writeShort

public abstract void writeShort(short s)
                         throws IOException

Writes a 2-byte value for the given integral number in the current byte order.

Throws:

IOException

writeUnsignedShort

public abstract void writeUnsignedShort(int s)
                                 throws IOException

Writes 2-byte as the unsigned short value (i.e. 2 least significant bytes) of the given integer in the current byte order.

Throws:

IOException

writeVarint

public abstract void writeVarint(int i)
                          throws IOException

Writes a variable length integer value for the given integral number.

Throws:

IOException

writeVarint

public abstract void writeVarint(long i)
                          throws IOException

Writes a variable length integer value for the given integral number.

Throws:

IOException

writeString

public abstract int writeString(String s)
                         throws IOException

Writes the given string as array of bytes encoded in current encoding scheme. The number of encoded bytes is written as a 2-byte integral value before the actual bytes.

Parameters:

s - a string. Must not be null.

Returns:

total number of bytes written to the stream

Throws:

IOException

NullPointerException - is the given string is null.

IllegalArgumentException - when the byte length cannot be encoded in a 2-byte integral value

writeString

public abstract int writeString(String s,
                                String encoding)
                         throws IOException,
                                UnsupportedEncodingException

Writes the given string as array of bytes encoded by given encoding scheme. The number of encoded bytes is written as a 2-byte integral value before the actual bytes.

Parameters:

s - a string. Must not be null.

encoding - canonical name of a supported encoding scheme

Returns:

total number of bytes written to the stream

Throws:

IOException

NullPointerException - is the given string is null.

UnsupportedEncodingException

IllegalArgumentException - when the byte length cannot be encoded in a 2-byte integral value

writeStringAsNullTerminated

public abstract int writeStringAsNullTerminated(String s)
                                         throws IOException

Writes the given string as array of bytes encoded by current encoding scheme. The number of bytes is not written before the actual bytes. But a single byte null character is written at the end.

Parameters:

s - a string. Must not be null.

Returns:

total number of bytes written to the stream

Throws:

IOException

writeStringAsNullTerminated

public abstract int writeStringAsNullTerminated(String s,
                                                String encoding)
                                         throws IOException

Writes the given string as array of bytes encoded by the given encoding scheme. The number of bytes is not written before the actual bytes. But a single byte null character is written at the end.

Parameters:

s - a string. Must not be null.

encoding - canonical name of a supported encoding scheme

Returns:

total number of bytes written to the stream

Throws:

IOException

writeStringRaw

public abstract int writeStringRaw(String s)
                            throws IOException

Writes the given string as array of bytes encoded by the current encoding scheme. The number of bytes is not written before the actual bytes.

Parameters:

s - a string. Must not be null.

Returns:

total number of bytes written to the stream

Throws:

IOException

writeStringRaw

public abstract int writeStringRaw(String s,
                                   String encoding)
                            throws IOException

Writes the given string as array of bytes encoded by the given encoding scheme. The number of encoded bytes is not written before the actual bytes.

Parameters:

s - a string. Must not be null.

encoding - canonical name of a supported encoding scheme

Returns:

total number of bytes written to the stream

Throws:

IOException

writeString

public abstract int writeString(String s,
                                String encoding,
                                boolean raw,
                                boolean nullTerminate)
                         throws IOException

Writes the given string as array of bytes encoded by the given encoding scheme.

Parameters:

s - a string. Must not be null.

encoding - canonical name of a supported encoding scheme

raw - if true, 2-byte length header is not written before the bytes.

nullTerminate - if true a single-byte null character is written at end of encoded bytes.

Returns:

total number of bytes written to the stream

Throws:

IOException

IllegalArgumentException - when raw is false, and the byte length cannot be encoded in a 2-byte integral value

writeUTF8String

public abstract int writeUTF8String(String s)
                             throws IOException

Writes the given string as an array of bytes encoded as UTF-8. This method always prepends the string with a varint value to indicate the number of UTF-8 bytes that are encoded.

Parameters:

s - a string. Must not be null

Returns:

total number of bytes written to the stream

Throws:

IOException

getEncodingScheme

public abstract String getEncodingScheme()

Gets canonical name of the current string encoding scheme. By default, the encoding scheme is UTF-8.

setEncodingScheme

public abstract void setEncodingScheme(String enc)

Sets the current string encoding scheme.

Parameters:

enc - canonical name of an encoding scheme.

setByteOrder

public abstract boolean setByteOrder(ByteOrder order)

Sets the byte order of the data.

Parameters:

order - BIG_ENDIAN or LITTLE_ENDIAN byte order

Returns:

if the given order is different than the native order of the platform.

getByteOrder

public abstract ByteOrder getByteOrder()

Gets the byte order for writing multi-byte data.

Returns:

BIG_ENDIAN or LITTLE_ENDIAN byte order

isClosed

public abstract boolean isClosed()

Affirms if this stream has been closed.