Module org.hsqldb
Package org.hsqldb.lib.tar

## Class TarFileOutputStream

- java.lang.Object
- - org.hsqldb.lib.tar.TarFileOutputStream

-     public class TarFileOutputStream
      extends java.lang.Object

  Note that this class is not a java.io.FileOutputStream, because our goal is to greatly restrict the public methods of FileOutputStream, yet we must use public methods of the underlying FileOutputStream internally. Can't accomplish these goals in Java if we subclass.

  This class is ignorant about Tar header fields, attributes and such. It is concerned with reading and writing blocks of data in conformance with Tar formatting, in a way convenient to those who want to write the header and data blocks.

  Users write file data by means of populating the provided, public byte array, then calling the single write(int) method to write a portion of that array. This design purposefully goes with efficiency, simplicity, and performance over Java convention, which would not use public fields.

  At this time, we do not support appending. That would greatly decrease the generality and simplicity of the our design, since appending is trivial without compression and very difficult with compression.

  Users must finish tar file creation by using the finish() method. Just like a normal OutputStream, if processing is aborted for any reason, the close() method must be used to free up system resources.

  SECURITY NOTE Due to pitiful lack of support for file security in Java before version 1.6, this class will only explicitly set permissions if it is compiled for Java 1.6. If it was not, and if your tar entries contain private data in files with 0400 or similar, be aware that that file can be pretty much be extracted by anybody with access to the tar file.

  See Also:
    `finish()`, `close()`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `TarFileOutputStream.Compression` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static boolean` | `debug` |
    `byte[]` | `writeBuffer` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TarFileOutputStream​(java.io.File targetFile)` | Convenience wrapper to use default blocksPerRecord and compressionType.
    `TarFileOutputStream​(java.io.File targetFile, int compressionType)` | Convenience wrapper to use default blocksPerRecord.
    `TarFileOutputStream​(java.io.File targetFile, int compressionType, int blocksPerRecord)` | This class does no validation or enforcement of file naming conventions.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `assertAtBlockBoundary()` |
    `int` | `bytesLeftInBlock()` |
    `void` | `close()` | Implements java.io.Closeable.
    `void` | `finish()` | (Only) when this method returns successfully, the generated file will be a valid tar file.
    `void` | `flush()` | Implements java.io.Flushable.
    `long` | `getBytesWritten()` |
    `void` | `padCurrentBlock()` | Rounds out the current block to the next block boundary.
    `void` | `write​(byte[] byteArray, int byteCount)` | This class and subclasses should write to the underlying writeStream ONLY WITH THIS METHOD.
    `void` | `write​(int byteCount)` | The normal way to write file data (as opposed to header data or padding) using this class.
    `void` | `writeBlock​(byte[] block)` | Write a user-specified 512-byte block.
    `void` | `writePadBlock()` | Writes a single zero'd block.
    `void` | `writePadBlocks​(int blockCount)` | Writes the specified quantity of zero'd blocks.

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

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

- - ### Field Detail

    - #### debug

          public static final boolean debug

    - #### writeBuffer

          public byte[] writeBuffer

  - ### Constructor Detail

    - #### TarFileOutputStream

          public TarFileOutputStream​(java.io.File targetFile)
                              throws java.io.IOException

      Convenience wrapper to use default blocksPerRecord and compressionType.
      Parameters:
        `targetFile` - File
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `TarFileOutputStream(File, int, int)`

    - #### TarFileOutputStream

          public TarFileOutputStream​(java.io.File targetFile,
                                     int compressionType)
                              throws java.io.IOException

      Convenience wrapper to use default blocksPerRecord.
      Parameters:
        `targetFile` - File
        `compressionType` - int
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `TarFileOutputStream(File, int, int)`

    - #### TarFileOutputStream

          public TarFileOutputStream​(java.io.File targetFile,
                                     int compressionType,
                                     int blocksPerRecord)
                              throws java.io.IOException

      This class does no validation or enforcement of file naming conventions. If desired, the caller should enforce extensions like "tar" and "tar.gz" (and that they match the specified compression type). It also overwrites files without warning (just like FileOutputStream).
      Parameters:
        `targetFile` - File
        `compressionType` - int
        `blocksPerRecord` - int
      Throws:
        `java.io.IOException` - on failure

  - ### Method Detail

    - #### write

          public void write​(byte[] byteArray,
                            int byteCount)
                     throws java.io.IOException

      This class and subclasses should write to the underlying writeStream ONLY WITH THIS METHOD. That way we can be confident that bytesWritten will always be accurate.
      Parameters:
        `byteArray` - byte[]
        `byteCount` - int
      Throws:
        `java.io.IOException` - on failure

    - #### write

          public void write​(int byteCount)
                     throws java.io.IOException

      The normal way to write file data (as opposed to header data or padding) using this class.
      Parameters:
        `byteCount` - int
      Throws:
        `java.io.IOException` - on failure

    - #### writeBlock

          public void writeBlock​(byte[] block)
                          throws java.io.IOException

      Write a user-specified 512-byte block. For efficiency, write(int) should be used when writing file body content.
      Parameters:
        `block` - byte[]
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `write(int)`

    - #### writePadBlocks

          public void writePadBlocks​(int blockCount)
                              throws java.io.IOException

      Writes the specified quantity of zero'd blocks.
      Parameters:
        `blockCount` - int
      Throws:
        `java.io.IOException` - on failure

    - #### writePadBlock

          public void writePadBlock()
                             throws java.io.IOException

      Writes a single zero'd block.
      Throws:
        `java.io.IOException` - on failure

    - #### bytesLeftInBlock

          public int bytesLeftInBlock()

    - #### assertAtBlockBoundary

          public void assertAtBlockBoundary()

      Throws:
        `java.lang.IllegalStateException` - if end of file not on a block boundary.

    - #### padCurrentBlock

          public void padCurrentBlock()
                               throws java.io.IOException

      Rounds out the current block to the next block boundary. If we are currently at a block boundary, nothing is done.
      Throws:
        `java.io.IOException` - on failure

    - #### flush

          public void flush()
                     throws java.io.IOException

      Implements java.io.Flushable.
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `Flushable`

    - #### close

          public void close()
                     throws java.io.IOException

      Implements java.io.Closeable.

      IMPORTANT: This method deletes the work file after closing it!

      Throws:
        `java.io.IOException` - on failure
      See Also:
        `Closeable`

    - #### getBytesWritten

          public long getBytesWritten()

    - #### finish

          public void finish()
                      throws java.io.IOException

      (Only) when this method returns successfully, the generated file will be a valid tar file. This method always performs a close, so you never need to call the close if your code makes it to this method. (You do need to call close if processing is aborted before calling finish()).
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `close()`