com.tangosol.util
Class Binary

java.lang.Object
  com.tangosol.util.Base
      com.tangosol.io.AbstractReadBuffer
          com.tangosol.io.AbstractByteArrayReadBuffer
              com.tangosol.util.Binary

All Implemented Interfaces:

ExternalizableLite, ReadBuffer, Externalizable, Serializable, Cloneable, Comparable

public final class Binary
extends AbstractByteArrayReadBuffer
implements Cloneable, Comparable, Externalizable, ExternalizableLite

A thread-safe immutable binary object.

Author:

cp 2002.01.25

Nested Class Summary

Nested classes/interfaces inherited from class com.tangosol.io.AbstractByteArrayReadBuffer

AbstractByteArrayReadBuffer.ByteArrayBufferInput

Nested classes/interfaces inherited from class com.tangosol.io.AbstractReadBuffer

AbstractReadBuffer.AbstractBufferInput

Nested classes/interfaces inherited from interface com.tangosol.io.ReadBuffer

ReadBuffer.BufferInput

Field Summary

Fields inherited from class com.tangosol.io.AbstractByteArrayReadBuffer

m_ab, m_cb, m_of

Fields inherited from class com.tangosol.io.AbstractReadBuffer

NO_BINARY, NO_BYTES

Constructor Summary

Binary()
Default constructor for a binary object.

Binary(Binary that)
Construct a Binary object from a Binary object.

Binary(byte[] ab)
Construct a binary object from a byte array.

Binary(byte[] ab, int of, int cb)
Construct a binary object from a portion of a byte array.

Binary(ByteArrayOutputStream stream)
Construct a Binary object from the contents of a ByteArrayOutputStream.

Binary(DataInput stream)
Construct a binary object from a DataInput interface.

Method Summary

Object	clone() Create a clone of this Binary object.
int	compareTo(Object o) Compares this object with the specified object for order.
boolean	endsWith(Binary bin) Tests if this Binary object ends with the specified suffix.
boolean	equals(Object o) Compares this Binary object with another object for equality.
InputStream	getInputStream() Get an InputStream to read the Binary object's contents from.
int	hashCode() Returns a hash code value for the object.
int	indexOf(byte b) Returns the offset within this Binary object of the first occurrence of the specified byte.
int	indexOf(byte b, int ofFrom) Returns the offset within this Binary object of the first occurrence of the specified byte, starting the search at the specified offset.
protected ReadBuffer	instantiateReadBuffer(int of, int cb) Factory method: Instantiate a ReadBuffer for a portion of this ReadBuffer.
protected boolean	isByteArrayPrivate() Determine if the underlying byte[] should be treated as private data.
int	lastIndexOf(byte b) Returns the offset within this Binary object of the last occurrence of the specified byte.
int	lastIndexOf(byte b, int ofFrom) Returns the offset within this Binary object of the last occurrence of the specified byte, starting the search at the specified offset and searching backwards.
void	readExternal(DataInput in) Restore the contents of this object by loading the object's state from the passed DataInput object.
void	readExternal(ObjectInput in) The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays.
boolean	regionMatches(int ofThis, Binary that, int ofThat, int cb) Tests if two Binary regions are equal.
boolean	startsWith(Binary bin) Tests if this Binary object starts with the specified prefix.
boolean	startsWith(Binary bin, int ofFrom) Tests if this Binary object starts with the specified prefix beginning a specified offset.
Binary	toBinary() Returns a new Binary object that holds the complete contents of this ReadBuffer. This is the equivalent of toBinary(0, length()).
Binary	toBinary(int of, int cb) Returns a Binary object that holds the specified portion of this ReadBuffer. This is the equivalent of getReadBuffer(of, cb).toBinary().
String	toString() Provide a human-readable representation of the Binary object.
void	writeExternal(DataOutput out) Save the contents of this object by storing the object's state into the passed DataOutput object.
void	writeExternal(ObjectOutput out) The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.
void	writeTo(OutputStream stream) Write the contents of the Binary object to an OutputStream.

Methods inherited from class com.tangosol.io.AbstractByteArrayReadBuffer

byteAt, copyBytes, instantiateBufferInput, length, resetRange, toByteArray

