io.pravega.common.util

Class ByteArraySegment

java.lang.Object

io.pravega.common.util.ByteArraySegment

All Implemented Interfaces:

ArrayView

public class ByteArraySegment
extends java.lang.Object
implements ArrayView

Allows segmenting a byte array and operating only on that segment.

Constructor Summary

Constructors

Constructor and Description
ByteArraySegment(byte[] array) Creates a new instance of the ByteArraySegment class that wraps the entire given array.
ByteArraySegment(byte[] array, int startOffset, int length) Creates a new instance of the ByteArraySegment class that wraps the given array range.
ByteArraySegment(byte[] array, int startOffset, int length, boolean readOnly) Creates a new instance of the ByteArraySegment class that wraps the given array range.
ByteArraySegment(java.nio.ByteBuffer buff) Creates a new instance of the ByteArraySegment class that wraps an array backed ByteBuffer.

Method Summary

Modifier and Type	Method and Description
byte[]	array() Gets a reference to the backing array for this ArrayView.
int	arrayOffset() Gets a value indicating the offset in the backing array where this ArrayView starts at.
ByteArraySegment	asReadOnly() Returns a new ByteArraySegment that wraps the same underlying array that this ByteSegmentDoes, except that the new instance is marked as Read-Only.
void	copyFrom(ByteArraySegment source, int targetOffset, int length) Copies a specified number of bytes from the given ByteArraySegment into this ByteArraySegment.
void	copyTo(byte[] target, int targetOffset, int length) Copies a specified number of bytes from this ArrayView into the given target array.
byte	get(int index) Gets the value at the specified index.
byte[]	getCopy() Returns a copy of the contents of this ArrayView.
int	getLength() Gets a value representing the length of this ArrayView.
java.io.InputStream	getReader() Creates an InputStream that can be used to read the contents of this ArrayView.
java.io.InputStream	getReader(int offset, int length) Creates an InputStream that can be used to read the contents of this ArrayView.
java.io.OutputStream	getWriter() Creates an OutputStream that can be used to write contents to this ByteArraySegment.
boolean	isReadOnly() Gets a value indicating whether the ByteArraySegment is read-only.
int	readFrom(java.io.InputStream stream) Attempts to read the contents of the InputStream and load it into this ByteArraySegment.
void	set(int index, byte value) Sets the value at the specified index.
ByteArraySegment	subSegment(int offset, int length) Returns a new ByteArraySegment that is a sub-segment of this ByteArraySegment.
ByteArraySegment	subSegment(int offset, int length, boolean readOnly) Returns a new ByteArraySegment that is a sub-segment of this ByteArraySegment.
void	writeTo(java.io.OutputStream stream) Writes the entire contents of this ByteArraySegment to the given OutputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

ByteArraySegment

public ByteArraySegment(byte[] array)

Creates a new instance of the ByteArraySegment class that wraps the entire given array.

Parameters:

array - The array to wrap.

Throws:

java.lang.NullPointerException - If the array is null.

ByteArraySegment

public ByteArraySegment(byte[] array,
                        int startOffset,
                        int length)

Creates a new instance of the ByteArraySegment class that wraps the given array range.

Parameters:

array - The array to wrap.

startOffset - The offset within the array to start the segment at.

length - The length of the segment.

Throws:

java.lang.NullPointerException - If the array is null.

java.lang.ArrayIndexOutOfBoundsException - If StartOffset or Length have invalid values.

ByteArraySegment

public ByteArraySegment(java.nio.ByteBuffer buff)

Creates a new instance of the ByteArraySegment class that wraps an array backed ByteBuffer.

Parameters:

buff - The ByteBuffer to wrap.

Throws:

java.lang.NullPointerException - If the array is null.

java.lang.UnsupportedOperationException - If buff is not backed by an array.

ByteArraySegment

public ByteArraySegment(byte[] array,
                        int startOffset,
                        int length,
                        boolean readOnly)

Creates a new instance of the ByteArraySegment class that wraps the given array range.

Parameters:

array - The array to wrap.

startOffset - The offset within the array to start the segment at.

length - The length of the segment.

readOnly - If true, no modifications will be allowed on the segment.

Throws:

java.lang.NullPointerException - If the array is null.

java.lang.ArrayIndexOutOfBoundsException - If StartOffset or Length have invalid values.

Method Detail

get

public byte get(int index)

Description copied from interface: ArrayView

Gets the value at the specified index.

Specified by:

get in interface ArrayView

Parameters:

index - The index to query.

Returns:

Byte indicating the value at the given index.

getLength

public int getLength()

Description copied from interface: ArrayView

Gets a value representing the length of this ArrayView.

Specified by:

getLength in interface ArrayView

Returns:

The length.

array

public byte[] array()

Description copied from interface: ArrayView

Gets a reference to the backing array for this ArrayView. This should be used in conjunction with arrayOffset() in order to determine where in the array this ArrayView starts at. NOTE: Care must be taken when using this array. Just like any other array in Java, it is modifiable and changes to it will be reflected in this ArrayView.

Specified by:

array in interface ArrayView

Returns:

The backing array.

arrayOffset

