de.schlichtherle.io.archive.tar
Class TarOutputArchive

java.lang.Object
  java.io.OutputStream
      java.io.FilterOutputStream
          org.apache.tools.tar.TarOutputStream
              de.schlichtherle.io.archive.tar.TarOutputArchive

All Implemented Interfaces:

OutputArchive, Closeable, Flushable

public class TarOutputArchive
extends org.apache.tools.tar.TarOutputStream
implements OutputArchive

An implementation of OutputArchive to write TAR archives.

Because the TAR file format needs to know each entry's length in advance, entries from an unknown source (such as entries created with FileOutputStream) are actually written to temp files and copied to the underlying TarOutputStream upon a call to their TarOutputArchive.EntryOutputStream.close() method. Note that this implies that the close() method may fail with an IOException.

Entries which's size is known in advance (such as entries copied with one of the (archiveC|c)opy(All)?(From|To) methods in the File class) are directly written to the underlying TarOutputStream instead.

This output archive can only write one entry at a time. Archive drivers may wrap this class in a MultiplexedOutputArchive to overcome this limitation.

Since:

TrueZIP 6.0

Version:

$Id: TarOutputArchive.java 06f3ba684701 2010/11/04 01:15:55 christian $

Author:

Christian Schlichtherle

Nested Class Summary

private class	TarOutputArchive.EntryOutputStream This entry output stream writes directly to our subclass.
private class	TarOutputArchive.TempEntryOutputStream This entry output stream writes the entry to a temporary file.

Field Summary

private boolean	busy
private Map	entries Maps entry names to tar entries [String -> TarEntry].
private OutputArchiveMetaData	metaData
private static String	TEMP_FILE_PREFIX Prefix for temporary files created by the multiplexer.

Fields inherited from class org.apache.tools.tar.TarOutputStream

assemBuf, assemLen, buffer, currBytes, currName, currSize, debug, LONGFILE_ERROR, LONGFILE_GNU, LONGFILE_TRUNCATE, longFileMode, oneBuf, recordBuf

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

TarOutputArchive(OutputStream out)

Method Summary

Enumeration	getArchiveEntries() Returns an enumeration of the ArchiveEntry instances in this archive (i.e. written so far).
ArchiveEntry	getArchiveEntry(String entryName) Returns the ArchiveEntry for the given entry name or null if no entry with this name has been written or started to be written.
OutputArchiveMetaData	getMetaData() Returns the meta data for this input archive.
int	getNumArchiveEntries() Returns the number of ArchiveEntry instances in this archive.
OutputStream	getOutputStream(ArchiveEntry entry, ArchiveEntry srcEntry) Returns a new OutputStream for writing the contents of the given archive entry.
private boolean	isBusy() Returns whether this output archive is busy writing an archive entry or not.
void	setMetaData(OutputArchiveMetaData metaData) Sets the meta data for this input archive.
void	storeDirectory(ArchiveEntry entry) Deprecated. This method will be removed in the next major version number release and should be implemented as getOutputStream(entry, null).close().
private void	storeTempEntry(TarEntry entry, File temp)

Methods inherited from class org.apache.tools.tar.TarOutputStream

close, closeEntry, finish, getRecordSize, putNextEntry, setBufferDebug, setDebug, setLongFileMode, write, write, write

Methods inherited from class java.io.FilterOutputStream

flush

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface de.schlichtherle.io.archive.spi.OutputArchive

close

Field Detail

TEMP_FILE_PREFIX

private static final String TEMP_FILE_PREFIX

Prefix for temporary files created by the multiplexer.

See Also:

Constant Field Values

entries

private final Map entries

Maps entry names to tar entries [String -> TarEntry].

metaData

private OutputArchiveMetaData metaData

busy

private boolean busy

Constructor Detail

TarOutputArchive

public TarOutputArchive(OutputStream out)

Method Detail

getNumArchiveEntries

public int getNumArchiveEntries()

Description copied from interface: OutputArchive

Returns the number of ArchiveEntry instances in this archive.

This method may be called before the archive is closed and must also reflect entries which have not yet been closed.