Methods inherited from class com.tangosol.io.AbstractReadBuffer

checkBounds, getBufferInput, getReadBuffer, toByteArray

Constructor Detail

Binary

public Binary()

Default constructor for a binary object. Supports deserialization.

Binary

public Binary(byte[] ab)

Construct a binary object from a byte array.

Parameters:

ab - an array of bytes

Binary

public Binary(byte[] ab,
              int of,
              int cb)

Construct a binary object from a portion of a byte array.

Parameters:

ab - an array of bytes

of - the offset into the byte array

cb - the number of bytes to extract

Binary

public Binary(Binary that)

Construct a Binary object from a Binary object.

Parameters:

that - another Binary object

See Also:

String.String(String)

Binary

public Binary(ByteArrayOutputStream stream)

Construct a Binary object from the contents of a ByteArrayOutputStream.

Parameters:

stream - the ByteArrayOutputStream that holds the value that this Binary object will represent

Binary

public Binary(DataInput stream)
       throws IOException

Construct a binary object from a DataInput interface.

Parameters:

stream - the object implementing DataInput from which this Binary object will load its data

Throws:

IOException - if an I/O error occurs reading the Binary

Method Detail

regionMatches

public boolean regionMatches(int ofThis,
                             Binary that,
                             int ofThat,
                             int cb)

Tests if two Binary regions are equal.

Parameters:

ofThis - the starting offset of the subregion in this Binary object

that - the Binary object containing the subregion to compare to

ofThat - the starting offset of the subregion in the passed Binary object that

cb - the number of bytes to compare

Returns:

true if the specified subregion of this Binary object exactly matches the specified subregion of the that Binary object; false otherwise

Throws:

NullPointerException - if that is null

See Also:

String.regionMatches(int, java.lang.String, int, int)

startsWith

public boolean startsWith(Binary bin,
                          int ofFrom)

Tests if this Binary object starts with the specified prefix beginning a specified offset.

Parameters:

bin - the prefix

ofFrom - the offset to begin looking in this Binary object

Returns:

true if the byte sequence represented by the bin argument is a prefix of the substring of this Binary object starting at offset ofFrom; false otherwise

Throws:

NullPointerException - if bin is null.

See Also:

String.startsWith(java.lang.String, int)

startsWith

public boolean startsWith(Binary bin)

Tests if this Binary object starts with the specified prefix.

Parameters:

bin - the prefix

Returns:

true if the byte sequence represented by the bin argument is a prefix of this Binary object; false otherwise

Throws:

NullPointerException - if bin is null.

See Also:

String.startsWith(java.lang.String, int)

endsWith

public boolean endsWith(Binary bin)

Tests if this Binary object ends with the specified suffix.

Parameters:

bin - the suffix

Returns:

true if the byte sequence represented by the bin argument is a suffix of this Binary object; false otherwise

Throws:

NullPointerException - if bin is null.

See Also:

String.endsWith(java.lang.String)

indexOf

public int indexOf(byte b)

Returns the offset within this Binary object of the first occurrence of the specified byte.

Parameters:

b - the byte to search for

Returns:

the offset of the first occurrence of the specified byte in the byte sequence represented by this Binary object, or -1 if the byte does not occur in the sequence

See Also:

String.indexOf(int)

indexOf

public int indexOf(byte b,
                   int ofFrom)

Returns the offset within this Binary object of the first occurrence of the specified byte, starting the search at the specified offset.

Parameters:

b - the byte to search for

ofFrom - the offset to search from

Returns:

the offset of the first occurrence of the specified byte in the byte sequence represented by this Binary object that is greater than or equal to ofFrom, or -1 if the byte does not occur from that offset to the end of the sequence

See Also:

String.indexOf(int)

lastIndexOf

public int lastIndexOf(byte b)

Returns the offset within this Binary object of the last occurrence of the specified byte. The byte sequence of the Binary object is searched in backwards order.

Parameters:

b - the byte to search for

Returns:

the offset of the last occurrence of the specified byte in the byte sequence represented by this Binary object, or -1 if the byte does not occur in the sequence

See Also:

String.lastIndexOf(int)

lastIndexOf

public int lastIndexOf(byte b,
                       int ofFrom)

