Class Bits


  • public final class Bits
    extends java.lang.Object
    Class (similar to (and partly copied from) java.nio.Bits) containing helper methods to encode variables (e.g. ints, long, List<Address> etc) to memory (byte buffer) or output streams and read variables from memory or input streams.

    The write methods write a type (e.g. an int or a char) to a buffer (ByteBuffer or output stream, using variable-length encoding. If there are not enough byte in the buffer to write a type, a BufferOverflowException is thrown. If the variable cannot be written to the output stream, an IOException is thrown.

    The read methods read a variable-length encoded type from a buffer or input stream. If there are fewer bytes in the buffer than needed to read the type, a BufferUnderflowException is thrown. If the read fails, an IOException is thrown.

    The size() methods return the number of bytes used to encode the given type with variable-length encoding.

    There are additional helper methods to write/read custom JGroups types, e.g. address lists, Views etc

    Note that methods to read/write atomic types (char, int etc) should only be used if variable-length encoding is desired; otherwise DataOutput.writeInt(int) or ByteBuffer.putInt(int) should be used instead.

    At the time of writing this (Feb 2014), most methods have not yet been implemented.

    Since:
    3.5
    Author:
    Bela Ban, Sanne Grinovero
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      protected static byte bytesRequiredFor​(int number)  
      protected static byte bytesRequiredFor​(long number)  
      protected static byte encodeLength​(byte len1, byte len2)
      Encodes the number of bytes needed into a single byte.
      protected static byte firstNibble​(byte len)  
      protected static byte getByteAt​(long num, int index)  
      static char makeChar​(byte[] buf, int offset)  
      static int makeInt​(byte[] buf, int offset, int bytes_to_read)  
      static int makeInt​(java.io.DataInput in, int bytes_to_read)  
      static int makeInt​(java.nio.ByteBuffer buffer, int bytes_to_read)  
      static long makeLong​(byte[] buf, int offset, int bytes_to_read)  
      static long makeLong​(java.io.DataInput in, int bytes_to_read)  
      static long makeLong​(java.nio.ByteBuffer buffer, int bytes_to_read)  
      static short makeShort​(byte a)  
      static short makeShort​(byte a, byte b)  
      static AsciiString readAsciiString​(java.io.DataInput in)
      Reads an AsciiString from buf.
      static AsciiString readAsciiString​(java.nio.ByteBuffer buf)
      Reads an AsciiString from buf.
      static char readChar​(byte[] buf, int offset)  
      static double readDouble​(byte[] buf, int offset)  
      static double readDouble​(java.io.DataInput in)
      Reads a double from an input stream
      static double readDouble​(java.nio.ByteBuffer buf)
      Reads a double from a buffer.
      static float readFloat​(byte[] buf, int offset)  
      static float readFloat​(java.io.DataInput in)
      Reads a a float from an input stream.
      static float readFloat​(java.nio.ByteBuffer buf)
      Reads a a float from a buffer.
      static int readInt​(byte[] buf, int offset)  
      static int readInt​(java.io.DataInput in)
      Reads an int from an input stream
      static int readInt​(java.nio.ByteBuffer buf)
      Reads an int from a buffer.
      static int readIntCompressed​(byte[] buf, int offset)  
      static long readLong​(byte[] buf, int offset)  
      static long readLong​(java.io.DataInput in)
      Reads a variable-length encoded long from an input stream.
      static long readLong​(java.nio.ByteBuffer buf)
      Reads a long from a buffer.
      static long readLongCompressed​(byte[] buf, int offset)  
      static void readLongSequence​(java.io.DataInput in, long[] seqnos, int index)
      Reads 2 compressed longs into an array of 2 longs.
      static void readLongSequence​(java.nio.ByteBuffer buf, long[] seqnos)
      Reads 2 compressed longs from buf into seqnos
      static short readShort​(byte[] buf, int offset)  
      static java.lang.String readString​(java.io.DataInput in)
      Reads a string from buf.
      static java.lang.String readString​(java.nio.ByteBuffer buf)
      Reads a string from buf.
      protected static byte secondNibble​(byte len)  
      static int size​(double num)
      Computes the size of a variable-length encoded double
      static int size​(float num)
      Computes the size of a variable-length encoded float
      static int size​(int num)
      Computes the size of a variable-length encoded int
      static int size​(long num)
      Computes the size of a variable-length encoded long.
      static byte size​(long hd, long hr)  
      static int size​(java.lang.String str)  
      static int size​(AsciiString str)
      Measures the number of bytes required to encode an AsciiSring.
      static int sizeUTF​(java.lang.String str)
      Measures the number of bytes required to encode a string, taking multibyte characters into account.
      static void writeAsciiString​(AsciiString s, java.io.DataOutput out)
      Writes an AsciiString to buf.
      static void writeAsciiString​(AsciiString s, java.nio.ByteBuffer buf)
      Writes an AsciiString to buf.
      static void writeChar​(char c, byte[] buf, int offset)  
      static void writeDouble​(double num, byte[] buf, int offset)  
      static void writeDouble​(double num, java.io.DataOutput out)
      Writes a double to an output stream
      static void writeDouble​(double num, java.nio.ByteBuffer buf)
      Writes a double to a ByteBuffer
      static void writeFloat​(float num, byte[] buf, int offset)  
      static void writeFloat​(float num, java.io.DataOutput out)
      Writes a float to an output stream
      static void writeFloat​(float num, java.nio.ByteBuffer buf)
      Writes a float to a ByteBuffer
      static void writeInt​(int num, byte[] buf, int offset)  
      static void writeInt​(int num, java.io.DataOutput out)
      Writes an int to an output stream
      static void writeInt​(int num, java.nio.ByteBuffer buf)
      Writes an int to a ByteBuffer
      static void writeIntCompressed​(int num, byte[] buf, int offset)  
      static void writeLong​(long num, byte[] buf, int offset)  
      static void writeLong​(long num, java.io.DataOutput out)
      Writes a long to out in variable-length encoding.
      static void writeLong​(long num, java.nio.ByteBuffer buf)
      Writes a long to a ByteBuffer
      static void writeLongCompressed​(long num, byte[] buf, int offset)  
      static void writeLongSequence​(long hd, long hr, java.io.DataOutput out)
      Writes 2 sequence numbers (seqnos) in compressed format to an output stream.
      static void writeLongSequence​(long hd, long hr, java.nio.ByteBuffer buf)
      Writes 2 sequence numbers (seqnos) in compressed format to buf.
      static void writeShort​(short s, byte[] buf, int offset)  
      static void writeString​(java.lang.String s, java.io.DataOutput out)
      Writes a string to buf.
      static void writeString​(java.lang.String s, java.nio.ByteBuffer buf)
      Writes a string to buf.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • makeChar

        public static char makeChar​(byte[] buf,
                                    int offset)
      • writeChar

        public static void writeChar​(char c,
                                     byte[] buf,
                                     int offset)
      • readChar

        public static char readChar​(byte[] buf,
                                    int offset)
      • makeShort

        public static short makeShort​(byte a,
                                      byte b)
      • makeShort

        public static short makeShort​(byte a)
      • writeShort

        public static void writeShort​(short s,
                                      byte[] buf,
                                      int offset)
      • readShort

        public static short readShort​(byte[] buf,
                                      int offset)
      • writeInt

        public static void writeInt​(int num,
                                    java.nio.ByteBuffer buf)
        Writes an int to a ByteBuffer
        Parameters:
        num - the int to be written
        buf - the buffer
      • writeInt

        public static void writeInt​(int num,
                                    java.io.DataOutput out)
                             throws java.io.IOException
        Writes an int to an output stream
        Parameters:
        num - the int to be written
        out - the output stream
        Throws:
        java.io.IOException
      • writeInt

        public static void writeInt​(int num,
                                    byte[] buf,
                                    int offset)
      • writeIntCompressed

        public static void writeIntCompressed​(int num,
                                              byte[] buf,
                                              int offset)
      • readInt

        public static int readInt​(java.nio.ByteBuffer buf)
        Reads an int from a buffer.
        Parameters:
        buf - the buffer
        Returns:
        the int read from the buffer
      • readInt

        public static int readInt​(java.io.DataInput in)
                           throws java.io.IOException
        Reads an int from an input stream
        Parameters:
        in - the input stream
        Returns:
        the int read from the input stream
        Throws:
        java.io.IOException
      • readInt

        public static int readInt​(byte[] buf,
                                  int offset)
      • readIntCompressed

        public static int readIntCompressed​(byte[] buf,
                                            int offset)
      • size

        public static int size​(int num)
        Computes the size of a variable-length encoded int
        Parameters:
        num - the int
        Returns:
        the number of bytes needed to variable-length encode num
      • writeLong

        public static void writeLong​(long num,
                                     java.nio.ByteBuffer buf)
        Writes a long to a ByteBuffer
        Parameters:
        num - the long to be written
        buf - the buffer
      • writeLong

        public static void writeLong​(long num,
                                     java.io.DataOutput out)
                              throws java.io.IOException
        Writes a long to out in variable-length encoding. Note that currently variable-length encoding is not used (a similar mechanism is used); this will be implemented later.
        Parameters:
        num - the long
        out - the output stream to write num to
        Throws:
        java.io.IOException
      • writeLong

        public static void writeLong​(long num,
                                     byte[] buf,
                                     int offset)
      • writeLongCompressed

        public static void writeLongCompressed​(long num,
                                               byte[] buf,
                                               int offset)
      • readLong

        public static long readLong​(java.nio.ByteBuffer buf)
        Reads a long from a buffer.
        Parameters:
        buf - the buffer
        Returns:
        the long read from the buffer
      • readLong

        public static long readLong​(java.io.DataInput in)
                             throws java.io.IOException
        Reads a variable-length encoded long from an input stream. Note that currently variable-length encoding is not used (a similar mechanism is used); this will be implemented later.
        Parameters:
        in - the input stream
        Returns:
        the long read from the input stream
        Throws:
        java.io.IOException
      • readLong

        public static long readLong​(byte[] buf,
                                    int offset)
      • readLongCompressed

        public static long readLongCompressed​(byte[] buf,
                                              int offset)
      • size

        public static int size​(long num)
        Computes the size of a variable-length encoded long. Note that this is not currently using variable-length encoding (will be implemented later).
        Parameters:
        num - the long
        Returns:
        the number of bytes needed to variable-length encode num
      • writeLongSequence

        public static void writeLongSequence​(long hd,
                                             long hr,
                                             java.nio.ByteBuffer buf)
        Writes 2 sequence numbers (seqnos) in compressed format to buf. The seqnos are non-negative and hr is guaranteed to be >= hd.

        Once variable-length encoding has been implemented, this method will probably get dropped as we can simply write the 2 longs individually.

        Parameters:
        hd - the highest delivered seqno. Guaranteed to be a positive number
        hr - the highest received seqno. Guaranteed to be a positive number. Greater than or equal to hd
        buf - the buffer to write to
      • writeLongSequence

        public static void writeLongSequence​(long hd,
                                             long hr,
                                             java.io.DataOutput out)
                                      throws java.io.IOException
        Writes 2 sequence numbers (seqnos) in compressed format to an output stream. The seqnos are non-negative and hr is guaranteed to be >= hd.

        Once variable-length encoding has been implemented, this method will probably get dropped as we can simply write the 2 longs individually.

        Parameters:
        hd - the highest delivered seqno. Guaranteed to be a positive number
        hr - the highest received seqno. Guaranteed to be a positive number. Greater than or equal to hd
        out - the output stream to write to
        Throws:
        java.io.IOException
      • readLongSequence

        public static void readLongSequence​(java.nio.ByteBuffer buf,
                                            long[] seqnos)
        Reads 2 compressed longs from buf into seqnos

        Once variable-length encoding has been implemented, this method will probably get dropped as we can simply read the 2 longs individually.

        Parameters:
        buf - the buffer to read from
        seqnos - the array to read the seqnos into, needs to have a length of 2
      • readLongSequence

        public static void readLongSequence​(java.io.DataInput in,
                                            long[] seqnos,
                                            int index)
                                     throws java.io.IOException
        Reads 2 compressed longs into an array of 2 longs.

        Once variable-length encoding has been implemented, this method will probably get dropped as we can simply read the 2 longs individually.

        Parameters:
        in - the input stream to read from
        seqnos - the array to read the seqnos into, needs to have a length of 2
        index - the index of the first element to be written; the seqnos are written to seqnos[index] and seqnos[index+1]
        Throws:
        java.io.IOException
      • size

        public static byte size​(long hd,
                                long hr)
      • makeInt

        public static int makeInt​(byte[] buf,
                                  int offset,
                                  int bytes_to_read)
      • makeInt

        public static int makeInt​(java.nio.ByteBuffer buffer,
                                  int bytes_to_read)
      • makeInt

        public static int makeInt​(java.io.DataInput in,
                                  int bytes_to_read)
                           throws java.io.IOException
        Throws:
        java.io.IOException
      • makeLong

        public static long makeLong​(byte[] buf,
                                    int offset,
                                    int bytes_to_read)
      • makeLong

        public static long makeLong​(java.nio.ByteBuffer buffer,
                                    int bytes_to_read)
      • makeLong

        public static long makeLong​(java.io.DataInput in,
                                    int bytes_to_read)
                             throws java.io.IOException
        Throws:
        java.io.IOException
      • writeFloat

        public static void writeFloat​(float num,
                                      java.nio.ByteBuffer buf)
        Writes a float to a ByteBuffer
        Parameters:
        num - the float to be written
        buf - the buffer
      • writeFloat

        public static void writeFloat​(float num,
                                      java.io.DataOutput out)
                               throws java.io.IOException
        Writes a float to an output stream
        Parameters:
        num - the float to be written
        out - the output stream
        Throws:
        java.io.IOException
      • writeFloat

        public static void writeFloat​(float num,
                                      byte[] buf,
                                      int offset)
      • readFloat

        public static float readFloat​(java.nio.ByteBuffer buf)
        Reads a a float from a buffer.
        Parameters:
        buf - the buffer
        Returns:
        the float read from the buffer
      • readFloat

        public static float readFloat​(java.io.DataInput in)
                               throws java.io.IOException
        Reads a a float from an input stream.
        Parameters:
        in - the input stream
        Returns:
        the float read from the input stream
        Throws:
        java.io.IOException
      • readFloat

        public static float readFloat​(byte[] buf,
                                      int offset)
      • size

        public static int size​(float num)
        Computes the size of a variable-length encoded float
        Parameters:
        num - the float
        Returns:
        the number of bytes needed to variable-length encode num
      • writeDouble

        public static void writeDouble​(double num,
                                       java.nio.ByteBuffer buf)
        Writes a double to a ByteBuffer
        Parameters:
        num - the double to be written
        buf - the buffer
      • writeDouble

        public static void writeDouble​(double num,
                                       java.io.DataOutput out)
                                throws java.io.IOException
        Writes a double to an output stream
        Parameters:
        num - the double to be written
        out - the output stream
        Throws:
        java.io.IOException
      • writeDouble

        public static void writeDouble​(double num,
                                       byte[] buf,
                                       int offset)
      • readDouble

        public static double readDouble​(java.nio.ByteBuffer buf)
        Reads a double from a buffer.
        Parameters:
        buf - the buffer
        Returns:
        the double read from the buffer
      • readDouble

        public static double readDouble​(java.io.DataInput in)
                                 throws java.io.IOException
        Reads a double from an input stream
        Parameters:
        in - the input stream
        Returns:
        the double read from the input stream
        Throws:
        java.io.IOException
      • readDouble

        public static double readDouble​(byte[] buf,
                                        int offset)
      • size

        public static int size​(double num)
        Computes the size of a variable-length encoded double
        Parameters:
        num - the double
        Returns:
        the number of bytes needed to variable-length encode num
      • writeString

        public static void writeString​(java.lang.String s,
                                       java.nio.ByteBuffer buf)
        Writes a string to buf. The length of the string is written first, followed by the chars (as single-byte values). Multi-byte values are truncated: only the lower byte of each multi-byte char is written, similar to DataOutput.writeChars(String).
        Parameters:
        s - the string
        buf - the buffer
      • writeString

        public static void writeString​(java.lang.String s,
                                       java.io.DataOutput out)
                                throws java.io.IOException
        Writes a string to buf. The length of the string is written first, followed by the chars (as single-byte values). Multi-byte values are truncated: only the lower byte of each multi-byte char is written, similar to DataOutput.writeChars(String).
        Parameters:
        s - the string
        out - the output stream
        Throws:
        java.io.IOException
      • readString

        public static java.lang.String readString​(java.nio.ByteBuffer buf)
        Reads a string from buf. The length is read first, followed by the chars. Each char is a single byte
        Parameters:
        buf - the buffer
        Returns:
        the string read from buf
      • readString

        public static java.lang.String readString​(java.io.DataInput in)
                                           throws java.io.IOException
        Reads a string from buf. The length is read first, followed by the chars. Each char is a single byte
        Parameters:
        in - the input stream
        Returns:
        the string read from buf
        Throws:
        java.io.IOException
      • sizeUTF

        public static int sizeUTF​(java.lang.String str)
        Measures the number of bytes required to encode a string, taking multibyte characters into account. Measures strings written by DataOutput.writeUTF(String).
        Parameters:
        str - the string
        Returns:
        the number of bytes required for encoding str
      • size

        public static int size​(java.lang.String str)
      • writeAsciiString

        public static void writeAsciiString​(AsciiString s,
                                            java.nio.ByteBuffer buf)
        Writes an AsciiString to buf. The length of the string is written first, followed by the chars (as single-byte values).
        Parameters:
        s - the string
        buf - the buffer
      • writeAsciiString

        public static void writeAsciiString​(AsciiString s,
                                            java.io.DataOutput out)
                                     throws java.io.IOException
        Writes an AsciiString to buf. The length of the string is written first, followed by the chars (as single-byte values).
        Parameters:
        s - the string
        out - the output stream
        Throws:
        java.io.IOException
      • readAsciiString

        public static AsciiString readAsciiString​(java.nio.ByteBuffer buf)
        Reads an AsciiString from buf. The length is read first, followed by the chars. Each char is a single byte
        Parameters:
        buf - the buffer
        Returns:
        the string read from buf
      • readAsciiString

        public static AsciiString readAsciiString​(java.io.DataInput in)
                                           throws java.io.IOException
        Reads an AsciiString from buf. The length is read first, followed by the chars. Each char is a single byte
        Parameters:
        in - the input stream
        Returns:
        the string read from buf
        Throws:
        java.io.IOException
      • size

        public static int size​(AsciiString str)
        Measures the number of bytes required to encode an AsciiSring.
        Parameters:
        str - the string
        Returns:
        the number of bytes required for encoding str
      • encodeLength

        protected static byte encodeLength​(byte len1,
                                           byte len2)
        Encodes the number of bytes needed into a single byte. The first number is encoded in the first nibble (the first 4 bits), the second number in the second nibble
        Parameters:
        len1 - The number of bytes needed to store a long. Must be between 0 and 8
        len2 - The number of bytes needed to store a long. Must be between 0 and 8
        Returns:
        The byte storing the 2 numbers len1 and len2
      • firstNibble

        protected static byte firstNibble​(byte len)
      • secondNibble

        protected static byte secondNibble​(byte len)
      • bytesRequiredFor

        protected static byte bytesRequiredFor​(long number)
      • bytesRequiredFor

        protected static byte bytesRequiredFor​(int number)
      • getByteAt

        protected static byte getByteAt​(long num,
                                        int index)