Module org.hsqldb

Class TarFileOutputStream

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

public class TarFileOutputStream extends 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:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
     
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final boolean
     
    byte[]
     
  • Constructor Summary

    Constructors
    Constructor
    Description
    Convenience wrapper to use default blocksPerRecord and compressionType.
    TarFileOutputStream(File targetFile, int compressionType)
    Convenience wrapper to use default blocksPerRecord.
    TarFileOutputStream(File targetFile, int compressionType, int blocksPerRecord)
    This class does no validation or enforcement of file naming conventions.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
     
    int
     
    void
    Implements java.io.Closeable.
    void
    (Only) when this method returns successfully, the generated file will be a valid tar file.
    void
    Implements java.io.Flushable.
    long
     
    void
    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
    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 Details

    • debug

      public static final boolean debug
    • writeBuffer

      public byte[] writeBuffer
  • Constructor Details

    • TarFileOutputStream

      public TarFileOutputStream(File targetFile) throws IOException
      Convenience wrapper to use default blocksPerRecord and compressionType.
      Parameters:
      targetFile - File
      Throws:
      IOException - on failure
      See Also:
    • TarFileOutputStream

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

      public TarFileOutputStream(File targetFile, int compressionType, int blocksPerRecord) 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). It also overwrites files without warning (just like FileOutputStream).
      Parameters:
      targetFile - File
      compressionType - int
      blocksPerRecord - int
      Throws:
      IOException - on failure
  • Method Details

    • write

      public void write(byte[] byteArray, int byteCount) throws 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:
      IOException - on failure
    • write

      public void write(int byteCount) throws IOException
      The normal way to write file data (as opposed to header data or padding) using this class.
      Parameters:
      byteCount - int
      Throws:
      IOException - on failure
    • writeBlock

      public void writeBlock(byte[] block) throws IOException
      Write a user-specified 512-byte block. For efficiency, write(int) should be used when writing file body content.
      Parameters:
      block - byte[]
      Throws:
      IOException - on failure
      See Also:
    • writePadBlocks

      public void writePadBlocks(int blockCount) throws IOException
      Writes the specified quantity of zero'd blocks.
      Parameters:
      blockCount - int
      Throws:
      IOException - on failure
    • writePadBlock

      public void writePadBlock() throws IOException
      Writes a single zero'd block.
      Throws:
      IOException - on failure
    • bytesLeftInBlock

      public int bytesLeftInBlock()
    • assertAtBlockBoundary

      public void assertAtBlockBoundary()
      Throws:
      IllegalStateException - if end of file not on a block boundary.
    • padCurrentBlock

      public void padCurrentBlock() throws IOException
      Rounds out the current block to the next block boundary. If we are currently at a block boundary, nothing is done.
      Throws:
      IOException - on failure
    • flush

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

      public void close() throws IOException
      Implements java.io.Closeable.

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

      Throws:
      IOException - on failure
      See Also:
    • getBytesWritten

      public long getBytesWritten()
    • finish

      public void finish() throws 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:
      IOException - on failure
      See Also: