net.sf.okapi.common.io

## Class FileCachedInputStream

- java.lang.Object
- - java.io.InputStream
  - - net.sf.okapi.common.io.FileCachedInputStream

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable, java.nio.channels.Channel, java.nio.channels.WritableByteChannel

      public class FileCachedInputStream
      extends java.io.InputStream
      implements java.nio.channels.WritableByteChannel

  An instance of this class acts as a buffer holding the bytes written through its `WritableByteChannel` interface (which can be easily turned into an `OutputStream` using `Channels#newOutputStream(WritableByteChannel)`). The data can be discarded at any time using `clear()`. The first `inspectable` bytes of `buffer` contains the first bytes written. When `buffer` is full, the bytes are written to an overflow file. Note that you must arbitrate carefully write and read accesses, as it is always possible to call `write(ByteBuffer)` and thus modify the length

  The method `dispose()` can be used to release the resources associated with the stream.

  ## Buffering

  This class provides no form of buffering except for the memory buffer described above, both when reading and when writing. Users should consider wrapping instances of this class, as reads after the buffer has been exhausted will be performed directly on a `RandomAccessFile`.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `byte[]` | `buffer` The inspection buffer.
    `static boolean` | `DEBUG`
    `static int` | `DEFAULT_BUFFER_SIZE` The default buffer size (1024KiB).
    `int` | `inspectable` The number of valid bytes currently in `buffer`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FileCachedInputStream()` Creates a new instance with default buffer size and overflow-file directory.
    `FileCachedInputStream(int bufferSize)` Creates a new instance with specified buffer size and default overflow-file directory.
    `FileCachedInputStream(int bufferSize, java.io.File overflowFile)` Creates a new instance with specified buffer size and overlow-file directory.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()`
    `void` | `clear()` Clears the content of this `FileCachedInputStream`, zeroing the length of the represented stream.
    `void` | `close()` Makes the stream unreadable until the next `clear()`.
    `void` | `dispose()` Disposes this stream, deleting the overflow file.
    `boolean` | `isOpen()`
    `long` | `length()`
    `void` | `mark(int readlimit)`
    `boolean` | `markSupported()`
    `long` | `position()`
    `void` | `position(long position)` Positions the input stream.
    `int` | `read()`
    `int` | `read(byte[] b)`
    `int` | `read(byte[] b, int offset, int length)`
    `void` | `reopen()` Makes the stream readable again after a `close()`.
    `void` | `reset()`
    `long` | `skip(long n)`
    `void` | `truncate(long size)` Truncates the overflow file to a given size if possible.
    `int` | `write(java.nio.ByteBuffer byteBuffer)` Appends the content of a specified buffer to the end of the currently represented stream.

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

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

- - ### Field Detail

    - #### DEBUG

          public static final boolean DEBUG

      See Also:
        Constant Field Values

    - #### DEFAULT_BUFFER_SIZE

          public static final int DEFAULT_BUFFER_SIZE

      The default buffer size (1024KiB).
      See Also:
        Constant Field Values

    - #### buffer

          public byte[] buffer

      The inspection buffer. The first `inspectable` bytes contain the first part of the input stream. The buffer is available for inspection, but users should not modify its content.

    - #### inspectable

          public int inspectable

      The number of valid bytes currently in `buffer`.

  - ### Constructor Detail

    - #### FileCachedInputStream

          public FileCachedInputStream(int bufferSize,
                                       java.io.File overflowFile)

      Creates a new instance with specified buffer size and overlow-file directory.
      Parameters:
        `bufferSize` - the buffer size, in bytes.
        `overflowFile` - the directory where the overflow file should be created, or `null` for the default temporary directory.

    - #### FileCachedInputStream

          public FileCachedInputStream(int bufferSize)
                                throws java.io.IOException

      Creates a new instance with specified buffer size and default overflow-file directory.
      Parameters:
        `bufferSize` - the buffer size, in bytes.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### FileCachedInputStream

          public FileCachedInputStream()
                                throws java.io.IOException

      Creates a new instance with default buffer size and overflow-file directory.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

  - ### Method Detail

    - #### clear

          public void clear()
                     throws java.io.IOException

      Clears the content of this `FileCachedInputStream`, zeroing the length of the represented stream.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### write

          public int write(java.nio.ByteBuffer byteBuffer)
                    throws java.io.IOException

      Appends the content of a specified buffer to the end of the currently represented stream.
      Specified by:
        `write` in interface `java.nio.channels.WritableByteChannel`
      Parameters:
        `byteBuffer` - a byte buffer.
      Returns:
        the number of bytes appended (i.e., `byteBuffer.remaining()`).
      Throws:
        `java.io.IOException`

    - #### truncate

          public void truncate(long size)
                        throws java.io.FileNotFoundException,
                               java.io.IOException

      Truncates the overflow file to a given size if possible.
      Parameters:
        `size` - the new size; the final size is the maximum between the current write position (i.e., the length of the represented stream minus the length of the inspection buffer) and this value.
      Throws:
        `java.io.FileNotFoundException` - Tif the file cannot be found.
        `java.io.IOException` - if an I/O error occurs.

    - #### close

          public void close()

      Makes the stream unreadable until the next `clear()`.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.nio.channels.Channel`
      Overrides:
        `close` in class `java.io.InputStream`
      See Also:
        `reopen()`

    - #### reopen

          public void reopen()
                      throws java.io.IOException

      Makes the stream readable again after a `close()`.
      Throws:
        `java.io.IOException` - if an I/O error occurs.
      See Also:
        `close()`

    - #### dispose

          public void dispose()
                       throws java.io.IOException

      Disposes this stream, deleting the overflow file. After that, the stream is unusable.
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### available

          public int available()
                        throws java.io.IOException

      Overrides:
        `available` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### read

          public int read(byte[] b,
                          int offset,
                          int length)
                   throws java.io.IOException

      Overrides:
        `read` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### read

          public int read(byte[] b)
                   throws java.io.IOException

      Overrides:
        `read` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### skip

          public long skip(long n)
                    throws java.io.IOException

      Overrides:
        `skip` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### read

          public int read()
                   throws java.io.IOException

      Specified by:
        `read` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### length

          public long length()
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### position

          public long position()
                        throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### position

          public void position(long position)
                        throws java.io.IOException

      Positions the input stream.
      Parameters:
        `position` - the new position (will be minimized with `length()`).
      Throws:
        `java.io.IOException` - if an I/O error occurs.

    - #### isOpen

          public boolean isOpen()

      Specified by:
        `isOpen` in interface `java.nio.channels.Channel`

    - #### mark

          public void mark(int readlimit)

      Overrides:
        `mark` in class `java.io.InputStream`

    - #### reset

          public void reset()
                     throws java.io.IOException

      Overrides:
        `reset` in class `java.io.InputStream`
      Throws:
        `java.io.IOException`

    - #### markSupported

          public boolean markSupported()

      Overrides:
        `markSupported` in class `java.io.InputStream`