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

Class 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