ImmutableBuffer (TrueCommons I/O 2.3.4 API)

java.lang.Object
- net.java.truecommons.io.PowerBuffer<ImmutableBuffer>
- - net.java.truecommons.io.ImmutableBuffer

All Implemented Interfaces:

Cloneable, Comparable<ImmutableBuffer>
```
@Immutable
public final class ImmutableBuffer
extends PowerBuffer<ImmutableBuffer>
```
A power buffer with immutable properties. This class is a drop-in replacement for ByteBuffer, so you can use an ImmutableBuffer wherever you would otherwise use a ByteBuffer.
This class protects the identity and state of its adapted byte buffer, but it does not protect its contents. Any attempt to obtain the adapted byte buffer() or change its state results in an UnsupportedOperationException. However, you may be able to change the adapted byte buffer's content with absolute put operations unless the buffer is also read-only.
This class is designed to be provided as a method parameter where the caller does not want the callee to change the state of the buffer. Consider the following method signature:
```
void parse(ImmutableBuffer input) throws InvalidDataException;
 
```
Given this signature, it's clear to a caller that the callee cannot change the buffer's state, so it need not worry about that. While a similar effect could get achieved by creating a ByteBuffer.duplicate() of the buffer before calling this method, using an ImmutableBuffer avoids the need to document what the callee is allowed or expected to do with the state of the given buffer because its immutable by design. Furthermore, an ImmutableBuffer can be passed around to any methods without the need to make a protective copy before each call, thereby preventing the pollution of the heap's Eden space and saving some CPU cycles.
Mind again that in order to protect the buffer's content, a caller still needs to call asReadOnlyBuffer().
Since:

TrueCommons 2.1

Author:

Christian Schlichtherle

See Also:
asMutableBuffer()

Method Summary

Methods
Modifier and Type	Method and Description
`byte[]`	`array()` Deprecated.
`ImmutableBuffer`	`asImmutableBuffer()` Returns an immutable buffer view of the adapted byte buffer.
`MutableBuffer`	`asMutableBuffer()` Returns a mutable buffer view of the adapted byte buffer.
`ImmutableBuffer`	`asReadOnlyBuffer()`
`ImmutableBuffer`	`bigEndian()` Deprecated.
`ByteBuffer`	`buffer()` Deprecated.
`ImmutableBuffer`	`clear()` Deprecated.
`ImmutableBuffer`	`compact()` Deprecated.
`ImmutableBuffer`	`duplicate()`
`ImmutableBuffer`	`flip()` Deprecated.
`byte`	`get()` Deprecated.
`ImmutableBuffer`	`get(byte[] dst)` Deprecated.
`ImmutableBuffer`	`get(byte[] dst, int offset, int length)` Deprecated.
`char`	`getChar()` Deprecated.
`double`	`getDouble()` Deprecated.
`float`	`getFloat()` Deprecated.
`int`	`getInt()` Deprecated.
`long`	`getLong()` Deprecated.
`short`	`getShort()` Deprecated.
`int`	`getUByte()` Deprecated.
`long`	`getUInt()` Deprecated.
`int`	`getUShort()` Deprecated.
`boolean`	`isMutable()` Returns `true` if and only if this power buffer is mutable.
`ImmutableBuffer`	`limit(int newLimit)` Deprecated.
`ImmutableBuffer`	`littleEndian()` Deprecated.
`ImmutableBuffer`	`load(ReadableByteChannel channel)` Deprecated.
`ImmutableBuffer`	`mark()` Deprecated.
`ImmutableBuffer`	`order(ByteOrder order)` Deprecated.
`ImmutableBuffer`	`position(int newPosition)` Deprecated.
`ImmutableBuffer`	`put(byte b)` Deprecated.
`ImmutableBuffer`	`put(byte[] src)` Deprecated.
`ImmutableBuffer`	`put(byte[] src, int offset, int length)` Deprecated.
`ImmutableBuffer`	`put(ByteBuffer src)` Deprecated.
`ImmutableBuffer`	`putChar(char value)` Deprecated.
`ImmutableBuffer`	`putDouble(double value)` Deprecated.
`ImmutableBuffer`	`putFloat(float value)` Deprecated.
`ImmutableBuffer`	`putInt(int value)` Deprecated.
`ImmutableBuffer`	`putLong(long value)` Deprecated.
`ImmutableBuffer`	`putShort(short value)` Deprecated.
`ImmutableBuffer`	`reset()` Deprecated.
`ImmutableBuffer`	`rewind()` Deprecated.
`ImmutableBuffer`	`save(WritableByteChannel channel)` Deprecated.
`ImmutableBuffer`	`skip(int skip)` Deprecated.
`ImmutableBuffer`	`slice()`
`static ImmutableBuffer`	`wrap(byte[] array)`
`static ImmutableBuffer`	`wrap(byte[] array, int offset, int length)`
`static ImmutableBuffer`	`wrap(ByteBuffer buf)` Constructs a new immutable buffer which adapts the given byte `buffer`.

