XsDataOutputStream (IBM WebSphere eXtreme Scale API Specification)

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

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable
```
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

Constructors
Constructor and Description

XsDataOutputStream()

Constructors
Constructor and Description
`XsDataOutputStream()`

Method Summary

Methods
Modifier and Type	Method and Description
`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
    Since:
    
    8.6
  - 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
    Since:
    
    8.6
  - writeVarint
```
public abstract void writeVarint(long i)
                          throws IOException
```
    Writes a variable length integer value for the given integral number.
    
    Throws:
    
    IOException
    Since:
    
    8.6
  - 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
    Since:
    
    8.6
  - 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.

Class XsDataOutputStream

Constructor Summary

Method Summary

Methods inherited from class java.io.OutputStream

Methods inherited from class java.lang.Object

Constructor Detail

XsDataOutputStream

Method Detail

size

position

position

rewind

toByteArray

toByteBuffer

writeBoolean

writeByte

writeUnsignedByte

writeChar

writeChars

writeInt

writeFloat

writeDouble

writeLong

writeShort

writeUnsignedShort

writeVarint

writeVarint

writeString

writeString

writeStringAsNullTerminated

writeStringAsNullTerminated

writeStringRaw

writeStringRaw

writeString

writeUTF8String

getEncodingScheme

setEncodingScheme

setByteOrder

getByteOrder

isClosed