com.streambase.sb

Class ByteArrayView

java.lang.Object

com.streambase.sb.ByteArrayView

All Implemented Interfaces:

com.streambase.sb.internal.CloneableData, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<ByteArrayView>

public abstract class ByteArrayView
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<ByteArrayView>, java.lang.Cloneable, com.streambase.sb.internal.CloneableData

This class represents a StreamBase blob. Please read the following class documentation and method javadoc carefully as care must be taken when manipulating blobs represented by a ByteArrayView in a running application.

ByteArrayView provides an immutable window onto a byte[] or a part of one, specified with an offset and length. It provides convenience routines to create new windows on the current view as either ByteArrayViews or ByteBuffers.

Only the copy() methods copy the underlying data, so changes in the parent byte[] will be reflected in the view's results

Note: The ByteArrayView and its underlying Blob object should not be modified in-place by a StreamBase application. Modifying a Blob may introduce race conditions. If you do need to modify a Blob's data, create a new Blob or ByteArrayView object to receive the result. Use copy methods such as ByteArrayView.copyBytes(), and create a new ByteArrayView with ByteArrayView.makeView(byte[]) and return it when needed.

Note: Serializations of instances of this class that are created (e.g., by using ObjectOutputStream) in one version of StreamBase in general will not be deserializable in any other version of StreamBase.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
ByteArrayView()

Method Summary

Modifier and Type	Method and Description
abstract byte[]	array() Returns a reference to the backing array for this view.
java.lang.String	asString()
ByteArrayView	clone() Implement Object.clone, which just delegates to ByteArrayView.copy().
int	compareTo(ByteArrayView rhs) compare this ByteArrayView to another lexigraphically NB: no data is copied when doing this
abstract ByteArrayView	copy() Create a new ByteArrayView which wraps a new byte[] containing a copy of this view's data NB: this method copies the underlying data
abstract ByteArrayView	copy(int offset, int length) Create a new ByteArrayView which wraps a new byte[] containing a copy of this view's data NB: this method copies the underlying data
abstract byte[]	copyBytes() Create a new byte[] containing a copy of this view's data.
abstract byte[]	copyBytes(int offset, int length) Create a new byte[] containing a copy of this view's data within the provided window.
boolean	equals(java.lang.Object obj) check if two ByteArrayViews are byte-for-byte identical NB: this may devolve to a byte by byte comparison
byte	get(int pos)
int	hashCode()
abstract int	length() return the length of this view NB: no data is copied when doing this
static ByteArrayView	makeCopiedView(byte[] bytes) Create a new ByteArrayView which wraps the entire provided byte[] (which is copied) NB: The bytes are copied
static ByteArrayView	makeCopiedView(byte[] bytes, int offset, int length) Create a new ByteArrayView which wraps the provided byte[] (which is copied) between offset and length from offset NB: The bytes are copied
static ByteArrayView	makeView(byte[] bytes) Create a new ByteArrayView which wraps the entire provided byte[] NB: no data is copied when doing this
static ByteArrayView	makeView(byte[] bytes, int offset, int length) Create a new ByteArrayView which wraps the provided byte[] between offset and length from offset NB: no data is copied when doing this
static ByteArrayView	makeView(java.lang.String s) Create a new ByteArrayView which converts the provided string to bytes and wraps it.
abstract int	offset() return the offset into the backing array of this view NB: no data is copied when doing this
abstract ByteArrayView	slice(int offset, int length) Create a new ByteArrayView which wraps a portion of this one NB: no data is copied when doing this
java.lang.String	toString() Formats a ByteArrayView by printing out every byte as a char.
abstract java.nio.ByteBuffer	view() Create a new ByteBuffer which wraps all of this one NB: no data is copied when doing this
abstract java.nio.ByteBuffer	view(int offset, int length) Create a new ByteBuffer which wraps a portion of this one NB: no data is copied when doing this

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ByteArrayView

public ByteArrayView()

Method Detail

makeView

public static ByteArrayView makeView(byte[] bytes)

Create a new ByteArrayView which wraps the entire provided byte[] NB: no data is copied when doing this

Parameters:

bytes - the data to be viewed

Returns:

the new ByteArrayView

makeView

public static ByteArrayView makeView(byte[] bytes,
                                     int offset,
                                     int length)

Create a new ByteArrayView which wraps the provided byte[] between offset and length from offset NB: no data is copied when doing this

Parameters:

bytes - the data to be viewed

offset - the initial offset of the window

length - the length of the window

Returns:

the new ByteArrayView

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > bytes.length

makeCopiedView

public static ByteArrayView makeCopiedView(byte[] bytes)

Create a new ByteArrayView which wraps the entire provided byte[] (which is copied) NB: The bytes are copied

Parameters:

bytes - the data to be copied and viewed