Methods inherited from class net.java.truecommons.io.PowerBuffer
allocate, allocateDirect, arrayOffset, asCharBuffer, asDoubleBuffer, asFloatBuffer, asIntBuffer, asLongBuffer, asShortBuffer, capacity, clone, compareTo, equals, get, getChar, getDouble, getFloat, getInt, getLong, getShort, getUByte, getUInt, getUShort, hasArray, hashCode, hasRemaining, isDirect, isReadOnly, limit, order, position, put, put, putChar, putDouble, putFloat, putInt, putLong, putShort, remaining, toString

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - array
```
@Deprecated
public byte[] array()
```
    Deprecated.
    
    Overrides:
    
    array in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.array()
  - asImmutableBuffer
```
public ImmutableBuffer asImmutableBuffer()
```
    Description copied from class: PowerBuffer
    
    Returns an immutable buffer view of the adapted byte buffer. The properties of the returned buffer are equal to the properties of this buffer, including its byte PowerBuffer.order().
    
    Specified by:
    
    asImmutableBuffer in class PowerBuffer<ImmutableBuffer>
  - asMutableBuffer
```
public MutableBuffer asMutableBuffer()
```
    Description copied from class: PowerBuffer
    
    Returns a mutable buffer view of the adapted byte buffer. The properties of the returned buffer are equal to the properties of this buffer, including its byte PowerBuffer.order().
    
    Specified by:
    
    asMutableBuffer in class PowerBuffer<ImmutableBuffer>
  - asReadOnlyBuffer
```
public ImmutableBuffer asReadOnlyBuffer()
```
    Specified by:
    
    asReadOnlyBuffer in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.asReadOnlyBuffer()
  - bigEndian
```
@Deprecated
public ImmutableBuffer bigEndian()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Sets the byte order to big endian.
    
    Overrides:
    
    bigEndian in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    this.
  - buffer
```
@Deprecated
public ByteBuffer buffer()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Returns the adapted byte buffer.
    
    Overrides:
    
    buffer in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    The adapted byte buffer.
  - clear
```
@Deprecated
public ImmutableBuffer clear()
```
    Deprecated.
    
    Overrides:
    
    clear in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.clear()
  - compact
```
@Deprecated
public ImmutableBuffer compact()
```
    Deprecated.
    
    Overrides:
    
    compact in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.compact()
  - duplicate
```
public ImmutableBuffer duplicate()
```
    Specified by:
    
    duplicate in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.duplicate()
  - flip
```
@Deprecated
public ImmutableBuffer flip()
```
    Deprecated.
    
    Overrides:
    
    flip in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.flip()
  - get
```
@Deprecated
public byte get()
```
    Deprecated.
    
    Overrides:
    
    get in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.get()
  - get
```
@Deprecated
public ImmutableBuffer get(byte[] dst)
```
    Deprecated.
    
    Overrides:
    
    get in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.get(byte[])
  - get
