de.flam.flcbyt

## Class FlamInputStream

- java.lang.Object
- - java.io.InputStream
  - - de.flam.flcbyt.FlamInputStream

- All Implemented Interfaces:
    Closeable, AutoCloseable

      public class FlamInputStream
      extends InputStream

  This InputStream provides sequential read access to original files. Original files can be normal binary, text or xml data as well as GZIP-, BZIP2-, XZ-, FLAM4-Files or any other kind of original data stream format supported by FLAM. It includes all conversion and formatting capabilities of the Frankenstein Limes Universal Converter (FLUC).

  For a more detailed description, please refer to FLAM byte interface (FLCBYT) C API manual.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `FlamInputStream(String fileString, String formatString)` Uses the native FLAM byte interface (written in C) to open a normal file, a member in a FLAM4FILE, a GZIP file or a member in a concatenated GZIP-, BZIP- or XZ-File or any other supported file format as an InputStream.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `String` | `close(boolean success, de.flam.flcbyt.enumeration.StatisticsFormat statsFormat)` Closes this InputStream and releases any system resources associated with the stream.
    `String` | `getStateString()` When opening a file through the FLAM byte interface, a state string is returned that contains some metadata about the opened file.
    `static void` | `loadLibrary()` Deprecated. May be removed in future versions; use `NativeLibraryLoader.loadLibrary()` instead.
    `static void` | `loadLibrary(String dllPath)` Deprecated. May be removed in future versions; use `NativeLibraryLoader.loadLibrary()` instead.
    `int` | `read()`
    `int` | `read(byte[] b)`
    `int` | `read(byte[] b, int off, int len)`

    - ### Methods inherited from class java.io.InputStream

      `available, mark, markSupported, reset, skip`

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

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

- - ### Constructor Detail

    - #### FlamInputStream

          public FlamInputStream(String fileString,
                                 String formatString)
                          throws CharacterCodingException,
                                 de.flam.flcbyt.exception.FlamException

      Uses the native FLAM byte interface (written in C) to open a normal file, a member in a FLAM4FILE, a GZIP file or a member in a concatenated GZIP-, BZIP- or XZ-File or any other supported file format as an InputStream. It supports base encoding, encryption, compression, character conversion and text formatting, among others.

      This stream class is backed by a native C library (flcbytjava) which must be loaded prior to calling this constructor by calling either `loadLibrary()` or `loadLibrary(String)`. Failing to do so results in undefined (JVM-dependent) behavior.

      The file definition string parameter uses the same syntax as the read method of the FLCL CONV command. The complete syntax and help can be obtained with the corresponding functions below. The string must start with 'read.' followed by the corresponding method (binary/char/text/flam4/xml/...).

      Examples:

               "read.text(file='test.txt')"

      Please call:

               getHelp(HelpSubject.READ_FILE, 10, null)
               getSyntax(HelpSubject.READ_FILE, 10, null)

      for more information.

      The format string uses the syntax of the 'format' union which was specifically designed for the byte interface to format a byte stream based on the FLAM elements. The string must start with 'format.' followed by the corresponding method.

      Examples:

               "format.text(method=CRLF suptws ccsid='UTF-16LE')"
               "format.bin()"
               "format.char(ccsid=DEFAULT)"
               "format.record(ccsid='IBM-1141')"

      Please call:

               FlamByteInterface.getHelp(HelpSubject.READ_FORMAT, 10, null)
               FlamByteInterface.getSyntax(HelpSubject.READ_FORMAT, 10, null)

      for more information.

      The file string defines how the FLAM elements are read from to the file. The format string defines how the FLAM elements are converted into a byte stream or records.

      Parameters:
        `fileString` - A file string of the FLCL CONV syntax for read operations
        `formatString` - A format string specifying the data format of the stream
      Throws:
        `CharacterCodingException` - if converting the parameter strings to the charset required by the native interface fails
        `de.flam.flcbyt.exception.FlamException` - if the specified file cannot be opened
        `IllegalArgumentException` - if fileString does not specify a read operation ("read." or "input.")

  - ### Method Detail

    - #### loadLibrary

          @Deprecated
          public static void loadLibrary()

      Deprecated. May be removed in future versions; use `NativeLibraryLoader.loadLibrary()` instead.
      Loads the native JNI-based library (flcbytjava) that backs the functionality of this class. Calls `FlamByteInterface.loadLibrary()`.
      See Also:
        `FlamByteInterface.loadLibrary()`

    - #### loadLibrary

          @Deprecated
          public static void loadLibrary(String dllPath)

      Deprecated. May be removed in future versions; use `NativeLibraryLoader.loadLibrary()` instead.
      Loads the native JNI-based library that backs the functionality of this class from the file specified by the path passed as argument. Calls `FlamByteInterface.loadLibrary(String)`.
      Parameters:
        `dllPath` - Path to the (lib)flybytjava DLL
      See Also:
        `FlamByteInterface.loadLibrary(String)`

    - #### read

          public int read()
                   throws IOException

      Specified by:
        `read` in class `InputStream`
      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `InputStream`
      Throws:
        `IOException`

    - #### close

          public String close(boolean success,
                              de.flam.flcbyt.enumeration.StatisticsFormat statsFormat)
                       throws de.flam.flcbyt.exception.FlamException,
                              CharacterCodingException

      Closes this InputStream and releases any system resources associated with the stream. In contrast to `close()`, this method can provide statistical information.

      The 'success' flag allows you to indicate whether the operation using the file was successful from the caller's point-of-view. If you set the 'remove' flag in the file string passed to the constructor, the file is only removed if you indicate success, i.e. pass true for the 'success' parameter at read or indicate failure (false) at write. In case of an error while processing the read data, it may be more reasonable to keep the file, even though it was flagged for deletion.

      You can also specify the output format for statistics, e.g. a plain list or XML.

      Parameters:
        `success` - True indicates that the data was processed successfully by the caller
        `statsFormat` - Format of the returned statistics
      Returns:
        A string containing statistical data from the FLAM byte interface
      Throws:
        `de.flam.flcbyt.exception.FlamException` - if an error occurs while closing the file
        `CharacterCodingException` - if the statistics information string cannot be converted from the native charset to a Unicode string
      See Also:
        `close()`

    - #### read

          public int read(byte[] b,
                          int off,
                          int len)
                   throws IOException

      Overrides:
        `read` in class `InputStream`
      Throws:
        `IOException`

    - #### read

          public int read(byte[] b)
                   throws IOException

      Overrides:
        `read` in class `InputStream`
      Throws:
        `IOException`

    - #### getStateString

          public String getStateString()

      When opening a file through the FLAM byte interface, a state string is returned that contains some metadata about the opened file. This state string is supposed to be passed to the constructor of a `FlamOutputStream` in order to keep the metadata that would be lost, otherwise.
      Returns:
        The state string returned by the FLAM byte interface, if any