Package nom.tam.util

Class ArrayDataFile

java.lang.Object
nom.tam.util.ArrayDataFile
All Implemented Interfaces:
Closeable, Flushable, AutoCloseable, InputReader, OutputWriter
Direct Known Subclasses:
FitsFile
public class ArrayDataFile extends Object
Efficient reading and writing of arrays to and from files, with custom encoding. Compared to its superclass, it add only the translation layer for encoding and decoding binary data to convert between Java arrays and their binary representation in file.
Since:
1.16
Author:
Attila Kovacs
See Also:

  • Method Details

    • getEncoder

      public OutputEncoder getEncoder()
      Returns the conversion from Java arrays to their binary representation in file. Subclass implementations can use this to access the required conversion when writing data to file.
      Returns:
      the conversion from Java arrays to their binary representation in file
      See Also:

    • getDecoder

      public InputDecoder getDecoder()
      Returns the conversion from the binary representation of arrays in file to Java arrays. Subclass implementeations can use this to access the required conversion when writing data to file.
      Returns:
      the conversion from the binary representation of arrays in the file to Java arrays
      See Also:

    • readLArray

      public long readLArray(Object o) throws IOException, IllegalArgumentException
      See ArrayDataInput.readLArray(Object) for a contract of this method.
      Parameters:
      o - an array, to be populated
      Returns:
      the actual number of bytes read from the input, or -1 if already at the end-of-file.
      Throws:
      IllegalArgumentException - if the argument is not an array or if it contains an element that is not supported for decoding.
      IOException - if there was an IO error reading from the input
      See Also:

    • readArrayFully

      public void readArrayFully(Object o) throws IOException, IllegalArgumentException
      See ArrayDataInput.readArrayFully(Object) for a contract of this method.
      Parameters:
      o - an array, to be populated
      Throws:
      IllegalArgumentException - if the argument is not an array or if it contains an element that is not supported for decoding.
      IOException - if there was an IO error reading from the input
      See Also:

    • readImage

      public void readImage(Object o) throws EOFException, IOException, IllegalArgumentException
      Like readArrayFully(Object) but strictly for numerical types only.
      Parameters:
      o - An any-dimensional array containing only numerical types
      Throws:
      IllegalArgumentException - if the argument is not an array or if it contains an element that is not supported.
      EOFException - if already at the end of file.
      IOException - if there was an IO error
      Since:
      1.18
      See Also:

    • writeArray

      public void writeArray(Object o) throws IOException, IllegalArgumentException
      See ArrayDataOutput.writeArray(Object) for a contract of this method.
      Parameters:
      o - an array ot any type.
      Throws:
      IllegalArgumentException - if the argument is not an array or if it contains an element that is not supported for encoding.
      IOException - if there was an IO error writing to the output.

    • seek

      public final void seek(long newPos) throws IOException
      Sets a new position in the file for subsequent reading or writing.
      Parameters:
      newPos - the new byte offset from the beginning of the file. It may be beyond the current end of the file, for example for writing more data after some 'gap'.
      Throws:
      IOException - if the position is negative or cannot be set.

    • getChannel

      public final FileChannel getChannel()
      Get the channel associated with this file. Note that this returns the channel of the associated RandomAccessFile. Note that since the BufferedFile buffers the I/O's to the underlying file, the offset of the channel may be different from the offset of the BufferedFile. This is different for a RandomAccessFile where the offsets are guaranteed to be the same.
      Returns:
      the file channel

    • getFD

      public final FileDescriptor getFD() throws IOException
      Get the file descriptor associated with this stream. Note that this returns the file descriptor of the associated RandomAccessFile.
      Returns:
      the file descriptor
      Throws:
      IOException - if the descriptor could not be accessed.

    • getFilePointer

      public final long getFilePointer()
      Gets the current read/write position in the file.
      Returns:
      the current byte offset from the beginning of the file.

    • hasAvailable

      public final boolean hasAvailable(int need) throws IOException
      Checks if there are the required number of bytes available to read from this file.
      Parameters:
      need - the number of bytes we need.
      Returns:
      true if the needed number of bytes can be read from the file or else false.
      Throws:
      IOException - if there was an IO error accessing the file.

    • length

      public final long length() throws IOException
      Returns the current length of the file.
      Returns:
      the current length of the file.
      Throws:
      IOException - if the operation failed

    • setLength

      public void setLength(long newLength) throws IOException
      Sets the length of the file. This method calls the method of the same name in RandomAccessFileIO.
      Parameters:
      newLength - The number of bytes at which the file is set.
      Throws:
      IOException - if the resizing of the underlying stream fails

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • flush

      public void flush() throws IOException
      Specified by:
      flush in interface Flushable
      Throws:
      IOException

    • write

      public final void write(int b) throws IOException
      Description copied from interface: OutputWriter
      Writes a byte. See the general contract of DataOutputStream.write(int).
      Specified by:
      write in interface OutputWriter
      Parameters:
      b - the (unsigned) byte value to write.
      Throws:
      IOException - if there was an underlying IO error
      See Also:

    • read

      public final int read() throws IOException
      Description copied from interface: InputReader
      Reads a byte. See the general contract of FilterInputStream.read().
      Specified by:
      read in interface InputReader
      Returns:
      the (unsigned) byte value or -1 if there is nothing left to read.
      Throws:
      IOException - if there was an underlying IO error
      See Also:

    • write

      public final void write(byte[] b, int from, int len) throws IOException
      Description copied from interface: OutputWriter
      Writes up to the specified number of bytes from a buffer to the stream. See the general contract of DataOutputStream.write(byte[], int, int).
      Specified by:
      write in interface OutputWriter
      Parameters:
      b - the buffer
      from - the starting buffer index
      len - the number of bytes to write.
      Throws:
      IOException - if there was an underlying IO error
      See Also:

    • read

      public final int read(byte[] b, int from, int len) throws IOException
      Description copied from interface: InputReader
      Reads up to the specified number of bytes into a buffer. See the general contract of DataInputStream.read(byte[], int, int).
      Specified by:
      read in interface InputReader
      Parameters:
      b - the buffer
      from - the starting buffer index
      len - the number of bytes to read.
      Returns:
      the number of bytes actually read, or -1 if there is nothing left to read.
      Throws:
      IOException - if there was an underlying IO error
      See Also:

    • readFully

      public final void readFully(byte[] b) throws EOFException, IOException
      Reads bytes to completely fill the supplied buffer. If not enough bytes are avaialable in the file to fully fill the buffer, an EOFException will be thrown.
      Parameters:
      b - the buffer
      Throws:
      EOFException - if already at the end of file.
      IOException - if there was an IO error before the buffer could be fully populated.

    • readFully

      public void readFully(byte[] b, int off, int len) throws EOFException, IOException
      Reads bytes to fill the supplied buffer with the requested number of bytes from the given starting buffer index. If not enough bytes are avaialable in the file to deliver the reqauested number of bytes the buffer, an EOFException will be thrown.
      Parameters:
      b - the buffer
      off - the buffer index at which to start reading data
      len - the total number of bytes to read.
      Throws:
      EOFException - if already at the end of file.
      IOException - if there was an IO error before the requested number of bytes could all be read.

    • readUTF

      public final String readUTF() throws IOException
      Same as RandomAccessFile.readUTF().
      Returns:
      a string
      Throws:
      IOException - if there was an IO error while reading from the file.

    • writeUTF

      public final void writeUTF(String s) throws IOException
      Same as RandomAccessFile.writeUTF(String)
      Parameters:
      s - a string
      Throws:
      IOException - if there was an IO error while writing to the file.

    • skip

      public final long skip(long n) throws IOException
      Moves the file pointer by a number of bytes from its current position.
      Parameters:
      n - the number of byter to move. Negative values are allowed and result in moving the pointer backward.
      Returns:
      the actual number of bytes that the pointer moved, which may be fewer than requested if the file boundary was reached.
      Throws:
      IOException - if there was an IO error.

    • read

      public final int read(byte[] b) throws IOException
      Read as many bytes into a byte array as possible. The number of bytes read may be fewer than the size of the array, for example because the end-of-file is reached during the read.
      Parameters:
      b - the byte buffer to fill with data from the file.
      Returns:
      the number of bytes actually read.
      Throws:
      IOException - if there was an IO error while reading, other than the end-of-file.

    • write

      public final void write(byte[] b) throws IOException
      Writes the contents of a byte array into the file.
      Parameters:
      b - the byte buffer to write into the file.
      Throws:
      IOException - if there was an IO error while writing to the file...