Class ArrayByteSource

  • All Implemented Interfaces:
    Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class ArrayByteSource
    extends BeanByteSource
    implements org.joda.beans.ImmutableBean, Serializable
    A byte source implementation that explicitly wraps a byte array.

    This implementation allows IOException to be avoided in many cases, and to be able to create and retrieve the internal array unsafely.

    See Also:
    Serialized Form
    • Method Detail

      • copyOf

        public static ArrayByteSource copyOf​(byte[] array)
        Obtains an instance, copying the array.
        Parameters:
        array - the array, copied
        Returns:
        the byte source
      • copyOf

        public static ArrayByteSource copyOf​(byte[] array,
                                             int fromIndex)
        Obtains an instance by copying part of an array.

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy
        fromIndex - the offset from the start of the array
        Returns:
        an array containing the specified values
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • copyOf

        public static ArrayByteSource copyOf​(byte[] array,
                                             int fromIndexInclusive,
                                             int toIndexExclusive)
        Obtains an instance by copying part of an array.

        The input array is copied and not mutated.

        Parameters:
        array - the array to copy
        fromIndexInclusive - the start index of the input array to copy from
        toIndexExclusive - the end index of the input array to copy to
        Returns:
        an array containing the specified values
        Throws:
        IndexOutOfBoundsException - if the index is invalid
      • ofUnsafe

        public static ArrayByteSource ofUnsafe​(byte[] array)
        Obtains an instance, not copying the array.

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the passed in array after calling this method. Doing so would violate the immutability of this class.

        Parameters:
        array - the array, not copied
        Returns:
        the byte source
      • ofUtf8

        public static ArrayByteSource ofUtf8​(String str)
        Obtains an instance from a string using UTF-8.
        Parameters:
        str - the string to store using UTF-8
        Returns:
        the byte source
      • from

        public static ArrayByteSource from​(ByteSource other)
        Obtains an instance from another byte source.
        Parameters:
        other - the other byte source
        Returns:
        the byte source
        Throws:
        UncheckedIOException - if an IO error occurs
      • from

        public static ArrayByteSource from​(CheckedSupplier<? extends InputStream> inputStreamSupplier)
        Obtains an instance from an input stream.

        This method use the supplier to open the input stream, extract the bytes and close the stream. It is intended that invoking the supplier opens the stream. It is not intended that an already open stream is supplied.

        Parameters:
        inputStreamSupplier - the supplier of the input stream
        Returns:
        the byte source
        Throws:
        UncheckedIOException - if an IO error occurs
      • from

        public static ArrayByteSource from​(InputStream inputStream)
                                    throws IOException
        Obtains an instance from an input stream.

        This method uses an already open input stream, extracting the bytes. The stream is not closed - that is the responsibility of the caller.

        Parameters:
        inputStream - the open input stream, which will not be closed
        Returns:
        the byte source
        Throws:
        IOException - if an IO error occurs
      • from

        public static ArrayByteSource from​(InputStream inputStream,
                                           int expectedSize)
                                    throws IOException
        Obtains an instance from an input stream, specifying the expected size.

        This method uses an already open input stream, extracting the bytes. The stream is not closed - that is the responsibility of the caller.

        Parameters:
        inputStream - the open input stream, which will not be closed
        expectedSize - the expected size of the input, not negative
        Returns:
        the byte source
        Throws:
        IOException - if an IO error occurs
      • fromBase64

        public static ArrayByteSource fromBase64​(String base64)
        Obtains an instance from a base-64 encoded string.
        Parameters:
        base64 - the base64 string to convert
        Returns:
        the decoded byte source
        Throws:
        IllegalArgumentException - if the input is not Base64 encoded
      • fromHex

        public static ArrayByteSource fromHex​(String hex)
        Obtains an instance from a hex encoded string, sometimes referred to as base-16.
        Parameters:
        hex - the hex string to convert
        Returns:
        the decoded byte source
        Throws:
        IllegalArgumentException - if the input is not hex encoded
      • metaBean

        public org.joda.beans.MetaBean metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean
      • getFileName

        public Optional<String> getFileName()
        Description copied from class: BeanByteSource
        Gets the file name of the source.

        Most sources originate from a file-based location. This is captured and returned here where available.

        Overrides:
        getFileName in class BeanByteSource
        Returns:
        the file name, empty if not known
      • withFileName

        public ArrayByteSource withFileName​(String fileName)
        Returns an instance with the file name updated.

        If a path is passed in, only the file name is retained.

        Parameters:
        fileName - the file name, an empty string can be used to remove the file name
        Returns:
        a source with the specified file name
      • readUnsafe

        public byte[] readUnsafe()
        Returns the underlying array.

        This method is inherently unsafe as it relies on good behavior by callers. Callers must never make any changes to the array returned by this method. Doing so would violate the immutability of this class.

        Returns:
        the raw array
      • readUtf8

        public String readUtf8()
        Reads the source, converting to UTF-8.
        Overrides:
        readUtf8 in class BeanByteSource
        Returns:
        the UTF-8 string
      • readUtf8UsingBom

        public String readUtf8UsingBom()
        Reads the source, converting to UTF-8 using a Byte-Order Mark if available.
        Overrides:
        readUtf8UsingBom in class BeanByteSource
        Returns:
        the UTF-8 string
      • toBase64String

        public String toBase64String()
        Encodes the byte source using base-64, returning a string.

        Equivalent to toBase64().readUtf8().

        Overrides:
        toBase64String in class BeanByteSource
        Returns:
        the base-64 encoded string
      • encode

        public ArrayByteSource encode​(ByteSourceCodec codec)
        Encodes the byte source.
        Parameters:
        codec - the codec to use
        Returns:
        the encoded form
      • decode

        public ArrayByteSource decode​(ByteSourceCodec codec)
        Decodes the byte source.
        Parameters:
        codec - the codec to use
        Returns:
        the decoded form
      • toHexString

        public String toHexString()
        Encodes the byte source using hex, sometimes referred to as base-16, returning a string.
        Returns:
        the hex encoded string
      • sizeIfKnown

        public Optional<Long> sizeIfKnown()
        Gets the size, which is always known.
        Overrides:
        sizeIfKnown in class ByteSource
        Returns:
        the size, which is always known
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object