Module org.hsqldb

Class TarFileInputStream

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

public class TarFileInputStream extends 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
    Convenience wrapper to use default readBufferBlocks and compressionType.
    TarFileInputStream(File sourceFile, int compressionType)
    Convenience wrapper to use default readBufferBlocks.
    TarFileInputStream(File sourceFile, int compressionType, int readBufferBlocks)
    This class does no validation or enforcement of file naming conventions.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    Implements java.io.Closeable.
    int
     
    void
    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
    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 Details

    • TarFileInputStream

      public TarFileInputStream(File sourceFile) throws IOException
      Convenience wrapper to use default readBufferBlocks and compressionType.
      Parameters:
      sourceFile - File
      Throws:
      IOException - on failure
      See Also:
    • TarFileInputStream

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

      public TarFileInputStream(File sourceFile, int compressionType, int readBufferBlocks) throws 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:
      IOException - on failure
      See Also:
  • Method Details

    • getReadBufferBlocks

      public int getReadBufferBlocks()
    • readBlocks

      public void readBlocks(int blocks) throws 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:
      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 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:
      IOException - on access failure
      TarMalformatException - if malformed
      See Also:
    • readNextHeaderBlock

      public boolean readNextHeaderBlock() throws 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:
      IOException - on access failure
      TarMalformatException - if malformed
      See Also:
    • close

      public void close() throws IOException
      Implements java.io.Closeable.
      Throws:
      IOException - on failure
      See Also: