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 -
Field Summary
Fields -
Constructor Summary
ConstructorsConstructorDescriptionTarFileOutputStream
(File targetFile) 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 TypeMethodDescriptionvoid
int
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
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.
-
Field Details
-
debug
public static final boolean debug -
writeBuffer
public byte[] writeBuffer
-
-
Constructor Details
-
TarFileOutputStream
Convenience wrapper to use default blocksPerRecord and compressionType.- Parameters:
targetFile
- File- Throws:
IOException
- on failure- See Also:
-
TarFileOutputStream
Convenience wrapper to use default blocksPerRecord.- Parameters:
targetFile
- FilecompressionType
- 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
- FilecompressionType
- intblocksPerRecord
- int- Throws:
IOException
- on failure
-
-
Method Details
-
write
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
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
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
Writes the specified quantity of zero'd blocks.- Parameters:
blockCount
- int- Throws:
IOException
- on failure
-
writePadBlock
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
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
Implements java.io.Flushable.- Throws:
IOException
- on failure- See Also:
-
close
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
(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:
-