ByteArrayRegion

package saker.build.thirdparty.saker.util.io

public abstract class ByteArrayRegion implements Externalizable, ByteRegion

saker.build.thirdparty.saker.util.io.ByteArrayRegion

java.lang.Object

java.io.Externalizable

java.io.Serializable

saker.build.thirdparty.saker.util.io.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	EMPTY 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[]	copyOptionally() Gets an array that contains the full range of this region.
public abstract byte[]	getArray() Gets the underlying array for this instance.
public abstract int	getOffset() Gets the offset of the range for this instance.
public boolean	isEmpty() 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	regionEquals(ByteArrayRegion region) Checks if the byte contents defined by this region equals to the contents of the argument region.
public String	toString() 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	writeTo(DataOutput out) Writes the contents of this byte array region to the argument data output.
public abstract long	writeTo(OutputStream os) Writes the contents of this byte array region to the argument output stream.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
From: Externalizable readExternal, writeExternal
From: ByteRegion copy, copyArrayRegion, get, getLength, put, put

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.

getOffset()

ByteRegion.getLength()

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.

public String toString(Charset charset) throws NullPointerException

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.