de.schlichtherle.io.archive.spi
Interface OutputArchive

All Known Implementing Classes:

CheckedZip32OutputArchive, MultiplexedOutputArchive, OdfOutputArchive, TarOutputArchive, Zip32OutputArchive, ZipOutputArchive

public interface OutputArchive

Defines the interface used to write entries to an archive file.

Implementations do not need to be thread safe: Multithreading is addressed in the package de.schlichtherle.io.

Since:

TrueZIP 6.0

Version:

$Id: OutputArchive.java,v 1.4 2010/08/20 13:09:48 christian_schlichtherle Exp $

Author:

Christian Schlichtherle

Method Summary

void	close() Closes this output archive and releases any system resources associated with it.
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.
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().

Method Detail

getNumArchiveEntries

int getNumArchiveEntries()

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.

getArchiveEntries

Enumeration getArchiveEntries()

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.

getArchiveEntry

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.

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

Parameters:

entryName - A valid archive entry name - never null.

See Also:

Requirements for Archive Entry Names

getOutputStream

OutputStream getOutputStream(ArchiveEntry entry,
                             ArchiveEntry srcEntry)
                             throws OutputArchiveBusyException,
                                    FileNotFoundException,
                                    IOException

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 close() method of this archive is called!

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.

storeDirectory

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

Writes the given entry as a directory enry.

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.

close

void close()
           throws IOException

Closes this output archive and releases any system resources associated with it.

Throws:

IOException - On any I/O related issue.

getMetaData

OutputArchiveMetaData getMetaData()

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

setMetaData

void setMetaData(OutputArchiveMetaData metaData)

Sets the meta data for this input archive.

Parameters:

metaData - The meta data - may not be null.