```
@Deprecated
public ImmutableBuffer get(byte[] dst,
                             int offset,
                             int length)
```
    Deprecated.
    
    Overrides:
    
    get in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.get(byte[], int, int)
  - getChar
```
@Deprecated
public char getChar()
```
    Deprecated.
    
    Overrides:
    
    getChar in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getChar()
  - getDouble
```
@Deprecated
public double getDouble()
```
    Deprecated.
    
    Overrides:
    
    getDouble in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getDouble()
  - getFloat
```
@Deprecated
public float getFloat()
```
    Deprecated.
    
    Overrides:
    
    getFloat in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getFloat()
  - getInt
```
@Deprecated
public int getInt()
```
    Deprecated.
    
    Overrides:
    
    getInt in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getInt()
  - getLong
```
@Deprecated
public long getLong()
```
    Deprecated.
    
    Overrides:
    
    getLong in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getLong()
  - getShort
```
@Deprecated
public short getShort()
```
    Deprecated.
    
    Overrides:
    
    getShort in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.getShort()
  - getUByte
```
@Deprecated
public int getUByte()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Reads an unsigned byte from the current position.
    
    Overrides:
    
    getUByte in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    The unsigned byte, cast to an integer.
  - getUInt
```
@Deprecated
public long getUInt()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Reads an unsigned int from the current position.
    
    Overrides:
    
    getUInt in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    The unsigned int, cast to a long.
  - getUShort
```
@Deprecated
public int getUShort()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Reads an unsigned short from the current position.
    
    Overrides:
    
    getUShort in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    The unsigned short, cast to an integer.
  - isMutable
```
public boolean isMutable()
```
    Description copied from class: PowerBuffer
    
    Returns true if and only if this power buffer is mutable.
    
    Specified by:
    
    isMutable in class PowerBuffer<ImmutableBuffer>
  - limit
```
@Deprecated
public ImmutableBuffer limit(int newLimit)
```
    Deprecated.
    
    Overrides:
    
    limit in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.limit(int)
  - littleEndian
```
@Deprecated
public ImmutableBuffer littleEndian()
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Sets the byte order to little endian.
    
    Overrides:
    
    littleEndian in class PowerBuffer<ImmutableBuffer>
    
    Returns:
    this.
  - load
```
@Deprecated
public ImmutableBuffer load(ReadableByteChannel channel)
                     throws IOException
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Marks this buffer, reads all remaining bytes from the given channel and resets this buffer. If an IOException occurs or the end-of-file is reached before this buffer has been entirely filled, then it does not get reset and the IOException or an EOFException gets thrown respectively.
    
    Overrides:
    
    load in class PowerBuffer<ImmutableBuffer>
    
    Parameters:
    channel - the channel.
    
    Returns:
    this.
    
    Throws:
    
    EOFException - on unexpected end-of-file.
    
    IOException - on any I/O error.
  - mark
```
@Deprecated
public ImmutableBuffer mark()
```
    Deprecated.
    
    Overrides:
    
    mark in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.mark()
  - order
```
@Deprecated
public ImmutableBuffer order(ByteOrder order)
```
    Deprecated.
    
    Overrides:
    
    order in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.order(ByteOrder)
  - position
```
@Deprecated
public ImmutableBuffer position(int newPosition)
```
    Deprecated.
    
    Overrides:
    
    position in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.position(int)
  - put
```
@Deprecated
public ImmutableBuffer put(byte b)
```
    Deprecated.
    
    Overrides:
    
    put in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.put(byte)
  - put
```
@Deprecated
public ImmutableBuffer put(byte[] src)
```
    Deprecated.
    
    Overrides:
    
    put in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.put(byte[])
  - put
```
@Deprecated
public ImmutableBuffer put(byte[] src,
                             int offset,
                             int length)
