Package com.tangosol.util

Class Binary

    • Field Detail

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

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

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

        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:
        String.indexOf(int, int)

      • 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:
        String.indexOf(String)

      • 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:
        String.indexOf(String, 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.

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

        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:
        String.lastIndexOf(int, int)

      • 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:
        String.lastIndexOf(String)

      • 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:
        String.lastIndexOf(String, int)

      • 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​(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:
        Base.toCrc(byte[], int, int)

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

      • 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