Returns:

the new ByteArrayView

Since:

6.3.13

makeCopiedView

public static ByteArrayView makeCopiedView(byte[] bytes,
                                           int offset,
                                           int length)

Create a new ByteArrayView which wraps the provided byte[] (which is copied) between offset and length from offset NB: The bytes are copied

Parameters:

bytes - the data to be copied and viewed

offset - the initial offset of the window

length - the length of the window

Returns:

the new ByteArrayView

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > bytes.length

Since:

6.3.13

makeView

public static ByteArrayView makeView(java.lang.String s)

Create a new ByteArrayView which converts the provided string to bytes and wraps it. NB: no data is copied when doing this

Parameters:

s - the String to be viewed

Returns:

the new ByteArrayView

Since:

6.3.13

slice

public abstract ByteArrayView slice(int offset,
                                    int length)

Create a new ByteArrayView which wraps a portion of this one NB: no data is copied when doing this

Parameters:

offset - the initial offset of the window (relative to the current window)

length - the length of the window

Returns:

the new ByteArrayView

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > length()

view

public abstract java.nio.ByteBuffer view(int offset,
                                         int length)

Create a new ByteBuffer which wraps a portion of this one NB: no data is copied when doing this

Parameters:

offset - the initial offset of the window (relative to the current window)

length - the length of the window

Returns:

a ByteBuffer whose arrayOffset() and limit() are the offset and length provided

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > length()

view

public abstract java.nio.ByteBuffer view()

Create a new ByteBuffer which wraps all of this one NB: no data is copied when doing this

Returns:

a ByteBuffer whose arrayOffset() and limit() are the offset() and length() of this view

array

public abstract byte[] array()

Returns a reference to the backing array for this view. Note that the view might only be of a part of the returned array: this means you should only access the array between offsets ByteArrayView.offset() and offset() + ByteArrayView.length(). NB: no data is copied when doing this

Returns:

the backing array

offset

public abstract int offset()

return the offset into the backing array of this view NB: no data is copied when doing this

Returns:

the offset in bytes

length

public abstract int length()

return the length of this view NB: no data is copied when doing this

Returns:

the length in bytes

copy

public abstract ByteArrayView copy(int offset,
                                   int length)

Create a new ByteArrayView which wraps a new byte[] containing a copy of this view's data NB: this method copies the underlying data

Parameters:

offset - the initial offset of the window (relative to the current window)

length - the length of the window

Returns:

the new ByteArrayView

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > length()

See Also:

if you need a copy of the data in a byte[] indexed from 0 rather than offset()

copy

public abstract ByteArrayView copy()

Create a new ByteArrayView which wraps a new byte[] containing a copy of this view's data NB: this method copies the underlying data

Returns:

the new ByteArrayView

See Also:

if you need a copy of the data in a byte[] indexed from 0 rather than offset()

clone

public ByteArrayView clone()

Implement Object.clone, which just delegates to ByteArrayView.copy().

Specified by:

clone in interface com.streambase.sb.internal.CloneableData

Overrides:

clone in class java.lang.Object

Since:

6.3

copyBytes

public abstract byte[] copyBytes(int offset,
                                 int length)

Create a new byte[] containing a copy of this view's data within the provided window. The returned array may be indexed from 0, unlike ByteArrayView.array(). NB: this method copies the underlying data

Parameters:

offset - the initial offset of the window (relative to the current window)

length - the length of the window

Returns:

the new byte[]

Throws:

java.lang.IllegalArgumentException - if offset or length are negative

java.lang.IndexOutOfBoundsException - if offset+length > length()

copyBytes

public abstract byte[] copyBytes()

Create a new byte[] containing a copy of this view's data. The returned array may be indexed from 0, unlike ByteArrayView.array(). NB: this method copies the underlying data

Returns:

a new byte[] containing a copy of this view's data

compareTo

public int compareTo(ByteArrayView rhs)

compare this ByteArrayView to another lexigraphically NB: no data is copied when doing this

Specified by:

compareTo in interface java.lang.Comparable<ByteArrayView>

Parameters:

rhs - The right hand side of this comparison

Returns:

< 0 if this is less than

equals

public boolean equals(java.lang.Object obj)

check if two ByteArrayViews are byte-for-byte identical NB: this may devolve to a byte by byte comparison

Overrides:

equals in class java.lang.Object

Parameters:

obj - The right hand side of this comparison

Returns:

true if the two views are equal

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

get

public byte get(int pos)

toString

public java.lang.String toString()

Formats a ByteArrayView by printing out every byte as a char. If this ByteArrayView is larger than 16 bytes, only 13 characters will be printed an an ellipsis ("...") will be appended.

Overrides:

toString in class java.lang.Object

asString

public final java.lang.String asString()