```
    Deprecated.
    
    Overrides:
    
    put in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.put(byte[], int, int)
  - put
```
@Deprecated
public ImmutableBuffer put(ByteBuffer src)
```
    Deprecated.
    
    Overrides:
    
    put in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.put(ByteBuffer)
  - putChar
```
@Deprecated
public ImmutableBuffer putChar(char value)
```
    Deprecated.
    
    Overrides:
    
    putChar in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putChar(char)
  - putDouble
```
@Deprecated
public ImmutableBuffer putDouble(double value)
```
    Deprecated.
    
    Overrides:
    
    putDouble in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putDouble(double)
  - putFloat
```
@Deprecated
public ImmutableBuffer putFloat(float value)
```
    Deprecated.
    
    Overrides:
    
    putFloat in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putFloat(float)
  - putInt
```
@Deprecated
public ImmutableBuffer putInt(int value)
```
    Deprecated.
    
    Overrides:
    
    putInt in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putInt(int)
  - putLong
```
@Deprecated
public ImmutableBuffer putLong(long value)
```
    Deprecated.
    
    Overrides:
    
    putLong in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putLong(long)
  - putShort
```
@Deprecated
public ImmutableBuffer putShort(short value)
```
    Deprecated.
    
    Overrides:
    
    putShort in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.putShort(short)
  - reset
```
@Deprecated
public ImmutableBuffer reset()
```
    Deprecated.
    
    Overrides:
    
    reset in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.reset()
  - rewind
```
@Deprecated
public ImmutableBuffer rewind()
```
    Deprecated.
    
    Overrides:
    
    rewind in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    Buffer.rewind()
  - save
```
@Deprecated
public ImmutableBuffer save(WritableByteChannel channel)
                     throws IOException
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Marks this buffer, writes all remaining bytes to the given channel and resets this buffer. If an IOException occurs, then this buffer does not get reset and the IOException gets thrown.
    
    Overrides:
    
    save in class PowerBuffer<ImmutableBuffer>
    
    Parameters:
    channel - the channel.
    
    Returns:
    this.
    
    Throws:
    
    IOException - on any I/O error.
  - skip
```
@Deprecated
public ImmutableBuffer skip(int skip)
```
    Deprecated.
    
    Description copied from class: PowerBuffer
    
    Skips the given number of bytes. This is a relative move operation to the buffer's position.
    
    Overrides:
    
    skip in class PowerBuffer<ImmutableBuffer>
    
    Parameters:
    skip - the number of bytes to move forwards. May be negative to move backwards, too.
    
    Returns:
    this.
  - slice
```
public ImmutableBuffer slice()
```
    Specified by:
    
    slice in class PowerBuffer<ImmutableBuffer>
    
    See Also:
    ByteBuffer.slice()
  - wrap
```
public static ImmutableBuffer wrap(byte[] array)
```
    See Also:
    ByteBuffer.wrap(byte[])
  - wrap
```
public static ImmutableBuffer wrap(byte[] array,
                   int offset,
                   int length)
```
    See Also:
    ByteBuffer.wrap(byte[], int, int)
  - wrap
```
public static ImmutableBuffer wrap(ByteBuffer buf)
```
    Constructs a new immutable buffer which adapts the given byte buffer.
    
    Parameters:
    buf - the byte buffer to adapt.
    
    Returns:
    a new immutable buffer.

Class ImmutableBuffer

Method Summary

Methods inherited from class net.java.truecommons.io.PowerBuffer

Methods inherited from class java.lang.Object

Method Detail

array

asImmutableBuffer

asMutableBuffer

asReadOnlyBuffer

bigEndian

buffer

clear

compact

duplicate

flip

get

get

get

getChar

getDouble

getFloat

getInt

getLong

getShort

getUByte

getUInt

getUShort

isMutable

limit

littleEndian

load

mark

order

position

put

put

put

put

putChar

putDouble

putFloat

putInt

putLong

putShort

reset

rewind

save

skip

slice

wrap

wrap

wrap