org.hd.d.pg2k.svrCore
Class ROByteArray

java.lang.Object
  org.hd.d.pg2k.svrCore.ROByteArray

All Implemented Interfaces:

java.io.Serializable, MemoryTools.Internable

public final class ROByteArray
extends java.lang.Object
implements java.io.Serializable, MemoryTools.Internable

An immutable, Serializable, wrapper for a byte array. This enables byte array data to be safely shared between multiple users, thus avoid copies and duplicates.

We clone at entry and exit and deserialisation to protect our internal data.

This also has helper methods for storing/extracting (with zlib) lossless-compressed String values. (The internal form is deflated UTF-8 without headers or checksum.)

These instances are suitable for pooling with MemoryTools.intern().

Intended to be efficient on the wire and in memory.

See Also:

Serialized Form

payload

private final byte[] payload

The (non-null) payload reference.

HEX_DIGITS

private static final java.lang.String HEX_DIGITS

The set of characters from which we produce our hex digits.

See Also:

Constant Field Values

EMPTY

public static final ROByteArray EMPTY

Empty array.

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

ROByteArray

public ROByteArray(byte[] data)

Construct with (copy of) non-null data block.

Parameters:

data - non-null array of bytes

toByteArray

public byte[] toByteArray()

Get (a copy of) the entire data block; never null.

getData

public byte[] getData(int start,
                      int afterEnd)

Get (a copy of) a portion of the data block.

length

public int length()

Get length of the data; non-negative.

get

public byte get(int index)

Get value at specified index.

hashCode

public int hashCode()

Compute a hash based on the length and some of the payload. This tries to fix the time taken to compute the hash even for large payloads at the cost of possible/probable extra collisions (as per the String experience).

This takes a fixed small number of sample points whose relative positions partly depend on the length, and the length itself is part of the hash.

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Is equal to an instance with a payload of the same length and content; may be slow to compute.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Returns a human-readable representation of this object.

Overrides:

toString in class java.lang.Object

getInputStream

public java.io.InputStream getInputStream()

Get internal data as InputStream (supporting mark()). This gives read-only access to the data as a markable/rewindable stream.

Each call produces a completely independent stream.

toHexString

public java.lang.String toHexString()

Returns a fixed-length unsigned lower-case hex representation of the data. This returns exactly two (lower-case) hex digits for each byte of data, with the high nybble before the low nybble, and lower-index bytes before higher-index bytes.

For example, a data array containing { 13, 241 } would produce "0df1".

fromHexString

public static ROByteArray fromHexString(java.lang.String s)

Creates instance from a hex representation as generated by toHexString(). Input must be non-null, even number of lower-case hex characters.

Throws:

java.lang.IllegalArgumentException - for invalid input

compressFromString

public static final ROByteArray compressFromString(java.lang.String in)

Create an instance from the compressed UTF-8 form of the argumentString. Unlikely to work well on short Strings.

The compression is zlib deflate without any checksums or other avoidable redundant data, so error checking had better be done elsewhere.

The String value can be recovered with the uncompressToString() method.

Parameters:

in - non-null String

uncompressToString

public static final java.lang.String uncompressToString(ROByteArray in)
                                                 throws java.io.IOException

Extract a String from an ROByteArray created by compressFromString(); never null. Results are undefined on other inputs.

Parameters:

in - non-null, non-empty value generated by compressFromString()

Throws:

java.io.IOException - when having difficulty decoding the input

readResolve

protected java.lang.Object readResolve()

Deserialise: use constructor for validation, defensive copying, etc. Also resolve all empty instances to a single value as a minor optimisation.