Package uk.ac.starlink.fits

## Class MappedFile

- java.lang.Object
- - uk.ac.starlink.fits.AbstractArrayDataIO
  - - uk.ac.starlink.fits.MappedFile

- All Implemented Interfaces:
    `java.io.Closeable`, `java.io.DataInput`, `java.io.DataOutput`, `java.lang.AutoCloseable`, `nom.tam.util.ArrayDataInput`, `nom.tam.util.ArrayDataOutput`, `nom.tam.util.FitsIO`, `nom.tam.util.RandomAccess`

      public class MappedFile
      extends AbstractArrayDataIO
      implements nom.tam.util.RandomAccess

  Provides mapped access to a data buffer using a single mapped byte buffer, compatible with nom.tam.util classes.

  This class implements the `nom.tam.util` `ArrayDataInput`, `ArrayDataOutput` and `RandomAccess` interfaces in the same way that `nom.tam.util.BufferedFile` does. Hence it can be used as a drop-in replacement for BufferedFile. Unlike BufferedFile however, it does mapped access to files (using java.nio.Buffer objects). This may be moderately more efficient for sequential access to a file, but is dramatically more efficient if very random access is required. This is because BufferedFile effectively always assumes that you are going to read sequentially, so that accessing a single datum distant from (or before) the last datum accessed always results in filling a whole buffer.

  ### Limitations:

  - Files larger than Integer.MAX_VALUE bytes may not currently be accessed
  - Access to very large files may fail if virtual memory runs out
  Since:
    30 Aug 2002
  Author:
    Mark Taylor (Starlink)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `MappedFile.FileTooLongException` | Exception indicating that a file is too long to map.

  - ### Field Summary

    - ### Fields inherited from interface nom.tam.util.FitsIO

      `BITS_OF_1_BYTE, BITS_OF_2_BYTES, BITS_OF_3_BYTES, BITS_OF_4_BYTES, BITS_OF_5_BYTES, BITS_OF_6_BYTES, BITS_OF_7_BYTES, BYTE_1_OF_LONG_MASK, BYTE_2_OF_LONG_MASK, BYTE_3_OF_LONG_MASK, BYTE_4_OF_LONG_MASK, BYTE_MASK, BYTES_IN_BOOLEAN, BYTES_IN_BYTE, BYTES_IN_CHAR, BYTES_IN_DOUBLE, BYTES_IN_FLOAT, BYTES_IN_INTEGER, BYTES_IN_LONG, BYTES_IN_SHORT, DEFAULT_BUFFER_SIZE, HIGH_INTEGER_MASK, INTEGER_MASK, SHORT_MASK, SHORT_OF_LONG_MASK`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MappedFile​(java.lang.String filename)` | Constructs a MappedFile object by mapping the whole of an existing file using read-only mode.
    `MappedFile​(java.lang.String filename, java.lang.String mode)` | Constructs a MappedFile object by mapping the whole of an existing file with a given mode.
    `MappedFile​(java.lang.String filename, java.lang.String mode, long start, int size)` | Constructs a MappedFile object by mapping part of an existing file with a given mode.
    `MappedFile​(java.nio.ByteBuffer buf)` | Constructs a MappedFile object from a byte buffer.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` |
    `void` | `flush()` |
    `protected byte` | `get()` | Reads one byte from the current position.
    `protected void` | `get​(byte[] buf, int offset, int length)` | Reads bytes into a buffer from the current position.
    `long` | `getFilePointer()` |
    `long` | `length()` | Returns the size of this buffer.
    `void` | `mark​(int readlimit)` |
    `boolean` | `markSupported()` |
    `protected void` | `put​(byte b)` | Writes a single byte at the current position.
    `protected void` | `put​(byte[] buf, int offset, int length)` | Writes bytes from a buffer to the current position.
    `protected long` | `remaining()` | Returns the number of bytes remaining between the current position and the end of the file.
    `void` | `reset()` |
    `void` | `seek​(long offsetFromStart)` |
    `long` | `skip​(long offset)` |
    `void` | `skipAllBytes​(int toSkip)` |
    `void` | `skipAllBytes​(long toSkip)` |
    `int` | `skipBytes​(int toSkip)` |

    - ### Methods inherited from class uk.ac.starlink.fits.AbstractArrayDataIO

      `read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, readArray, readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLArray, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, write, writeArray, writeBoolean, writeByte, writeBytes, writeChar, writeChars, writeDouble, writeFloat, writeInt, writeLong, writeShort, writeUTF`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface nom.tam.util.ArrayDataInput

      `read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, read, readArray, readFully, readLArray`

    - ### Methods inherited from interface java.io.DataInput

      `readBoolean, readByte, readChar, readDouble, readFloat, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF`

