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

## Class TarFileInputStream

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

-     public class TarFileInputStream
      extends java.lang.Object

  Note that this class is not a java.io.FileInputStream, because our goal is to greatly restrict the public methods of FileInputStream, yet we must use public methods of the underlying FileInputStream 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 get the header and data blocks.

  Asymmetric to the Tar file writing side, the bufferBlocks setting here is used only for to adjust read buffer size (for file data reads), so the user can compromise between available memory and performance. Small buffer sizes will always work, but will incur more reads; on the other hand, buffer sizes larger than the largest component file is just a waste of memory.

  We assume the responsibility to manage the setting because the decision should be based on available RAM more than anything else (therefore, we can't set a good value automatically).

  As alluded to above, headers are read in separate reads, regardless of the readBufferBlocks setting. readBufferBlocks is used for reading file data.

  I have purposefully not implemented skip(), because, though I haven't tested it, I believe our readBlock() and readBlocks() methods are at least as fast, since we use the larges read buffer within limits the user has set.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TarFileInputStream​(java.io.File sourceFile)` | Convenience wrapper to use default readBufferBlocks and compressionType.
    `TarFileInputStream​(java.io.File sourceFile, int compressionType)` | Convenience wrapper to use default readBufferBlocks.
    `TarFileInputStream​(java.io.File sourceFile, int compressionType, int readBufferBlocks)` | 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` | `close()` | Implements java.io.Closeable.
    `int` | `getReadBufferBlocks()` |
    `void` | `readBlock()` | readBlock() and readNextHeaderBlock are the methods that USERS of this class should use to read header blocks from the tar file.
    `void` | `readBlocks​(int blocks)` | readBlocks(int) is the method that USERS of this class should use to read file data from the tar file.
    `boolean` | `readNextHeaderBlock()` | readBlock() and readNextHeaderBlock are the methods that USERS of this class should use to read header blocks from the tar file.

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

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

- - ### Constructor Detail

    - #### TarFileInputStream

          public TarFileInputStream​(java.io.File sourceFile)
                             throws java.io.IOException

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

    - #### TarFileInputStream

          public TarFileInputStream​(java.io.File sourceFile,
                                    int compressionType)
                             throws java.io.IOException

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

    - #### TarFileInputStream

          public TarFileInputStream​(java.io.File sourceFile,
                                    int compressionType,
                                    int readBufferBlocks)
                             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).

      This object will automatically release its I/O resources when you get false back from a readNextHeaderBlock() call. If you abort before then, you must call the close() method like for a normal InputStream.

      Parameters:
        `sourceFile` - File
        `compressionType` - int
        `readBufferBlocks` - int
      Throws:
        `java.io.IOException` - on failure
      See Also:
        `close()`, `readNextHeaderBlock()`

  - ### Method Detail

    - #### getReadBufferBlocks

          public int getReadBufferBlocks()

    - #### readBlocks

          public void readBlocks​(int blocks)
                          throws java.io.IOException,
                                 TarMalformatException

      readBlocks(int) is the method that USERS of this class should use to read file data from the tar file. This method reads from the tar file and writes to the readBuffer array.

      This class and subclasses should read from the underlying readStream ONLY WITH THIS METHOD. That way we can be confident that bytesRead will always be accurate.

      This method is different from a typical Java byte array read command in that when reading tar files

      1. we always know ahead-of-time how many bytes we should read, and
      2. we always want to read quantities of bytes in multiples of 512.
      Parameters:
        `blocks` - How many 512 blocks to read.
      Throws:
        `java.io.IOException` - for an I/O error on the underlying InputStream
        `TarMalformatException` - if no I/O error occurred, but we failed to read the exact number of bytes requested.

    - #### readBlock

          public void readBlock()
                         throws java.io.IOException,
                                TarMalformatException

      readBlock() and readNextHeaderBlock are the methods that USERS of this class should use to read header blocks from the tar file.

      readBlock() should be used when you know that the current block should contain what you want. E.g. you know that the very first block of a tar file should contain a Tar Entry header block.

      Throws:
        `java.io.IOException` - on access failure
        `TarMalformatException` - if malformed
      See Also:
        `readNextHeaderBlock()`

    - #### readNextHeaderBlock

          public boolean readNextHeaderBlock()
                                      throws java.io.IOException,
                                             TarMalformatException

      readBlock() and readNextHeaderBlock are the methods that USERS of this class should use to read header blocks from the tar file.

      readNextHeaderBlock continues working through the Tar File from the current point until it finds a block with a non-0 first byte.

      Returns:
        True if a header block was read and place at beginning of the readBuffer array. False if EOF was encountered without finding any blocks with first byte != 0. If false is returned, we have automatically closed the this TarFileInputStream too.
      Throws:
        `java.io.IOException` - on access failure
        `TarMalformatException` - if malformed
      See Also:
        `readBlock()`

    - #### close

          public void close()
                     throws java.io.IOException

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