Package io.protostuff

Class ByteString


  • public final class ByteString
    extends java.lang.Object
    Immutable array of bytes.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private ByteString​(byte[] bytes)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.nio.ByteBuffer asReadOnlyByteBuffer()
      Constructs a new read-only java.nio.ByteBuffer with the same backing byte array.
      static byte[] byteArrayDefaultValue​(java.lang.String bytes)
      Helper called by generated code to construct default values for byte array fields.
      byte byteAt​(int index)
      Gets the byte at the given index.
      static ByteString bytesDefaultValue​(java.lang.String bytes)
      Helper called by generated code to construct default values for bytes fields.
      static ByteString copyFrom​(byte[] bytes)
      Copies the given bytes into a ByteString.
      static ByteString copyFrom​(byte[] bytes, int offset, int size)
      Copies the given bytes into a ByteString.
      static ByteString copyFrom​(java.lang.String text, java.lang.String charsetName)
      Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.
      static ByteString copyFromUtf8​(java.lang.String text)
      Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.
      void copyTo​(byte[] target, int offset)
      Copies bytes into a buffer at the given offset.
      void copyTo​(byte[] target, int sourceOffset, int targetOffset, int size)
      Copies bytes into a buffer.
      boolean equals​(byte[] data)
      Returns true if the contents of the internal array and the provided array match.
      boolean equals​(byte[] data, int offset, int len)
      Returns true if the contents of the internal array and the provided array match.
      static boolean equals​(ByteString bs, ByteString other, boolean checkHash)
      Returns true if the contents of both match.
      boolean equals​(java.lang.Object o)  
      (package private) byte[] getBytes()  
      int hashCode()  
      boolean isEmpty()
      Returns true if the size is 0, false otherwise.
      int size()
      Gets the number of bytes.
      static java.lang.String stringDefaultValue​(java.lang.String bytes)
      Helper called by generated code to construct default values for string fields.
      byte[] toByteArray()
      Copies bytes to a byte[].
      java.lang.String toString()  
      java.lang.String toStringUtf8()
      Constructs a new String by decoding the bytes as UTF-8.
      (package private) static ByteString wrap​(byte[] bytes)  
      static void writeTo​(Output output, ByteString bs, int fieldNumber, boolean repeated)
      Writes the bytes to the Output.
      static void writeTo​(java.io.DataOutput out, ByteString bs)
      Writes the bytes to the DataOutput.
      static void writeTo​(java.io.OutputStream out, ByteString bs)
      Writes the bytes to the OutputStream.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • bytes

        private final byte[] bytes
      • EMPTY_STRING

        public static final java.lang.String EMPTY_STRING
        Empty String.
        See Also:
        Constant Field Values
      • EMPTY_BYTE_ARRAY

        public static final byte[] EMPTY_BYTE_ARRAY
        Empty byte array.
      • EMPTY

        public static final ByteString EMPTY
        Empty ByteString.
      • hash

        private volatile int hash
    • Constructor Detail

      • ByteString

        private ByteString​(byte[] bytes)
    • Method Detail

      • getBytes

        byte[] getBytes()
      • writeTo

        public static void writeTo​(java.io.OutputStream out,
                                   ByteString bs)
                            throws java.io.IOException
        Writes the bytes to the OutputStream.
        Throws:
        java.io.IOException
      • writeTo

        public static void writeTo​(java.io.DataOutput out,
                                   ByteString bs)
                            throws java.io.IOException
        Writes the bytes to the DataOutput.
        Throws:
        java.io.IOException
      • writeTo

        public static void writeTo​(Output output,
                                   ByteString bs,
                                   int fieldNumber,
                                   boolean repeated)
                            throws java.io.IOException
        Writes the bytes to the Output.
        Throws:
        java.io.IOException
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • byteAt

        public byte byteAt​(int index)
        Gets the byte at the given index.
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - index is < 0 or >= size
      • size

        public int size()
        Gets the number of bytes.
      • isEmpty

        public boolean isEmpty()
        Returns true if the size is 0, false otherwise.
      • copyFrom

        public static ByteString copyFrom​(byte[] bytes,
                                          int offset,
                                          int size)
        Copies the given bytes into a ByteString.
      • copyFrom

        public static ByteString copyFrom​(byte[] bytes)
        Copies the given bytes into a ByteString.
      • copyFrom

        public static ByteString copyFrom​(java.lang.String text,
                                          java.lang.String charsetName)
        Encodes text into a sequence of bytes using the named charset and returns the result as a ByteString.
      • copyFromUtf8

        public static ByteString copyFromUtf8​(java.lang.String text)
        Encodes text into a sequence of UTF-8 bytes and returns the result as a ByteString.
      • copyTo

        public void copyTo​(byte[] target,
                           int offset)
        Copies bytes into a buffer at the given offset.
        Parameters:
        target - buffer to copy into
        offset - in the target buffer
      • copyTo

        public void copyTo​(byte[] target,
                           int sourceOffset,
                           int targetOffset,
                           int size)
        Copies bytes into a buffer.
        Parameters:
        target - buffer to copy into
        sourceOffset - offset within these bytes
        targetOffset - offset within the target buffer
        size - number of bytes to copy
      • toByteArray

        public byte[] toByteArray()
        Copies bytes to a byte[].
      • asReadOnlyByteBuffer

        public java.nio.ByteBuffer asReadOnlyByteBuffer()
        Constructs a new read-only java.nio.ByteBuffer with the same backing byte array.
      • toStringUtf8

        public java.lang.String toStringUtf8()
        Constructs a new String by decoding the bytes as UTF-8.
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • equals

        public static boolean equals​(ByteString bs,
                                     ByteString other,
                                     boolean checkHash)
        Returns true if the contents of both match.
      • equals

        public boolean equals​(byte[] data)
        Returns true if the contents of the internal array and the provided array match.
      • equals

        public boolean equals​(byte[] data,
                              int offset,
                              int len)
        Returns true if the contents of the internal array and the provided array match.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • stringDefaultValue

        public static java.lang.String stringDefaultValue​(java.lang.String bytes)
        Helper called by generated code to construct default values for string fields.

        The protocol compiler does not actually contain a UTF-8 decoder -- it just pushes UTF-8-encoded text around without touching it. The one place where this presents a problem is when generating Java string literals. Unicode characters in the string literal would normally need to be encoded using a Unicode escape sequence, which would require decoding them. To get around this, protoc instead embeds the UTF-8 bytes into the generated code and leaves it to the runtime library to decode them.

        It gets worse, though. If protoc just generated a byte array, like: new byte[] {0x12, 0x34, 0x56, 0x78} Java actually generates *code* which allocates an array and then fills in each value. This is much less efficient than just embedding the bytes directly into the bytecode. To get around this, we need another work-around. String literals are embedded directly, so protoc actually generates a string literal corresponding to the bytes. The easiest way to do this is to use the ISO-8859-1 character set, which corresponds to the first 256 characters of the Unicode range. Protoc can then use good old CEscape to generate the string.

        So we have a string literal which represents a set of bytes which represents another string. This function -- stringDefaultValue -- converts from the generated string to the string we actually want. The generated code calls this automatically.

      • bytesDefaultValue

        public static ByteString bytesDefaultValue​(java.lang.String bytes)
        Helper called by generated code to construct default values for bytes fields.

        This is a lot like stringDefaultValue(java.lang.String), but for bytes fields. In this case we only need the second of the two hacks -- allowing us to embed raw bytes as a string literal with ISO-8859-1 encoding.

      • byteArrayDefaultValue

        public static byte[] byteArrayDefaultValue​(java.lang.String bytes)
        Helper called by generated code to construct default values for byte array fields.

        This is a lot like stringDefaultValue(java.lang.String), but for bytes fields. In this case we only need the second of the two hacks -- allowing us to embed raw bytes as a string literal with ISO-8859-1 encoding.