Package com.esotericsoftware.kryo.io

Class Output

  • All Implemented Interfaces:
    Pool.Poolable, java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable
    Direct Known Subclasses:
    ByteBufferOutput, OutputChunked, UnsafeOutput
    public class Output
extends java.io.OutputStream
implements java.lang.AutoCloseable, Pool.Poolable
    An OutputStream that writes data to a byte[] and optionally flushes to another OutputStream. Utility methods are provided for efficiently writing primitive types and strings using big endian.
    Author:
    Nathan Sweet

    • Constructor Summary

      Constructors 
      Constructor Description
      Output()
      Creates an uninitialized Output, setBuffer(byte[], int) must be called before the Output is used.
      Output​(byte[] buffer)
      Creates a new Output for writing to a byte[].
      Output​(byte[] buffer, int maxBufferSize)
      Creates a new Output for writing to a byte[].
      Output​(int bufferSize)
      Creates a new Output for writing to a byte[].
      Output​(int bufferSize, int maxBufferSize)
      Creates a new Output for writing to a byte[].
      Output​(java.io.OutputStream outputStream)
      Creates a new Output for writing to an OutputStream.
      Output​(java.io.OutputStream outputStream, int bufferSize)
      Creates a new Output for writing to an OutputStream with the specified buffer size.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Flushes any buffered bytes and closes the underlying OutputStream, if any.
      void flush()
      Flushes the buffered bytes.
      byte[] getBuffer()
      Returns the buffer.
      int getMaxCapacity()
      The maximum buffer size, or -1 for no maximum.
      java.io.OutputStream getOutputStream()  
      boolean getVariableLengthEncoding()  
      int intLength​(int value, boolean optimizePositive)
      Returns the number of bytes that would be written with writeInt(int, boolean).
      int longLength​(int value, boolean optimizePositive)
      Returns the number of bytes that would be written with writeLong(long, boolean).
      int position()
      Returns the current position in the buffer.
      protected boolean require​(int required)
      Ensures the buffer is large enough to read the specified number of bytes.
      void reset()
      Sets the position and total to 0.
      void setBuffer​(byte[] buffer)
      Sets a new buffer to write to.
      void setBuffer​(byte[] buffer, int maxBufferSize)
      Sets a new buffer to write to.
      void setOutputStream​(java.io.OutputStream outputStream)
      Sets a new OutputStream to flush data to when the buffer is full.
      void setPosition​(int position)
      Sets the current position in the buffer.
      void setVariableLengthEncoding​(boolean varEncoding)
      If false, writeInt(int, boolean), writeLong(long, boolean), writeInts(int[], int, int, boolean), and writeLongs(long[], int, int, boolean) will use fixed length encoding, which may be faster for some data.
      byte[] toBytes()
      Allocates and returns a new byte[] containing the bytes currently in the buffer between 0 and position().
      long total()
      Returns the total number of bytes written.
      static int varIntLength​(int value, boolean optimizePositive)
      Returns the number of bytes that would be written with writeVarInt(int, boolean).
      static int varLongLength​(long value, boolean optimizePositive)
      Returns the number of bytes that would be written with writeVarLong(long, boolean).
      void write​(byte[] bytes)
      Writes the bytes.
      void write​(byte[] bytes, int offset, int length)
      Writes the bytes.
      void write​(int value)
      Writes a byte.
      void writeAscii​(java.lang.String value)
      Writes a string that is known to contain only ASCII characters.
      void writeBoolean​(boolean value)
      Writes a 1 byte boolean.
      void writeBooleans​(boolean[] array, int offset, int count)
      Writes a boolean array in bulk.
      void writeByte​(byte value)  
      void writeByte​(int value)  
      void writeBytes​(byte[] bytes)
      Writes the bytes.
      void writeBytes​(byte[] bytes, int offset, int count)
      Writes the bytes.
      void writeChar​(char value)
      Writes a 2 byte char.
      void writeChars​(char[] array, int offset, int count)
      Writes a char array in bulk.
      void writeDouble​(double value)
      Writes an 8 byte double.
      void writeDoubles​(double[] array, int offset, int count)
      Writes a double array in bulk.
      void writeFloat​(float value)
      Writes a 4 byte float.
      void writeFloats​(float[] array, int offset, int count)
      Writes a float array in bulk.
      void writeInt​(int value)
      Writes a 4 byte int.
      int writeInt​(int value, boolean optimizePositive)
      Reads an int using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean).
      void writeInts​(int[] array, int offset, int count)
      Writes an int array in bulk.
      void writeInts​(int[] array, int offset, int count, boolean optimizePositive)
      Writes an int array in bulk using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean).
      void writeLong​(long value)
      Writes an 8 byte long.
      int writeLong​(long value, boolean optimizePositive)
      Reads a long using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean).
      void writeLongs​(long[] array, int offset, int count)
      Writes a long array in bulk.
      void writeLongs​(long[] array, int offset, int count, boolean optimizePositive)
      Writes a long array in bulk using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean).
      void writeShort​(int value)
      Writes a 2 byte short.
      void writeShorts​(short[] array, int offset, int count)
      Writes a short array in bulk.
      void writeString​(java.lang.String value)
      Writes the length and string, or null.
      int writeVarDouble​(double value, double precision, boolean optimizePositive)
      Writes a 1-9 byte double with reduced precision.
      int writeVarFloat​(float value, float precision, boolean optimizePositive)
      Writes a 1-5 byte float with reduced precision.
      int writeVarInt​(int value, boolean optimizePositive)
      Writes a 1-5 byte int.
      int writeVarIntFlag​(boolean flag, int value, boolean optimizePositive)
      Writes a 1-5 byte int, encoding the boolean value with a bit flag.
      int writeVarLong​(long value, boolean optimizePositive)
      Writes a 1-9 byte long.

      • Methods inherited from class java.io.OutputStream

        nullOutputStream

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • maxCapacity

        protected int maxCapacity

      • total

        protected long total

      • position

        protected int position

      • capacity

        protected int capacity

      • buffer

        protected byte[] buffer

      • outputStream

        protected java.io.OutputStream outputStream

      • varEncoding

        protected boolean varEncoding

    • Constructor Detail

      • Output

        public Output()
        Creates an uninitialized Output, setBuffer(byte[], int) must be called before the Output is used.

      • Output

        public Output​(int bufferSize)
        Creates a new Output for writing to a byte[].
        Parameters:
        bufferSize - The size of the buffer. An exception is thrown if more bytes than this are written and flush() does not empty the buffer.

      • Output

        public Output​(int bufferSize,
              int maxBufferSize)
        Creates a new Output for writing to a byte[].
        Parameters:
        bufferSize - The initial size of the buffer.
        maxBufferSize - If flush() does not empty the buffer, the buffer is doubled as needed until it exceeds maxBufferSize and an exception is thrown. Can be -1 for no maximum.

      • Output

        public Output​(byte[] buffer)
        Creates a new Output for writing to a byte[].
        See Also:
        setBuffer(byte[])

      • Output

        public Output​(byte[] buffer,
              int maxBufferSize)
        Creates a new Output for writing to a byte[].
        See Also:
        setBuffer(byte[], int)

      • Output

        public Output​(java.io.OutputStream outputStream)
        Creates a new Output for writing to an OutputStream. A buffer size of 4096 is used.

      • Output

        public Output​(java.io.OutputStream outputStream,
              int bufferSize)
        Creates a new Output for writing to an OutputStream with the specified buffer size.

    • Method Detail

      • getOutputStream

        public java.io.OutputStream getOutputStream()

      • setOutputStream

        public void setOutputStream​(java.io.OutputStream outputStream)
        Sets a new OutputStream to flush data to when the buffer is full. The position and total are reset, discarding any buffered bytes.
        Parameters:
        outputStream - May be null.

      • setBuffer

        public void setBuffer​(byte[] buffer)
        Sets a new buffer to write to. The max size is the buffer's length.
        See Also:
        setBuffer(byte[], int)

      • setBuffer

        public void setBuffer​(byte[] buffer,
                      int maxBufferSize)
        Sets a new buffer to write to. The bytes are not copied, the old buffer is discarded and the new buffer used in its place. The position and total are reset. The OutputStream is set to null.
        Parameters:
        maxBufferSize - If flush() does not empty the buffer, the buffer is doubled as needed until it exceeds maxBufferSize and an exception is thrown. Can be -1 for no maximum.

      • getBuffer

        public byte[] getBuffer()
        Returns the buffer. The bytes between 0 and position() are the data that has been written.

      • toBytes

        public byte[] toBytes()
        Allocates and returns a new byte[] containing the bytes currently in the buffer between 0 and position().

      • getVariableLengthEncoding

        public boolean getVariableLengthEncoding()

      • position

        public int position()
        Returns the current position in the buffer. This is the number of bytes that have not been flushed.

      • setPosition

        public void setPosition​(int position)
        Sets the current position in the buffer.

      • total

        public long total()
        Returns the total number of bytes written. This may include bytes that have not been flushed.

      • getMaxCapacity

        public int getMaxCapacity()
        The maximum buffer size, or -1 for no maximum.
        See Also:
        Output(int, int)

      • reset

        public void reset()
        Sets the position and total to 0.
        Specified by:
        reset in interface Pool.Poolable

      • require

        protected boolean require​(int required)
                   throws KryoException
        Ensures the buffer is large enough to read the specified number of bytes.
        Returns:
        true if the buffer has been resized.
        Throws:
        KryoException

      • flush

        public void flush()
           throws KryoException
        Flushes the buffered bytes. The default implementation writes the buffered bytes to the OutputStream, if any, and sets the position to 0. Can be overridden to flush the bytes somewhere else.
        Specified by:
        flush in interface java.io.Flushable
        Overrides:
        flush in class java.io.OutputStream
        Throws:
        KryoException

      • close

        public void close()
           throws KryoException
        Flushes any buffered bytes and closes the underlying OutputStream, if any.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        KryoException

      • write

        public void write​(int value)
           throws KryoException
        Writes a byte.
        Specified by:
        write in class java.io.OutputStream
        Throws:
        KryoException

      • write

        public void write​(byte[] bytes)
           throws KryoException
        Writes the bytes. Note the number of bytes is not written.
        Overrides:
        write in class java.io.OutputStream
        Throws:
        KryoException

      • write

        public void write​(byte[] bytes,
                  int offset,
                  int length)
           throws KryoException
        Writes the bytes. Note the number of bytes is not written.
        Overrides:
        write in class java.io.OutputStream
        Throws:
        KryoException

      • writeBytes

        public void writeBytes​(byte[] bytes)
                throws KryoException
        Writes the bytes. Note the number of bytes is not written.
        Throws:
        KryoException

      • writeBytes

        public void writeBytes​(byte[] bytes,
                       int offset,
                       int count)
                throws KryoException
        Writes the bytes. Note the number of bytes is not written.
        Throws:
        KryoException

      • writeVarInt

        public int writeVarInt​(int value,
                       boolean optimizePositive)
                throws KryoException
        Writes a 1-5 byte int.
        Parameters:
        optimizePositive - If true, small positive numbers will be more efficient (1 byte) and small negative numbers will be inefficient (5 bytes).
        Returns:
        The number of bytes written.
        Throws:
        KryoException
        See Also:
        varIntLength(int, boolean)

      • writeVarIntFlag

        public int writeVarIntFlag​(boolean flag,
                           int value,
                           boolean optimizePositive)
                    throws KryoException
        Writes a 1-5 byte int, encoding the boolean value with a bit flag.
        Parameters:
        optimizePositive - If true, small positive numbers will be more efficient (1 byte) and small negative numbers will be inefficient (5 bytes).
        Returns:
        The number of bytes written.
        Throws:
        KryoException

      • intLength

        public int intLength​(int value,
                     boolean optimizePositive)
        Returns the number of bytes that would be written with writeInt(int, boolean).

      • writeVarLong

        public int writeVarLong​(long value,
                        boolean optimizePositive)
                 throws KryoException
        Writes a 1-9 byte long.
        Parameters:
        optimizePositive - If true, small positive numbers will be more efficient (1 byte) and small negative numbers will be inefficient (9 bytes).
        Returns:
        The number of bytes written.
        Throws:
        KryoException
        See Also:
        varLongLength(long, boolean)

      • longLength

        public int longLength​(int value,
                      boolean optimizePositive)
        Returns the number of bytes that would be written with writeLong(long, boolean).

      • writeVarFloat

        public int writeVarFloat​(float value,
                         float precision,
                         boolean optimizePositive)
                  throws KryoException
        Writes a 1-5 byte float with reduced precision.
        Parameters:
        optimizePositive - If true, small positive numbers will be more efficient (1 byte) and small negative numbers will be inefficient (5 bytes).
        Returns:
        The number of bytes written.
        Throws:
        KryoException

      • writeVarDouble

        public int writeVarDouble​(double value,
                          double precision,
                          boolean optimizePositive)
                   throws KryoException
        Writes a 1-9 byte double with reduced precision.
        Parameters:
        optimizePositive - If true, small positive numbers will be more efficient (1 byte) and small negative numbers will be inefficient (9 bytes).
        Returns:
        The number of bytes written.
        Throws:
        KryoException

      • writeAscii

        public void writeAscii​(java.lang.String value)
                throws KryoException
        Writes a string that is known to contain only ASCII characters. Non-ASCII strings passed to this method will be corrupted. Each byte is a 7 bit character with the remaining byte denoting if another character is available. This is slightly more efficient than writeString(String). The string can be read using Input.readString() or Input.readStringBuilder().
        Parameters:
        value - May be null.
        Throws:
        KryoException

      • writeInts

        public void writeInts​(int[] array,
                      int offset,
                      int count)
               throws KryoException
        Writes an int array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeInts

        public void writeInts​(int[] array,
                      int offset,
                      int count,
                      boolean optimizePositive)
               throws KryoException
        Writes an int array in bulk using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean). This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeLongs

        public void writeLongs​(long[] array,
                       int offset,
                       int count)
                throws KryoException
        Writes a long array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeLongs

        public void writeLongs​(long[] array,
                       int offset,
                       int count,
                       boolean optimizePositive)
                throws KryoException
        Writes a long array in bulk using fixed or variable length encoding, depending on setVariableLengthEncoding(boolean). This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeFloats

        public void writeFloats​(float[] array,
                        int offset,
                        int count)
                 throws KryoException
        Writes a float array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeDoubles

        public void writeDoubles​(double[] array,
                         int offset,
                         int count)
                  throws KryoException
        Writes a double array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeShorts

        public void writeShorts​(short[] array,
                        int offset,
                        int count)
                 throws KryoException
        Writes a short array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeChars

        public void writeChars​(char[] array,
                       int offset,
                       int count)
                throws KryoException
        Writes a char array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • writeBooleans

        public void writeBooleans​(boolean[] array,
                          int offset,
                          int count)
                   throws KryoException
        Writes a boolean array in bulk. This may be more efficient than writing them individually.
        Throws:
        KryoException

      • varIntLength

        public static int varIntLength​(int value,
                               boolean optimizePositive)
        Returns the number of bytes that would be written with writeVarInt(int, boolean).

      • varLongLength

        public static int varLongLength​(long value,
                                boolean optimizePositive)
        Returns the number of bytes that would be written with writeVarLong(long, boolean).