Package 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, ByteSequence, HashEncoded, Externalizable, Serializable, Cloneable, Comparable
public final class Binary extends AbstractByteArrayReadBuffer implements Comparable, Externalizable, ExternalizableLite
A thread-safe immutable binary object.
Author:
cp 2002.01.25
See Also:

  • Field Details

    • EMPTY

      public static final Binary EMPTY
      An empty Binary.

    • TRUE

      public static final Binary TRUE
      A Binary representation of Boolean.TRUE value.

    • FALSE

      public static final Binary FALSE
      A Binary representation of Boolean.FALSE value.

  • Constructor Details

    • 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:

    • 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 Details

    • 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:

    • 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:

    • 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:

    • 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:

    • indexOf

      public int indexOf(byte b)
      Returns the offset within this Binary object of the first occurrence of the specified byte.

      This method is identical in its functionality to the corresponding method in String.

      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:

    • 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.

      This method is identical in its functionality to the corresponding method in String.

      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:

    • indexOf

      public int indexOf(Binary bin)
      Returns the offset within this Binary object of the first occurrence of the specified Binary.

      This method is identical in its functionality to the corresponding method in String.

      Parameters:
      bin - the Binary to search for
      Returns:
      the offset of the first occurrence of the byte sequence represented by the specified Binary in the byte sequence represented by this Binary object, or -1 if the byte sequence does not occur
      Since:
      3.5
      See Also:

    • indexOf

      public int indexOf(Binary bin, int ofFrom)
      Returns the offset within this Binary object of the first occurrence of the specified Binary, starting the search at the specified offset.

      This method is identical in its functionality to the corresponding method in String. Note that one side-effect of maintaining compatibility with the String behavior is that zero-length Strings can be found even when the from-index is out-of-bounds. Given any Binary value "value" and a zero-length binary value "empty", the following will always hold true: 

       int rnd = new Random().nextInt(Integer.MAX_VALUE - value.length());
 assert value.indexOf(empty, value.length() + rnd) == value.length();
      Parameters:
      bin - the Binary to search for
      ofFrom - the offset to search from
      Returns:
      the offset of the first occurrence of the byte sequence represented by the specified Binary in the byte sequence represented by this Binary object that is greater than or equal to ofFrom, or -1 if the byte sequence does not occur from that offset to the end of this Binary
      Since:
      3.5
      See Also:

    • 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.

      This method is identical in its functionality to the corresponding method in String.

      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:

    • 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.

      This method is identical in its functionality to the corresponding method in String.

      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:

    • lastIndexOf

      public int lastIndexOf(Binary bin)
      Returns the offset within this Binary object of the last occurrence of the specified Binary.

      This method is identical in its functionality to the corresponding method in String.

      Parameters:
      bin - the Binary to search for
      Returns:
      the offset of the last occurrence of the byte sequence represented by the specified Binary in the byte sequence represented by this Binary object, or -1 if the byte sequence does not occur
      Since:
      3.5
      See Also:

    • lastIndexOf

      public int lastIndexOf(Binary bin, int ofFrom)
      Returns the offset within this Binary object of the last occurrence of the specified Binary, starting the search at the specified offset.

      This method is identical in its functionality to the corresponding method in String.

      Parameters:
      bin - the Binary to search for
      ofFrom - the offset to search from
      Returns:
      the offset of the last occurrence of the byte sequence represented by the specified Binary in the byte sequence represented by this Binary object that is less than or equal to ofFrom, or -1 if the byte sequence does not occur from that offset to the beginning of this Binary
      Since:
      3.5
      See Also:

    • replace

      public Binary replace(byte bOld, byte bNew)
      Replace all occurrences of one specified byte with another in this Binary object. (This method does not alter the state of this Binary; if replacement must occur, it is accomplished by creating a new Binary instance.)
      Parameters:
      bOld - the byte value to replace
      bNew - the byte value to replace bOld with
      Returns:
      a Binary whose value is the same as this Binary's value, except that all occurrences of bOld will have been replaced with bNew

    • replace

      public Binary replace(Binary binOld, Binary binNew)
      Replace all occurrences of one specified Binary with another in this Binary object. (This method does not alter the state of this Binary; if replacement must occur, it is accomplished by creating a new Binary instance.)
      Parameters:
      binOld - the Binary value to replace
      binNew - the Binary value to replace binOld with
      Returns:
      a Binary whose value is the same as this Binary's value, except that all occurrences of binOld will have been replaced with binNew

    • replaceRegion

      public Binary replaceRegion(int of, int cb, Binary binNew)
      Replace a region within this Binary with another Binary.

      This method does not alter the state of this Binary; it creates a new Binary instance instead.

      Parameters:
      of - the offset of the range to replace within this Binary
      cb - the length of the range to replace in bytes
      binNew - the Binary value to replace the range with
      Returns:
      a Binary whose value is the same as this Binary's value, except that the specified range will have been replaced with binNew
      Since:
      3.5

    • concat

      public Binary concat(Binary bin)
      Concatenate the passed Binary onto this Binary.
      Parameters:
      bin - the Binary to concatenate to this Binary
      Returns:
      a Binary containing the byte sequence of this Binary object followed immediately by the byte sequence of the passed Binary object
      Since:
      3.5

    • reverse

      public Binary reverse()
      Reverse this Binary object's byte sequence such that the byte at offset zero of this sequence occurs at offset length()-1 in the resulting sequence, the byte at offset one of this sequence occurs at offset length()-2 in the resulting sequence, and so on. The resulting Binary object will have the same length as this Binary object.
      Returns:
      a Binary whose byte sequence contains the same byte values as this Binary, but in reverse sequence
      Since:
      3.5

    • split

      public Binary[] split(int nSize)
      Split a Binary into an array of Binaries each of which does not exceed the specified size.
      Parameters:
      nSize - the size of result Binaries
      Returns:
      an array of Binaries
      Since:
      12.2.1.4

    • toBinary

      public Binary toBinary()
      Return 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 ByteSequence
      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)
      Return a Binary object that holds the specified portion of this ReadBuffer.

      This method is an 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.
      Overrides:
      toString in class 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.

      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object
      See Also:

    • equals

      public boolean equals(Object o)
      Compares this Binary object with another object for equality.
      Specified by:
      equals in interface ReadBuffer
      Overrides:
      equals in class AbstractByteArrayReadBuffer
      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

    • calculateNaturalPartition

      public int calculateNaturalPartition(int cPartitions)
      Calculate the partition ID to which the specified Binary should be naturally assigned. This calculation should not be applied to Binary objects decorated with artificially assigned partitions.

      The resulting partition ID will be in the range [0..cPartitions).

      Note: if the specified partition count is zero, this method will return a hash code fo the binary, thus allowing clients that don't have a concept of partitioning or knowledge of the partition count to defer the partition id calculation until the partition count is known.

      Parameters:
      cPartitions - the partition count
      Returns:
      the partition that the this Binary is naturally assigned to or a natural hash code if the partition count is not specified

    • 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

    • 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

    • writeExternal

      public static void writeExternal(DataOutput out, ReadBuffer buf) throws IOException
      Write the contents of the specified ReadBuffer to the specified DataOutput stream in a format that can be restored as a Binary via readExternal(java.io.ObjectInput)
      Parameters:
      out - the DataOutput stream to write to
      buf - the ReadBuffer to write the contents of
      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

    • readBinary

      public static Binary readBinary(FileChannel channel, long of, int cb, byte[] ab2) throws IOException
      Read a Binary of the specified length at the specified offset from the specified FileChannel.
      Parameters:
      channel - the FileChannel to read from
      of - the offset within the FileChannel to read from
      cb - the number of bytes to read from the FileChannel, which will be the length of the Binary
      ab2 - reserved; pass in null
      Returns:
      a Binary containing the specified sequence of bytes from the channel
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(InputStream in) throws IOException
      Read a Binary from the specified InputStream.
      Parameters:
      in - the InputStream to read from
      Returns:
      a Binary containing all the bytes from the specified InputStream
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(InputStream in, int cb) throws IOException
      Read a Binary from the specified InputStream.
      Parameters:
      in - the InputStream to read from
      cb - the exact number of bytes to read from the stream
      Returns:
      a Binary containing cb bytes
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(File file) throws IOException
      Read a Binary from the specified File.
      Parameters:
      file - the File to read from
      Returns:
      a Binary containing all the bytes from the specified file
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(URL url) throws IOException
      Read a Binary from the specified URL.
      Parameters:
      url - the URL to read from
      Returns:
      a Binary containing all the bytes from the specified URL
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(DataInput input) throws IOException
      Read a Binary from the specified DataInput.
      Parameters:
      input - the DataInput to read from
      Returns:
      a Binary containing all the bytes from the specified DataInput
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • readBinary

      public static Binary readBinary(DataInputStream in) throws IOException
      Read a Binary from the specified DataInputStream.
      Parameters:
      in - the DataInputStream to read from
      Returns:
      a Binary containing all the bytes from the specified DataInputStream
      Throws:
      IOException - if an I/O exception or unexpected EOF occurs

    • memchr

      public static int memchr(byte[] abHaystack, int ofHaystack, int cbHaystack, byte bNeedle)
      Find the specified byte (a "needle") in the specified binary region ("the haystack").
      Parameters:
      abHaystack - the byte array containing the binary region to search within (the "haystack")
      ofHaystack - the offset of the binary region within abHaystack
      cbHaystack - the size in bytes of the binary region within abHaystack
      bNeedle - the byte to search for (a "needle")
      Returns:
      the offset within the binary region (the "haystack") at which the specified byte (the "needle") was found, or -1 if the specified byte does not occur within the binary region
      Since:
      3.5

    • memchr

      public static int memchr(byte[] abHaystack, int ofHaystack, int cbHaystack, byte bNeedle, boolean fBackwards)
      Find the specified byte (a "needle") in the specified binary region ("the haystack").
      Parameters:
      abHaystack - the byte array containing the binary region to search within (the "haystack")
      ofHaystack - the offset of the binary region within abHaystack
      cbHaystack - the size in bytes of the binary region within abHaystack
      bNeedle - the byte to search for (a "needle")
      fBackwards - pass false to find the first occurrence, or true to find the last occurrence
      Returns:
      the offset within the binary region (the "haystack") at which the specified byte (the "needle") was found, or -1 if the specified byte does not occur within the binary region
      Since:
      3.5

    • memmem

      public static int memmem(byte[] abHaystack, int ofHaystack, int cbHaystack, byte[] abNeedle, int ofNeedle, int cbNeedle)
      Find the second binary region (a "needle") in the first binary region ("the haystack").
      Parameters:
      abHaystack - the byte array containing the binary region to search within (the "haystack")
      ofHaystack - the offset of the binary region within abHaystack
      cbHaystack - the size in bytes of the binary region within abHaystack
      abNeedle - the byte array containing the binary region to search for (a "needle")
      ofNeedle - the offset of the binary region within abNeedle
      cbNeedle - the size in bytes of the binary region within abNeedle
      Returns:
      the offset within the first binary region (the "haystack") at which the second binary region (the "needle") was found, or -1 if the second binary region does not occur within the first
      Since:
      3.5

    • memmem

      public static int memmem(byte[] abHaystack, int ofHaystack, int cbHaystack, byte[] abNeedle, int ofNeedle, int cbNeedle, boolean fBackwards)
      Find the second binary region (a "needle") in the first binary region ("the haystack").
      Parameters:
      abHaystack - the byte array containing the binary region to search within (the "haystack")
      ofHaystack - the offset of the binary region within abHaystack
      cbHaystack - the size in bytes of the binary region within abHaystack
      abNeedle - the byte array containing the binary region to search for (a "needle")
      ofNeedle - the offset of the binary region within abNeedle
      cbNeedle - the size in bytes of the binary region within abNeedle
      fBackwards - pass false to find the first occurrence, or true to find the last occurrence
      Returns:
      the offset within the first binary region (the "haystack") at which the second binary region (the "needle") was found, or -1 if the second binary region does not occur within the first
      Since:
      3.5

    • memcmp

      public static int memcmp(byte[] ab1, int of1, int cb1, byte[] ab2, int of2, int cb2)
      Compare two binary regions.
      Parameters:
      ab1 - the byte array containing the first binary region to compare
      of1 - the offset of the binary region within ab1
      cb1 - the size in bytes of the binary region within ab1
      ab2 - the byte array containing the second binary region to compare
      of2 - the offset of the binary region within ab2
      cb2 - the size in bytes of the binary region within ab2
      Returns:
      a value less than zero, zero or greater than zero if the first binary region is "less than," "equal to" or "greater than" the second binary region
      Since:
      3.5

    • memcpy

      public static void memcpy(byte[] abSrc, int ofSrc, byte[] abDest, int ofDest, int cbCopy)
      Copy binary data from one binary region to another. This is safe for copying a region from an array to itself, even if the regions are overlapping; as such, it is equivalent to both memmov() and memcpy(). The implementation uses the arraycopy() method of the System class; the only difference between this method and the raw arraycopy() is that this method is typed and decorates any exception with debugging information about the arguments that caused the exception.
      Parameters:
      abSrc - the byte array containing the binary region to copy from
      ofSrc - the offset of the binary region within abSrc
      abDest - the byte array containing the binary region to copy to
      ofDest - the offset of the binary region within abDest
      cbCopy - the size in bytes of the binary region to copy
      Since:
      3.5

    • equals

      public static boolean equals(byte[] ab1, int of1, byte[] ab2, int of2, int cb)
      Compare two binary regions, testing for equality.
      Parameters:
      ab1 - the byte array containing the first binary region to compare
      of1 - the offset of the binary region within ab1
      ab2 - the byte array containing the second binary region to compare
      of2 - the offset of the binary region within ab2
      cb - the size of the binary regions, which is the number of bytes to compare
      Returns:
      true iff the two specified binary regions are identical
      Since:
      3.5

    • clone

      public static byte[] clone(byte[] ab, int of, int cb)
      Create a clone of the specified binary region.
      Parameters:
      ab - the byte array containing the binary region to copy from
      of - the offset of the binary region within ab
      cb - the size in bytes of the binary region to copy
      Returns:
      a copy of the specified binary region
      Since:
      3.5

    • toString

      public static String toString(byte[] ab)
      For debugging purposes, convert the passed byte array into a string that contains the information regarding whether the reference is null, and if it is not null, what the length of the byte array is.
      Parameters:
      ab - a byte array; may be null
      Returns:
      a String; never null
      Since:
      3.5

    • join

      public static Binary join(Binary[] aBinaries)
      Join an array of Binaries into a single Binary.
      Parameters:
      aBinaries - an array of Binaries to join
      Since:
      12.2.1.4