de.flam.flcbyt

## Class FlamOutputStream

- java.lang.Object
- - java.io.OutputStream
  - - de.flam.flcbyt.FlamOutputStream

- All Implemented Interfaces:
    Closeable, Flushable, AutoCloseable

      public class FlamOutputStream
      extends OutputStream

  This InputStream provides sequential write 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
    `FlamOutputStream(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 OutputStream.
    `FlamOutputStream(String fileString, String formatString, String state)` 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 OutputStream.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()`
    `String` | `close(de.flam.flcbyt.enumeration.StatisticsFormat statsFormat)` Closes this OutputStream and releases any system resources associated with the stream.
    `void` | `flush()` Flushes this output stream and forces any buffered output bytes to be written out.
    `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.
    `void` | `write(byte[] b)`
    `void` | `write(byte[] b, int off, int len)`
    `void` | `write(int b)`

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

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

- - ### Constructor Detail

    - #### FlamOutputStream

          public FlamOutputStream(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 OutputStream. 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 write method of the FLCL CONV command. The complete syntax and help can be obtained with the corresponding functions below. The string must start with 'write.' followed by the corresponding method (binary/char/text/flam4/xml/...).

      Example:

               "write.binary(file='test.gz' comp.gzip(level=BEST))"

      Please call:

               getHelp(HelpSubject.WRITE_FILE, 10, null)
               getSyntax(HelpSubject.WRITE_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 the byte stream into 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:

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

      for more information.

      The file string defines how the FLAM elements are written to the file. The format string defines how your input data is converted into FLAM elements.

      Parameters:
        `fileString` - A file string of the FLCL CONV syntax for write operations
        `formatString` - A format string specifying the input data format
      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.")

    - #### FlamOutputStream

          public FlamOutputStream(String fileString,
                                  String formatString,
                                  String state)
                           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 OutputStream. 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 write method of the FLCL CONV command. The complete syntax and help can be obtained with the corresponding functions below. The string must start with 'write.' followed by the corresponding method (binary/char/text/flam4/xml/...).

      Example:

               "write.binary(file='test.gz' comp.gzip(level=BEST))"

      Please call:

               getHelp(HelpSubject.WRITE_FILE, 10, null)
               getSyntax(HelpSubject.WRITE_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 the byte stream into 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:

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

      for more information.

      The file string defines how the FLAM elements are written to the file. The format string defines how your input data is converted into FLAM elements.

      This constructor accepts an optional string containing internal state information and can be used to transfer attributes, values and other information from an input file opened by a `FlamInputStream` to an output file opened by a `FlamOutputStream`.

      The state string contains mainly file attributes which must be known to fill header information for archives (GZIP, FLAM) correctly.

      You can look up the state string syntax and help with the corresponding functions of class `FlamByteInterface` below. The string must start with 'state(' followed by the corresponding value definitions and closed with ')'.

      Example:

               "state(member='test.txt' recf=FBA recl=120)"

      Please use (from `FlamByteInterface`):

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

      for more information.
      Parameters:
        `fileString` - A file string of the FLCL CONV syntax for write operations
        `formatString` - A format string specifying the input data format
        `state` - An optional string containing internal state information, may be null
      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)`

    - #### write

          public void write(int b)
                     throws IOException

      Specified by:
        `write` in class `OutputStream`
      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

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

    - #### close

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

      Closes this OutputStream and releases any system resources associated with the stream. In contrast to `close()`, this method can provide statistical information. You can specify the output format for statistics, e.g. a plain list or XML.
      Parameters:
        `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()`

    - #### flush

          public void flush()
                     throws IOException

      Flushes this output stream and forces any buffered output bytes to be written out. Flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing. It does not guarantee that they are actually written to a physical device such as a disk drive.
      Specified by:
        `flush` in interface `Flushable`
      Overrides:
        `flush` in class `OutputStream`
      Throws:
        `IOException`

    - #### write

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

      Overrides:
        `write` in class `OutputStream`
      Throws:
        `IOException`

    - #### write

          public void write(byte[] b)
                     throws IOException

      Overrides:
        `write` in class `OutputStream`
      Throws:
        `IOException`