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

Class HyperRectangleReader

java.lang.Object
org.apache.sis.internal.storage.io.HyperRectangleReader
Direct Known Subclasses:
RawRasterReader
public class HyperRectangleReader extends Object
Helper methods for reading a rectangular area, a cube or a hyper-cube from a channel. The data can be stored in an existing array, or a new array can be created. This class does not handle compression; it is rather designed for efficient reading of uncompressed data. It tries to read the largest possible contiguous blocks of data with single ReadableByteChannel.read(ByteBuffer) and ByteBuffer.get(byte[], int, int) method calls.

This reader supports subsampling in any dimension. However, subsampling in the first dimension (the one with fastest varying index) is generally not efficient because it forces a large amount of seek operations. This class makes no special case for making that specific subsampling faster. It is generally not worth because subsampling in the first dimension is a special case anyway. It is the "dimension" of bands in an image using the pixel interleaved sample model, so the caller often needs to process subsampling in the first dimension in a different way than other dimensions anyway.

Since:
0.7
Version:
1.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private long
    origin
    The input position of the first sample (ignoring sub-area and subsampling).
    private final DataTransfer
    reader
    The channel from which to read the values, together with a buffer for transferring data.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HyperRectangleReader(byte dataType, ChannelDataInput input)
    Creates a new reader for the given input.
    HyperRectangleReader(String filename, Buffer data)
    Creates a new reader for the data in an existing buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    final String
    filename()
    Returns a file identifier for error messages or debugging purpose.
    final long
    getOrigin()
    Returns the input position of the first sample (ignoring sub-area and subsampling).
    final Object
    read(Region region)
    Reads data in the given region.
    private Object
    read(Region region, int capacity, boolean asBuffer)
    Implementation of read(Region) and #readAsBuffer(Region).
    final Buffer
    readAsBuffer(Region region, int capacity)
    Reads data in the given region as a buffer.
    final int
    sampleSize()
    Returns the number of bytes in each value to be read.
    final void
    setOrigin(long p)
    Sets the input position of the first sample (ignoring sub-area and subsampling).

    Methods inherited from class java.lang.Object

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

  • Field Details

    • reader

      private final DataTransfer reader
      The channel from which to read the values, together with a buffer for transferring data.

    • origin

      private long origin
      The input position of the first sample (ignoring sub-area and subsampling). This is initially the origin argument given to the constructor, copied verbatim.
      See Also:

  • Constructor Details

    • HyperRectangleReader

      public HyperRectangleReader(byte dataType, ChannelDataInput input) throws DataStoreContentException
      Creates a new reader for the given input.
      Parameters:
      dataType - the type of elements to read, as one of the constants defined in Numbers.
      input - the channel from which to read the values, together with a buffer for transferring data.
      Throws:
      DataStoreContentException - if the given dataType is not one of the supported values.

    • HyperRectangleReader

      public HyperRectangleReader(String filename, Buffer data) throws IOException
      Creates a new reader for the data in an existing buffer. The data will be read from the current buffer position to the buffer limit.
      Parameters:
      filename - a data source name, for error messages or debugging purpose.
      data - a buffer containing the data to read.
      Throws:
      IOException - should never happen.

  • Method Details

    • filename

      public final String filename()
      Returns a file identifier for error messages or debugging purpose.
      Returns:
      the file identifier.

    • sampleSize

      public final int sampleSize()
      Returns the number of bytes in each value to be read.
      Returns:
      number of bytes per value.

    • getOrigin

      public final long getOrigin()
      Returns the input position of the first sample (ignoring sub-area and subsampling). Default value is 0.
      Returns:
      the input position of the first sample (ignoring sub-area and subsampling).

    • setOrigin

      public final void setOrigin(long p)
      Sets the input position of the first sample (ignoring sub-area and subsampling).
      Parameters:
      p - the new input position of the first sample (ignoring sub-area and subsampling).

    • read

      public final Object read(Region region) throws IOException
      Reads data in the given region. It is caller's responsibility to ensure that the Region object has been created with a size argument equals to this hyper-rectangle size.
      Parameters:
      region - the sub-area to read and the subsampling to use.
      Returns:
      the data in an array of primitive type.
      Throws:
      IOException - if an error occurred while transferring data from the channel.
      ArithmeticException - if the region to read is too large or too far from origin.

    • readAsBuffer

      public final Buffer readAsBuffer(Region region, int capacity) throws IOException
      Reads data in the given region as a buffer. This method performs the same work than read(Region) except that the array is wrapped in a heap buffer. The capacity argument is the minimal length of the array to allocate. The actual length of data read will be the limit of the returned buffer.
      Parameters:
      region - the sub-area to read and the subsampling to use.
      capacity - minimal length of the array to allocate, or 0 for automatic.
      Returns:
      the data in a buffer backed by an array on the heap.
      Throws:
      IOException - if an error occurred while transferring data from the channel.
      ArithmeticException - if the region to read is too large or too far from origin.

    • read

      private Object read(Region region, int capacity, boolean asBuffer) throws IOException
      Implementation of read(Region) and #readAsBuffer(Region).
      Parameters:
      region - the sub-area to read and the subsampling to use.
      capacity - minimal length of the array to allocate, or 0 for automatic.
      asBuffer - true for wrapping the array in a Buffer.
      Returns:
      the data as an array or wrapped in a buffer, depending on asBuffer value.
      Throws:
      IOException