Returns the offset within this Binary object of the last occurrence of the specified byte, starting the search at the specified offset and searching backwards.

Parameters:

b - the byte to search for

ofFrom - the offset to search backwards from (inclusive)

Returns:

the offset of the last occurrence of the specified byte in the byte sequence represented by this Binary object that is less than or equal to ofFrom, or -1 if the byte does not occur from that offset to the start of the sequence

See Also:

String.lastIndexOf(int)

toBinary

public Binary toBinary()

Returns a new Binary object that holds the complete contents of this ReadBuffer.

This is the equivalent of toBinary(0, length()).

Specified by:

toBinary in interface ReadBuffer

Overrides:

toBinary in class AbstractByteArrayReadBuffer

Returns:

the contents of this ReadBuffer as a Binary object

toBinary

public Binary toBinary(int of,
                       int cb)

Returns a Binary object that holds the specified portion of this ReadBuffer.

This is the equivalent of getReadBuffer(of, cb).toBinary().

Specified by:

toBinary in interface ReadBuffer

Overrides:

toBinary in class AbstractByteArrayReadBuffer

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the Binary object

Returns:

a Binary object containing the specified portion of this ReadBuffer

instantiateReadBuffer

protected ReadBuffer instantiateReadBuffer(int of,
                                           int cb)

Factory method: Instantiate a ReadBuffer for a portion of this ReadBuffer.

Specified by:

instantiateReadBuffer in class AbstractReadBuffer

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the resulting ReadBuffer

Returns:

a ReadBuffer that represents a portion of this ReadBuffer

isByteArrayPrivate

protected boolean isByteArrayPrivate()

Determine if the underlying byte[] should be treated as private data.

Specified by:

isByteArrayPrivate in class AbstractByteArrayReadBuffer

Returns:

true iff the underlying data should not ever be exposed by this object

clone

public Object clone()

Create a clone of this Binary object.

Specified by:

clone in interface ReadBuffer

Overrides:

clone in class AbstractReadBuffer

Returns:

a Binary object with the same contents as this Binary object

toString

public String toString()

Provide a human-readable representation of the Binary object.

Returns:

a String whose contents represent the value of this Binary object

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashed data structures.

The Binary object uses a CRC32 algorithm to determine the hash code. For more information on this algorithm, see http://www.tangosol.com/article-crc.jsp.

Returns:

a hash code value for this object

equals

public boolean equals(Object o)

Compares this Binary object with another object for equality.

Overrides:

equals in class AbstractReadBuffer

Parameters:

o - an object reference or null

Returns:

true iff the passed object reference is a Binary object representing the same exact sequence of byte values

compareTo

public int compareTo(Object o)

Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Specified by:

compareTo in interface Comparable

Parameters:

o - the Object to be compared.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object

Throws:

ClassCastException - if the specified object's type prevents it from being compared to this Object

NullPointerException - if the specified object is null

readExternal

public void readExternal(ObjectInput in)
                  throws IOException

The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects, strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal.

Specified by:

readExternal in interface Externalizable

Parameters:

in - the stream to read data from in order to restore the object

Throws:

IOException - if an I/O exception occurs

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects, strings, and arrays.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - the stream to write the object to

Throws:

IOException - if an I/O exception occurs

readExternal

public void readExternal(DataInput in)
                  throws IOException

Restore the contents of this object by loading the object's state from the passed DataInput object.

Specified by:

readExternal in interface ExternalizableLite

Parameters:

in - the DataInput stream to read data from in order to restore the state of this object

Throws:

IOException - if an I/O exception occurs

NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(DataOutput out)
                   throws IOException

Save the contents of this object by storing the object's state into the passed DataOutput object.

Specified by:

writeExternal in interface ExternalizableLite

Parameters:

out - the DataOutput stream to write the state of this object to

Throws:

IOException - if an I/O exception occurs

getInputStream

public InputStream getInputStream()

Get an InputStream to read the Binary object's contents from.

Returns:

an InputStream backed by this Binary object

writeTo

public void writeTo(OutputStream stream)
             throws IOException

Write the contents of the Binary object to an OutputStream.

Parameters:

stream - an OutputStream to write to

Throws:

IOException