CoherenceTM v3.4.1
Copyright© 2000-2008 by Oracle Corporation

com.tangosol.util
Class Binary

java.lang.Object
  extended by com.tangosol.util.Base
      extended by com.tangosol.io.AbstractReadBuffer
          extended by com.tangosol.io.AbstractByteArrayReadBuffer
              extended by com.tangosol.util.Binary
All Implemented Interfaces:
ExternalizableLite, ReadBuffer, java.io.Externalizable, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public final class Binary
extends AbstractByteArrayReadBuffer
implements java.lang.Cloneable, java.lang.Comparable, java.io.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(java.io.ByteArrayOutputStream stream)
          Construct a Binary object from the contents of a ByteArrayOutputStream.
Binary(java.io.DataInput stream)
          Construct a binary object from a DataInput interface.
 
Method Summary
 java.lang.Object clone()
          Create a clone of this Binary object.
 int compareTo(java.lang.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(java.lang.Object o)
          Compares this Binary object with another object for equality.
 java.io.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(java.io.DataInput in)
          Restore the contents of this object by loading the object's state from the passed DataInput object.
 void readExternal(java.io.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().

 java.lang.String toString()
          Provide a human-readable representation of the Binary object.
 void writeExternal(java.io.DataOutput out)
          Save the contents of this object by storing the object's state into the passed DataOutput object.
 void writeExternal(java.io.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(java.nio.ByteBuffer buf)
          Write the contents of the Binary object to a ByteBuffer.
 void writeTo(java.io.DataOutput out)
          Write the contents of the Binary object to a DataOutput.
 void writeTo(java.io.OutputStream out)
          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(java.io.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(java.io.DataInput stream)
       throws java.io.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:
java.io.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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 java.lang.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 java.lang.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(java.lang.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(java.lang.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 java.lang.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:
java.lang.ClassCastException - if the specified object's type prevents it from being compared to this Object
java.lang.NullPointerException - if the specified object is null

readExternal

public void readExternal(java.io.ObjectInput in)
                  throws java.io.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 java.io.Externalizable
Parameters:
in - the stream to read data from in order to restore the object
Throws:
java.io.IOException - if an I/O exception occurs

writeExternal

public void writeExternal(java.io.ObjectOutput out)
                   throws java.io.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 java.io.Externalizable
Parameters:
out - the stream to write the object to
Throws:
java.io.IOException - if an I/O exception occurs

readExternal

public void readExternal(java.io.DataInput in)
                  throws java.io.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:
java.io.IOException - if an I/O exception occurs
java.io.NotActiveException - if the object is not in its initial state, and therefore cannot be deserialized into

writeExternal

public void writeExternal(java.io.DataOutput out)
                   throws java.io.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:
java.io.IOException - if an I/O exception occurs

getInputStream

public java.io.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(java.io.OutputStream out)
             throws java.io.IOException
Write the contents of the Binary object to an OutputStream.

Parameters:
out - an OutputStream to write to
Throws:
java.io.IOException

writeTo

public void writeTo(java.io.DataOutput out)
             throws java.io.IOException
Write the contents of the Binary object to a DataOutput.

Parameters:
out - a DataOutput to write to
Throws:
java.io.IOException

writeTo

public void writeTo(java.nio.ByteBuffer buf)
Write the contents of the Binary object to a ByteBuffer.

Parameters:
buf - a ByteBuffer to write to

CoherenceTM v3.4.1
Copyright© 2000-2008 by Oracle Corporation