Module org.hsqldb

Class 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()
    • 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()