public int arrayOffset()

Description copied from interface: ArrayView

Gets a value indicating the offset in the backing array where this ArrayView starts at.

Specified by:

arrayOffset in interface ArrayView

Returns:

The offset in the backing array.

getReader

public java.io.InputStream getReader()

Description copied from interface: ArrayView

Creates an InputStream that can be used to read the contents of this ArrayView. The InputStream returned spans the entire ArrayView.

Specified by:

getReader in interface ArrayView

Returns:

The InputStream.

getReader

public java.io.InputStream getReader(int offset,
                                     int length)

Description copied from interface: ArrayView

Creates an InputStream that can be used to read the contents of this ArrayView. The InputStream returned spans the given section of the ArrayView.

Specified by:

getReader in interface ArrayView

Parameters:

offset - The starting offset of the section to read.

length - The length of the section to read.

Returns:

The InputStream.

getCopy

public byte[] getCopy()

Description copied from interface: ArrayView

Returns a copy of the contents of this ArrayView.

Specified by:

getCopy in interface ArrayView

Returns:

A byte array with the same length as this ArrayView, containing a copy of the data within it.

copyTo

public void copyTo(byte[] target,
                   int targetOffset,
                   int length)

Description copied from interface: ArrayView

Copies a specified number of bytes from this ArrayView into the given target array.

Specified by:

copyTo in interface ArrayView

Parameters:

target - The target array.

targetOffset - The offset within the target array to start copying data at.

length - The number of bytes to copy.

set

public void set(int index,
                byte value)

Sets the value at the specified index.

Parameters:

index - The index to set the value at.

value - The value to set.

Throws:

java.lang.IllegalStateException - If the ByteArraySegment is readonly.

java.lang.ArrayIndexOutOfBoundsException - If index is invalid.

isReadOnly

public boolean isReadOnly()

Gets a value indicating whether the ByteArraySegment is read-only.

Returns:

The value.

copyFrom

public void copyFrom(ByteArraySegment source,
                     int targetOffset,
                     int length)

Copies a specified number of bytes from the given ByteArraySegment into this ByteArraySegment.

Parameters:

source - The ByteArraySegment to copy bytes from.

targetOffset - The offset within this ByteArraySegment to start copying at.

length - The number of bytes to copy.

Throws:

java.lang.IllegalStateException - If the ByteArraySegment is readonly.

java.lang.ArrayIndexOutOfBoundsException - If targetOffset or length are invalid.

writeTo

public void writeTo(java.io.OutputStream stream)
             throws java.io.IOException

Writes the entire contents of this ByteArraySegment to the given OutputStream. Only copies the contents of the ByteArraySegment, and writes no other data (such as the length of the Segment or any other info).

Parameters:

stream - The OutputStream to write to.

Throws:

java.io.IOException - If the OutputStream threw one.

readFrom

public int readFrom(java.io.InputStream stream)
             throws java.io.IOException

Attempts to read the contents of the InputStream and load it into this ByteArraySegment. Up to getLength() bytes will be read from the InputStream, but no guarantees are made that the entire ByteArraySegment will be populated.

Only attempts to read the data, and does not expect any other header/footer information in the InputStream. This method is the exact reverse of writeTo().

Parameters:

stream - The InputStream to read from.

Returns:

The number of bytes read. This will be less than or equal to getLength().

Throws:

java.io.IOException - If the InputStream threw one.

getWriter

public java.io.OutputStream getWriter()

Creates an OutputStream that can be used to write contents to this ByteArraySegment. The OutputStream returned is a FixedByteArrayOutputStream (ByteArrayOutputStream that cannot expand) that spans the entire ByteArraySegment.

Returns:

The OutputStream.

Throws:

java.lang.IllegalStateException - If the ByteArraySegment is readonly.

subSegment

public ByteArraySegment subSegment(int offset,
                                   int length)

Returns a new ByteArraySegment that is a sub-segment of this ByteArraySegment. The new ByteArraySegment wraps the same underlying byte array that this ByteArraySegment does.

Parameters:

offset - The offset within this ByteArraySegment where the new ByteArraySegment starts.

length - The length of the new ByteArraySegment.

Returns:

The new ByteArraySegment.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If offset or length are invalid.

subSegment

public ByteArraySegment subSegment(int offset,
                                   int length,
                                   boolean readOnly)

Returns a new ByteArraySegment that is a sub-segment of this ByteArraySegment. The new ByteArraySegment wraps the same underlying byte array that this ByteArraySegment does.

Parameters:

offset - The offset within this ByteArraySegment where the new ByteArraySegment starts.

length - The length of the new ByteArraySegment.

readOnly - Whether the resulting sub-segment should be read-only. Note: if this ByteArraySegment is already read-only, this argument is ignored and the resulting segment is read-only

Returns:

The new ByteArraySegment.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If offset or length are invalid.

asReadOnly

public ByteArraySegment asReadOnly()

Returns a new ByteArraySegment that wraps the same underlying array that this ByteSegmentDoes, except that the new instance is marked as Read-Only. If this instance is already Read-Only, this instance is returned instead.

Returns:

A new read-only ByteArraySegment.