Package org.apache.sis.internal.storage.io

Class ChannelDataOutput

java.lang.Object
org.apache.sis.internal.storage.io.ChannelData
org.apache.sis.internal.storage.io.ChannelDataOutput
All Implemented Interfaces:
Flushable, Markable
Direct Known Subclasses:
ChannelImageOutputStream
public class ChannelDataOutput extends ChannelData implements Flushable
Provides convenience methods for working with a (WritableByteChannel, ByteBuffer) pair. The channel and the buffer must be supplied by the caller. It is okay if they have already been used before ChannelDataOutput creation.

Encapsulation

This class exposes publicly the channel and the buffer because this class is not expected to perform all possible data manipulations that we can do with the buffers. This class is only a helper tool, which often needs to be completed by specialized operations performed directly on the buffer. However, users are encouraged to transfer data from the buffer to the channel using only the methods provided in this class if they want to keep the seek(long) and getStreamPosition() values accurate.

Since this class is only a helper tool, it does not "own" the channel and consequently does not provide close() method. It is users responsibility to close the channel after usage.

Relationship with DataOutput

This class API is compatibly with the DataOutput interface, so subclasses can implement that interface if they wish. This class does not implement DataOutput itself because it is not needed for SIS purposes. However, the ChannelImageOutputStream class implements the DataOutput interface, together with the ImageOutputStream one, mostly for situations when inter-operability with javax.imageio is needed.
Since:
0.5
Version:
1.2

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private class 
    ChannelDataOutput.ArrayWriter
    Helper class for the writeFully(…) methods, in order to avoid duplicating almost identical code many times.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final WritableByteChannel
    channel
    The channel where data are written.

    Fields inherited from class org.apache.sis.internal.storage.io.ChannelData

    buffer, bufferOffset, channelOffset, filename

  • Constructor Summary

    Constructors
    Constructor
    Description
    ChannelDataOutput(String filename, WritableByteChannel channel, ByteBuffer buffer)
    Creates a new data output for the given channel and using the given buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    clear()
    Fills the buffer with the zero values from its position up to the limit.
    final void
    ensureBufferAccepts(int n)
    Makes sure that the buffer can accept at least n more bytes.
    final void
    flush()
    Flushes the buffer content to the channel.
    (package private) final void
    flushAndSetPosition(int position)
    Writes the buffer content up to the given position, then set the buffer position to the given value.
    long
    getStreamPosition()
    Returns the current byte position of the stream.
    final void
    seek(long position)
    Moves to the given position in the stream, relative to the stream position at construction time.
    final void
    write(byte[] src)
    Writes all bytes from the given array into the stream.
    final void
    write(byte[] src, int offset, int length)
    Writes length bytes starting at index offset from the given array.
    final void
    writeBit(int bit)
    Writes a single bit.
    final void
    writeBits(long bits, int numBits)
    Writes a sequence of bits.
    final void
    writeByte(int value)
    Writes the 8 low-order bits of v to the stream.
    final void
    writeChar(int value)
    Writes char value (16 bits) into the steam.
    final void
    writeChars(char[] src)
    Writes all characters from the given array into the stream.
    final void
    writeChars(char[] src, int offset, int length)
    Writes length chars starting at index offset from the given array.
    final void
    writeDouble(double value)
    Writes double value (64 bits) into the steam.
    final void
    writeDoubles(double[] src)
    Writes all doubles from the given array into the stream.
    final void
    writeDoubles(double[] src, int offset, int length)
    Writes length doubles starting at index offset from the given array.
    final void
    writeFloat(float value)
    Writes float value (32 bits) into the steam.
    final void
    writeFloats(float[] src)
    Writes all floats from the given array into the stream.
    final void
    writeFloats(float[] src, int offset, int length)
    Writes length floats starting at index offset from the given array.
    private void
    writeFully()
    Writes fully the buffer content from its position to its limit.
    final void
    writeInt(int value)
    Writes integer value (32 bits) into the steam.
    final void
    writeInts(int[] src)
    Writes all integers from the given array into the stream.
    final void
    writeInts(int[] src, int offset, int length)
    Writes length integers starting at index offset from the given array.
    final void
    writeLong(long value)
    Writes long value (64 bits) into the steam.
    final void
    writeLongs(long[] src)
    Writes all longs from the given array into the stream.
    final void
    writeLongs(long[] src, int offset, int length)
    Writes length longs starting at index offset from the given array.
    final void
    writeShort(int value)
    Writes the 16 low-order bits of value to the stream.
    final void
    writeShorts(short[] src)
    Writes all shorts from the given array into the stream.
    final void
    writeShorts(short[] src, int offset, int length)
    Writes length shorts starting at index offset from the given array.

    Methods inherited from class org.apache.sis.internal.storage.io.ChannelData

    clearBitOffset, flushBefore, getBitOffset, getFlushedPosition, mark, onEmptyTransfer, readBitFromBuffer, reset, reset, setBitOffset, setStreamPosition, skipRemainingBits, toString

    Methods inherited from class java.lang.Object

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

  • Field Details

    • channel

      public final WritableByteChannel channel
      The channel where data are written. This is supplied at construction time.

  • Constructor Details

    • ChannelDataOutput

      public ChannelDataOutput(String filename, WritableByteChannel channel, ByteBuffer buffer) throws IOException
      Creates a new data output for the given channel and using the given buffer.
      Parameters:
      filename - a file identifier used only for formatting error message.
      channel - the channel where data are written.
      buffer - the buffer where to put the data.
      Throws:
      IOException - if an error occurred while creating the data output.

  • Method Details

    • ensureBufferAccepts

      public final void ensureBufferAccepts(int n) throws IOException
      Makes sure that the buffer can accept at least n more bytes. It is caller's responsibility to ensure that the given number of bytes is not greater than the buffer capacity.

      After this method call, the buffer limit will be equal or greater than position + n.

      Parameters:
      n - the minimal number of additional bytes that the buffer shall accept.
      Throws:
      IOException - if an error occurred while writing to the channel.

    • getStreamPosition

      public long getStreamPosition()
      Returns the current byte position of the stream.
      Specified by:
      getStreamPosition in interface Markable
      Overrides:
      getStreamPosition in class ChannelData
      Returns:
      the position of the stream.

    • writeBit

      public final void writeBit(int bit) throws IOException
      Writes a single bit. This method uses only the rightmost bit of the given argument; the upper 31 bits are ignored.
      Parameters:
      bit - the bit to write (rightmost bit).
      Throws:
      IOException - if an error occurred while creating the data output.

    • writeBits

      public final void writeBits(long bits, int numBits) throws IOException
      Writes a sequence of bits. This method uses only the numBits rightmost bits; other bits are ignored.
      Parameters:
      bits - the bits to write (rightmost bits).
      numBits - the number of bits to write.
      Throws:
      IOException - if an error occurred while creating the data output.

    • writeByte

      public final void writeByte(int value) throws IOException
      Writes the 8 low-order bits of v to the stream. The 24 high-order bits of v are ignored. This method ensures that there is space for at least 1 byte in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.put(byte).
      Parameters:
      value - byte to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeShort

      public final void writeShort(int value) throws IOException
      Writes the 16 low-order bits of value to the stream. The 16 high-order bits of v are ignored. This method ensures that there is space for at least 2 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putShort(short).
      Parameters:
      value - short integer to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeChar

      public final void writeChar(int value) throws IOException
      Writes char value (16 bits) into the steam. This method ensures that there is space for at least 2 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putChar(char).
      Parameters:
      value - character to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeInt

      public final void writeInt(int value) throws IOException
      Writes integer value (32 bits) into the steam. This method ensures that there is space for at least 4 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putInt(int).
      Parameters:
      value - integer to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeLong

      public final void writeLong(long value) throws IOException
      Writes long value (64 bits) into the steam. This method ensures that there is space for at least 4 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putLong(long).
      Parameters:
      value - long integer to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeFloat

      public final void writeFloat(float value) throws IOException
      Writes float value (32 bits) into the steam. This method ensures that there is space for at least 4 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putFloat(float).
      Parameters:
      value - floating point value to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • writeDouble

      public final void writeDouble(double value) throws IOException
      Writes double value (64 bits) into the steam. This method ensures that there is space for at least 8 bytes in the buffer, (writing previous bytes into the channel if necessary), then delegates to ByteBuffer.putDouble(double).
      Parameters:
      value - double precision floating point value to be written.
      Throws:
      IOException - if some I/O exception occurs during writing.

    • write

      public final void write(byte[] src) throws IOException
      Writes all bytes from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of bytes to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeShorts

      public final void writeShorts(short[] src) throws IOException
      Writes all shorts from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of shorts to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeChars

      public final void writeChars(char[] src) throws IOException
      Writes all characters from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of characters to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeInts

      public final void writeInts(int[] src) throws IOException
      Writes all integers from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of integers to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeLongs

      public final void writeLongs(long[] src) throws IOException
      Writes all longs from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of longs to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeFloats

      public final void writeFloats(float[] src) throws IOException
      Writes all floats from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of floats to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeDoubles

      public final void writeDoubles(double[] src) throws IOException
      Writes all doubles from the given array into the stream. The implementation is as below:
      Parameters:
      src - an array of doubles to be written into stream.
      Throws:
      IOException - if an error occurred while writing the stream.

    • write

      public final void write(byte[] src, int offset, int length) throws IOException
      Writes length bytes starting at index offset from the given array.
      Parameters:
      src - an array containing the bytes to write.
      offset - index within src of the first byte to write.
      length - the number of bytes to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeChars

      public final void writeChars(char[] src, int offset, int length) throws IOException
      Writes length chars starting at index offset from the given array.
      Parameters:
      src - an array containing the characters to write.
      offset - index within src of the first char to write.
      length - the number of chars to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeShorts

      public final void writeShorts(short[] src, int offset, int length) throws IOException
      Writes length shorts starting at index offset from the given array.
      Parameters:
      src - an array containing the shorts to write.
      offset - index within src of the first short to write.
      length - the number of shorts to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeInts

      public final void writeInts(int[] src, int offset, int length) throws IOException
      Writes length integers starting at index offset from the given array.
      Parameters:
      src - an array containing the integers to write.
      offset - index within src of the first integer to write.
      length - the number of integers to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeLongs

      public final void writeLongs(long[] src, int offset, int length) throws IOException
      Writes length longs starting at index offset from the given array.
      Parameters:
      src - an array containing the longs to write.
      offset - index within src of the first long to write.
      length - the number of longs to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeFloats

      public final void writeFloats(float[] src, int offset, int length) throws IOException
      Writes length floats starting at index offset from the given array.
      Parameters:
      src - an array containing the floats to write.
      offset - index within src of the first float to write.
      length - the number of floats to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • writeDoubles

      public final void writeDoubles(double[] src, int offset, int length) throws IOException
      Writes length doubles starting at index offset from the given array.
      Parameters:
      src - an array containing the doubles to write.
      offset - index within src of the first double to write.
      length - the number of doubles to write.
      Throws:
      IOException - if an error occurred while writing the stream.

    • clear

      private void clear()
      Fills the buffer with the zero values from its position up to the limit. After this method call, the position is undetermined and shall be set to a new value by the caller.

    • seek

      public final void seek(long position) throws IOException
      Moves to the given position in the stream, relative to the stream position at construction time. If the given position is greater than the stream length, then the values of bytes between the previous stream length and the given position are unspecified. The limit is unchanged.
      Specified by:
      seek in class ChannelData
      Parameters:
      position - the position where to move.
      Throws:
      IOException - if the stream cannot be moved to the given position.

    • flush

      public final void flush() throws IOException
      Flushes the buffer content to the channel. This method does not flush the channel itself.
      Specified by:
      flush in interface Flushable
      Throws:
      IOException - if an error occurred while writing to the channel.

    • flushAndSetPosition

      final void flushAndSetPosition(int position) throws IOException
      Writes the buffer content up to the given position, then set the buffer position to the given value. The buffer limit is unchanged, and the buffer offset is incremented by the given value.
      Overrides:
      flushAndSetPosition in class ChannelData
      Throws:
      IOException

    • writeFully

      private void writeFully() throws IOException
      Writes fully the buffer content from its position to its limit. After this method call, the buffer position is equal to its limit.
      Throws:
      IOException - if an error occurred while writing to the channel.