- - ### Constructor Detail

    - #### MappedFile

          public MappedFile​(java.nio.ByteBuffer buf)

      Constructs a MappedFile object from a byte buffer.
      Parameters:
        `buf` - byte buffer

    - #### MappedFile

          public MappedFile​(java.lang.String filename)
                     throws java.io.IOException

      Constructs a MappedFile object by mapping the whole of an existing file using read-only mode.
      Parameters:
        `filename` - name of the file to map
      Throws:
        `MappedFile.FileTooLongException` - if the file is too long to map
        `java.io.IOException`

    - #### MappedFile

          public MappedFile​(java.lang.String filename,
                            java.lang.String mode)
                     throws java.io.IOException

      Constructs a MappedFile object by mapping the whole of an existing file with a given mode.
      Parameters:
        `filename` - name of the file to map
        `mode` - mode
      Throws:
        `MappedFile.FileTooLongException` - if the file is too long to map
        `java.io.IOException`

    - #### MappedFile

          public MappedFile​(java.lang.String filename,
                            java.lang.String mode,
                            long start,
                            int size)
                     throws java.io.IOException

      Constructs a MappedFile object by mapping part of an existing file with a given mode.
      Parameters:
        `filename` - name of the file to map
        `mode` - mode
        `start` - offset of region to map
        `size` - length of region to map
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### seek

          public void seek​(long offsetFromStart)
                    throws java.io.IOException

      Specified by:
        `seek` in interface `nom.tam.util.RandomAccess`
      Throws:
        `java.io.IOException`

    - #### skip

          public long skip​(long offset)

      Specified by:
        `skip` in interface `nom.tam.util.ArrayDataInput`

    - #### getFilePointer

          public long getFilePointer()

      Specified by:
        `getFilePointer` in interface `nom.tam.util.RandomAccess`

    - #### skipBytes

          public int skipBytes​(int toSkip)

      Specified by:
        `skipBytes` in interface `java.io.DataInput`

    - #### skipAllBytes

          public void skipAllBytes​(long toSkip)
                            throws java.io.IOException

      Specified by:
        `skipAllBytes` in interface `nom.tam.util.ArrayDataInput`
      Throws:
        `java.io.IOException`

    - #### skipAllBytes

          public void skipAllBytes​(int toSkip)
                            throws java.io.IOException

      Specified by:
        `skipAllBytes` in interface `nom.tam.util.ArrayDataInput`
      Throws:
        `java.io.IOException`

    - #### markSupported

          public boolean markSupported()

    - #### mark

          public void mark​(int readlimit)

      Specified by:
        `mark` in interface `nom.tam.util.ArrayDataInput`

    - #### reset

          public void reset()
                     throws java.io.IOException

      Specified by:
        `reset` in interface `nom.tam.util.ArrayDataInput`
      Throws:
        `java.io.IOException`

    - #### get

          protected byte get()
                      throws java.io.IOException

      Description copied from class: `AbstractArrayDataIO`
      Reads one byte from the current position.
      Specified by:
        `get` in class `AbstractArrayDataIO`
      Returns:
        next byte
      Throws:
        `java.io.IOException`

    - #### get

          protected void get​(byte[] buf,
                             int offset,
                             int length)
                      throws java.io.IOException

      Description copied from class: `AbstractArrayDataIO`
      Reads bytes into a buffer from the current position.
      Specified by:
        `get` in class `AbstractArrayDataIO`
      Parameters:
        `buf` - destination buffer
        `offset` - offset of first byte in `buf` to be written
        `length` - maximum number of bytes to be written to `buf`
      Throws:
        `java.io.IOException`

    - #### put

          protected void put​(byte b)
                      throws java.io.IOException

      Description copied from class: `AbstractArrayDataIO`
      Writes a single byte at the current position.
      Specified by:
        `put` in class `AbstractArrayDataIO`
      Parameters:
        `b` - output byte
      Throws:
        `java.io.IOException`

    - #### put

          protected void put​(byte[] buf,
                             int offset,
                             int length)
                      throws java.io.IOException

      Description copied from class: `AbstractArrayDataIO`
      Writes bytes from a buffer to the current position.
      Specified by:
        `put` in class `AbstractArrayDataIO`
      Parameters:
        `buf` - source buffer
        `offset` - offset of first byte in `buf` to be read
        `length` - number of bytes from `buf` to be read
      Throws:
        `java.io.IOException`

    - #### length

          public long length()

      Description copied from class: `AbstractArrayDataIO`
      Returns the size of this buffer. May be -1 if not known/unlimited.
      Specified by:
        `length` in class `AbstractArrayDataIO`
      Returns:
        length or -1

    - #### remaining

          protected long remaining()

      Description copied from class: `AbstractArrayDataIO`
      Returns the number of bytes remaining between the current position and the end of the file. If there is no end to the file, it is permissible to return `Long.MAX_VALUE`;
      Specified by:
        `remaining` in class `AbstractArrayDataIO`
      Returns:
        number of bytes left in file

    - #### close

          public void close()

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `nom.tam.util.FitsIO`

    - #### flush

          public void flush()

      Specified by:
        `flush` in interface `nom.tam.util.ArrayDataOutput`