saker.util Documentation TaskDoc JavaDoc Packages
public abstract class ByteArrayRegion implements Externalizable, ByteRegion
ByteRegion implementation backed by a byte array.

This is the de-facto implementation of the interface ByteRegion. Users who wish to create an instance of ByteRegion should use the static factory methods in this class.

Clients who are dealing with ByteRegion instances may check for them if they're an instance of ByteArrayRegion, and use the backing byte array directly to improve reading and writing performance. This instance of checking works through RMI connections.

The array backed by instances of this class is defined by an offset. The actual byte region starts at the mentioned offset index, and clients should only access the region defined by it and the length.

Methods of this class accept the index parameter relative to the aforementioned offset, i.e. index 0 is the same as accessing the byte at the starting offset.

This class can't be subclassed by clients, and they should use the static factory methods to retrieve an instance.

Fields
public static final ByteArrayRegion
Singleton instance for an empty ByteArrayRegion.
Methods
public static ByteArrayRegion
allocate(int length)
Allocates a new byte array with the given length and returns it as a ByteArrayRegion.
public abstract byte[]
Gets an array that contains the full range of this region.
public abstract byte[]
Gets the underlying array for this instance.
public abstract int
Gets the offset of the range for this instance.
public boolean
Checks if this region contains any bytes.
public void
put(int index, byte[] bytes)
Puts an array of bytes into this region starting at the given index.
public abstract void
put(int index, byte[] bytes, int offset, int len)
Puts an array range of bytes into this region starting at the given index.
public boolean
Checks if the byte contents defined by this region equals to the contents of the argument region.
public String
Returns a string representation of the object.
public String
toString(Charset charset)
Returns a string representation of this byte region by decoding its contents using the given charset.
public static ByteArrayRegion
wrap(byte[] array)
Gets a byte array region that wraps the argument array.
public static ByteArrayRegion
wrap(byte[] array, int offset, int len)
Gets a byte array region that wraps the argument range of the specified array.
public abstract long
Writes the contents of this byte array region to the argument data output.
public abstract long
Writes the contents of this byte array region to the argument output stream.
public static final ByteArrayRegion EMPTY
Singleton instance for an empty ByteArrayRegion.
public static ByteArrayRegion allocate(int length) throws NegativeArraySizeException
Allocates a new byte array with the given length and returns it as a ByteArrayRegion.

This is the same as calling:

 ByteArrayRegion.wrap(new byte[length]);
 
Callers shouldn't rely on the identity of the returned byte array. This method may optimize the allocation for a 0 length byte array, and return a shared object.
lengthThe length of the allocated byte array.
The byte array region allocated for the given length.
NegativeArraySizeExceptionIf the argument is negative.
public abstract byte[] copyOptionally()
Gets an array that contains the full range of this region.

This method is similar to ByteRegion.copy(), but if the range is defined to contain the whole underlying array, then no copies are made.

The modifications made to the returned array may or may not modify the actually represented byte region.

The returned array will have a length of ByteRegion.getLength().

The array containing the contents of this byte region.
public abstract byte[] getArray()
Gets the underlying array for this instance.

The array should only be accessed in the range defined for this instance.

The underlying array.
public abstract int getOffset()
Gets the offset of the range for this instance.
The starting offset of the represented region.
public boolean isEmpty()
Checks if this region contains any bytes.
true if the region is empty.
public void put(int index, byte[] bytes) throws IndexOutOfBoundsException, NullPointerException
Puts an array of bytes into this region starting at the given index.

The index is 0 based, where the index 0 means that the first byte will be written at the offset in the underlying array.

The full contents of the argument array will be copied into the underlying array for this byte array region.

This method is the same as calling:

 put(index, bytes, 0, bytes.length);
 
indexThe index where to start writing the bytes.
bytesThe bytes to write to this region.
IndexOutOfBoundsExceptionIf the index or any of the written bytes would be out of range.
NullPointerExceptionIf the array is null.
public abstract void put(int index, byte[] bytes, int offset, int len) throws IndexOutOfBoundsException, NullPointerException
Puts an array range of bytes into this region starting at the given index.

The index is 0 based, where the index 0 means that the first byte will be written at the offset in the underlying array.

The contents of the argument array in the given range will be copied into the underlying array for this byte array region.

indexThe index where to start writing the bytes.
bytesThe array of bytes to write.
offsetThe starting offset in the argument array to start the copying from.
lenThe number of bytes to copy from the argument array.
IndexOutOfBoundsExceptionIf the index or the specified range or any of the written bytes would be out of range.
NullPointerExceptionIf the array is null.
public boolean regionEquals(ByteArrayRegion region)
Checks if the byte contents defined by this region equals to the contents of the argument region.
regionThe region to compare.
true if the bytes are the same in the byte regions defined by this and the argument.
public String toString()
Returns a string representation of the object.In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 
The contents of this byte array region decoded using UTF-8.
Returns a string representation of this byte region by decoding its contents using the given charset.
charsetThe charset to use to decode the bytes.
The decoded string representation of the byte region.
NullPointerExceptionIf the charset is null.
public static ByteArrayRegion wrap(byte[] array) throws NullPointerException
Gets a byte array region that wraps the argument array.

The returned region will contain the whole array argument.

If the array is empty, the method will return EMPTY, and not a new instance.

arrayThe array.
A byte array region wrapping the array.
NullPointerExceptionIf the array is null.
public static ByteArrayRegion wrap(byte[] array, int offset, int len) throws IndexOutOfBoundsException, NullPointerException
Gets a byte array region that wraps the argument range of the specified array.

If the array is empty, the method will return EMPTY, and not a new instance.

arrayThe array.
offsetThe offset where the region starts.
lenThe length of the region.
A byte array region wrapping the array for the given range.
IndexOutOfBoundsExceptionIf the specified range is not in the bounds of the array.
NullPointerExceptionIf the array is null.
public abstract long writeTo(DataOutput out) throws IOException
Writes the contents of this byte array region to the argument data output.
outThe data output to write the contents of this region.
The number of bytes written to the data output. This is the same as ByteRegion.getLength().
IOExceptionIn case of I/O error.
public abstract long writeTo(OutputStream os) throws IOException
Writes the contents of this byte array region to the argument output stream.
osThe output stream to write the contents of this region.
The number of bytes written to the output stream. This is the same as ByteRegion.getLength().
IOExceptionIn case of I/O error.