Specified by:

getNumArchiveEntries in interface OutputArchive

getArchiveEntries

public Enumeration getArchiveEntries()

Description copied from interface: OutputArchive

Returns an enumeration of the ArchiveEntry instances in this archive (i.e. written so far).

This method may be called before the archive is closed and must also reflect entries which have not yet been closed.

Specified by:

getArchiveEntries in interface OutputArchive

getArchiveEntry

public ArchiveEntry getArchiveEntry(String entryName)

Description copied from interface: OutputArchive

Returns the ArchiveEntry for the given entry name or null if no entry with this name has been written or started to be written.

This method may be called before the archive is closed and must also reflect entries which have not yet been closed.

Specified by:

getArchiveEntry in interface OutputArchive

Parameters:

entryName - A valid archive entry name - never null.

See Also:

Requirements for Archive Entry Names

getOutputStream

public OutputStream getOutputStream(ArchiveEntry entry,
                                    ArchiveEntry srcEntry)
                             throws IOException

Description copied from interface: OutputArchive

Returns a new OutputStream for writing the contents of the given archive entry.

The returned stream should preferrably be unbuffered, as buffering is usually done in higher layers (all copy routines in TrueZIP do this and most client applications do it, too). Buffering twice does not increase, but decrease performance.

Note that the stream is guaranteed to be closed before the OutputArchive.close() method of this archive is called!

Specified by:

getOutputStream in interface OutputArchive

Parameters:

entry - A valid reference to an archive entry. The runtime class of this entry is the same as the runtime class of the entries returned by ArchiveDriver.createArchiveEntry(de.schlichtherle.io.archive.Archive, java.lang.String, de.schlichtherle.io.archive.spi.ArchiveEntry).

srcEntry - If not null, this identifies the entry from which TrueZIP is actually copying data from and should be used to implement the Direct Data Copying (DDC) feature. Note that there is no guarantee on the runtime type of this object; it may have been created by other drivers. Furthermore, this not exclusively used for archive copies, so you should not simply copy all properties of the source entry to the entry (see ArchiveDriver.createArchiveEntry(Archive, String, ArchiveEntry) for comparison).

For example, the ZIP driver family uses this to copy the already deflated data if the source entry is another ZIP file entry. As another example, the TarDriver uses this to determine the size of the input file, thereby removing the need to create (yet another) temporary file.

Returns:

A (preferrably unbuffered) OutputStream to write the archive entry data to. null is not allowed!

Throws:

OutputArchiveBusyException - If the archive is currently busy on output for another entry. This exception is guaranteed to be recoverable, meaning it should be possible to write the same entry again as soon as the archive is not busy on output anymore.

FileNotFoundException - If the archive entry is not accessible for some reason.

IOException - On any other exceptional condition.

isBusy

private final boolean isBusy()

Returns whether this output archive is busy writing an archive entry or not.

storeTempEntry

private void storeTempEntry(TarEntry entry,
                            File temp)
                     throws IOException

Throws:

IOException

storeDirectory

public final void storeDirectory(ArchiveEntry entry)
                          throws IOException

Deprecated. This method will be removed in the next major version number release and should be implemented as getOutputStream(entry, null).close().

Description copied from interface: OutputArchive

Writes the given entry as a directory enry.

Specified by:

storeDirectory in interface OutputArchive

Parameters:

entry - The archive entry to write. This is never null and safe to be casted to the archive entry type actually created by the ArchiveDriver.createArchiveEntry(de.schlichtherle.io.archive.Archive, java.lang.String, de.schlichtherle.io.archive.spi.ArchiveEntry) method.

Throws:

IOException - On any exceptional condition.

getMetaData

public OutputArchiveMetaData getMetaData()

Description copied from interface: OutputArchive

Returns the meta data for this input archive. The default value is null.

Specified by:

getMetaData in interface OutputArchive

setMetaData

public void setMetaData(OutputArchiveMetaData metaData)

Description copied from interface: OutputArchive

Sets the meta data for this input archive.

Specified by:

setMetaData in interface OutputArchive

Parameters:

metaData - The meta data - may not be null.