Class ByteOutput

  • Direct Known Subclasses:
    CodedOutputStream

    @ExperimentalApi
    public abstract class ByteOutput
    extends Object
    An output target for raw bytes. This interface provides semantics that support two types of writing:

    Traditional write operations: (as defined by OutputStream) where the target method is responsible for either copying the data or completing the write before returning from the method call.

    Lazy write operations: where the caller guarantees that it will never modify the provided buffer and it can therefore be considered immutable. The target method is free to maintain a reference to the buffer beyond the scope of the method call (e.g. until the write operation completes).

    • Constructor Detail

      • ByteOutput

        public ByteOutput()
    • Method Detail

      • write

        public abstract void write​(byte value)
                            throws IOException
        Writes a single byte.
        Parameters:
        value - the byte to be written
        Throws:
        IOException - thrown if an error occurred while writing
      • write

        public abstract void write​(byte[] value,
                                   int offset,
                                   int length)
                            throws IOException
        Writes a sequence of bytes. The ByteOutput must copy value if it will not be processed prior to the return of this method call, since value may be reused/altered by the caller.

        NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.

        Parameters:
        value - the bytes to be written
        offset - the offset of the start of the writable range
        length - the number of bytes to write starting from offset
        Throws:
        IOException - thrown if an error occurred while writing
      • writeLazy

        public abstract void writeLazy​(byte[] value,
                                       int offset,
                                       int length)
                                throws IOException
        Writes a sequence of bytes. The ByteOutput is free to retain a reference to the value beyond the scope of this method call (e.g. write later) since it is considered immutable and is guaranteed not to change by the caller.

        NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.

        Parameters:
        value - the bytes to be written
        offset - the offset of the start of the writable range
        length - the number of bytes to write starting from offset
        Throws:
        IOException - thrown if an error occurred while writing
      • write

        public abstract void write​(ByteBuffer value)
                            throws IOException
        Writes a sequence of bytes. The ByteOutput must copy value if it will not be processed prior to the return of this method call, since value may be reused/altered by the caller.

        NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.

        Parameters:
        value - the bytes to be written. Upon returning from this call, the position of this buffer will be set to the limit
        Throws:
        IOException - thrown if an error occurred while writing
      • writeLazy

        public abstract void writeLazy​(ByteBuffer value)
                                throws IOException
        Writes a sequence of bytes. The ByteOutput is free to retain a reference to the value beyond the scope of this method call (e.g. write later) since it is considered immutable and is guaranteed not to change by the caller.

        NOTE: This method MUST NOT modify the value. Doing so is a programming error and will lead to data corruption which will be difficult to debug.

        Parameters:
        value - the bytes to be written. Upon returning from this call, the position of this buffer will be set to the limit
        Throws:
        IOException - thrown if an error occurred while writing