Module org.hsqldb

Package org.hsqldb.lib.tar

Class TarFileOutputStream

java.lang.Object

org.hsqldb.lib.tar.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()

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	TarFileOutputStream.Compression

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

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