de.schlichtherle.io.archive.spi
Interface ArchiveDriver

All Known Implementing Classes:

AbstractArchiveDriver, AbstractSfxDriver, AbstractZip32RaesDriver, AbstractZipRaesDriver, CheckedJarDriver, CheckedOdfDriver, CheckedReadOnlySfxDriver, CheckedZip32Driver, CheckedZipDriver, JarDriver, OdfDriver, ParanoidZip32RaesDriver, ParanoidZipRaesDriver, ReadOnlySfxDriver, ReadWriteSfxDriver, SafeZip32RaesDriver, SafeZipRaesDriver, TarBZip2Driver, TarDriver, TarGZipDriver, UnsafeZip32RaesDriver, UnsafeZipRaesDriver, Zip32Driver, ZipDriver

public interface ArchiveDriver

This "driver" interface is used in a Builder software pattern as the Builder or Abstract Factory which reads and writes archives of a particular type, e.g. ZIP, TZP, JAR, TAR, TAR.GZ, TAR.BZ2 or any other. Archive drivers may be shared by multiple instances of ArchiveController and ArchiveDetector.

The following requirements must be met by any implementation:

• Implementations must be thread safe and (at least virtually) immutable: Otherwise, the class File may seem to behave non-deterministic and may even throw exceptions where it shouldn't.
• Implementations must not assume that they are used as singletons: Multiple instances of an implementation may be used for the same archive type.
• If the driver should be supported by the driver registration process of the class DefaultArchiveDetector, a no-arguments constructor must be provided.
• Although not required, since TrueZIP 6.4 it's recommended for implementations to implement the Serializable interface, too, so that File instances which are indirectly referring to it can be serialized.

Since:

TrueZIP 6.0

Version:

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

Author:

Christian Schlichtherle

Method Summary

ArchiveEntry	createArchiveEntry(Archive archive, String entryName, ArchiveEntry template) Creates a new archive entry for entryName for use with an OutputArchive.
InputArchive	createInputArchive(Archive archive, ReadOnlyFile rof) Creates a new input archive for archive from the given read only file.
OutputArchive	createOutputArchive(Archive archive, OutputStream out, InputArchive source) Creates a new output archive for archive from the given output stream.
boolean	equals(Object o) Archive drivers will be put into hash maps as keys, so be sure to implement this properly.
Icon	getClosedIcon(Archive archive) Returns the icon that FileSystemView and FileTreeCellRenderer should display for the given archive.
Icon	getOpenIcon(Archive archive) Returns the icon that FileTreeCellRenderer should display for the given archive.
int	hashCode() Archive drivers will be put into hash maps as keys, so be sure to implement this properly.

Method Detail

createInputArchive

InputArchive createInputArchive(Archive archive,
                                ReadOnlyFile rof)
                                throws IOException

Creates a new input archive for archive from the given read only file.

Note that if an exception is thrown, the method must be reentrant! In addition, the exception type determines the behaviour of the classes File, FileInputStream and FileOutputStream as follows:

Exception type	File.isFile()	File.isDirectory()	File.exists()	File.delete()
FileNotFoundException	false	false	true	true (unless prohibited by the real file system)
IOException	true	false	true	true (unless prohibited by the real file system)

Parameters:

archive - The abstract archive representation which TrueZIP's internal ArchiveController is processing - never null.

rof - The ReadOnlyFile to read the actual archive contents from - never null. Hint: If you'ld prefer to have an InputStream, you could decorate this parameter with a ReadOnlyFileInputStream.

Returns:

A new input archive instance.

Throws:

TransientIOException - If calling this method for the same archive file again may finally succeed. This exception is associated with another IOException as its cause which is unwrapped and interpreted as below.

FileNotFoundException - If the input archive is inaccessible for any reason and you would like the package de.schlichtherle.io to mask the archive as a special file which cannot get read, written or deleted.

IOException - On any other I/O or data format related issue when reading the input archive and you would like the package de.schlichtherle.io to treat the archive like a regular file which may be read, written or deleted.

See Also:

InputArchive

createArchiveEntry

ArchiveEntry createArchiveEntry(Archive archive,
                                String entryName,
                                ArchiveEntry template)
                                throws CharConversionException

Creates a new archive entry for entryName for use with an OutputArchive.

Parameters:

archive - The abstract archive representation which TrueZIP's internal ArchiveController is processing - never null.

entryName - A valid archive entry name - never null.

template - If not null, then the newly created entry shall inherit as much attributes from this object as possible (with the exception of the name). This is typically used for archive copy operations. Note that there is no guarantee on the runtime type of this object; it may have been created by other drivers. It is safe to ignore the metaData property when copying entries.

Returns:

A new archive entry instance.

Throws:

CharConversionException - If name contains illegal characters.

See Also:

Requirements for Archive Entry Names

createOutputArchive

OutputArchive createOutputArchive(Archive archive,
                                  OutputStream out,
                                  InputArchive source)
                                  throws IOException

Creates a new output archive for archive from the given output stream.

Parameters:

archive - The abstract archive representation which TrueZIP's internal ArchiveController is processing - never null.

out - The OutputStream to write the archive entries to - never null.

source - The source InputArchive if archive is going to get updated. If not null, this is guaranteed to be a product of this driver's createInputArchive(de.schlichtherle.io.archive.Archive, de.schlichtherle.io.rof.ReadOnlyFile) method. This may be used to copy some meta data which is specific to the type of archive this driver supports. For example, this could be used to copy the comment of a ZIP file.

Returns:

A new output archive instance.

Throws:

TransientIOException - If calling this method for the same archive file again may finally succeed. This exception is associated with another IOException as its cause which is unwrapped and interpreted as below.

FileNotFoundException - If the output archive is inaccessible for any reason.

IOException - On any other I/O or data format related issue when writing the output archive.

See Also:

OutputArchive

getOpenIcon

Icon getOpenIcon(Archive archive)

Returns the icon that FileTreeCellRenderer should display for the given archive.

Parameters:

archive - The abstract archive representation which TrueZIP's internal ArchiveController is processing - never null.

Returns:

The icon that should be displayed for the given archive if is is open/expanded in the view. If null is returned, a default icon should be used.

getClosedIcon

Icon getClosedIcon(Archive archive)

Returns the icon that FileSystemView and FileTreeCellRenderer should display for the given archive.

Parameters:

archive - The abstract archive representation which TrueZIP's internal ArchiveController is processing - never null.

Returns:

The icon that should be displayed for the given archive if is is closed/collapsed in the view. If null is returned, a default icon should be used.

equals

boolean equals(Object o)

Archive drivers will be put into hash maps as keys, so be sure to implement this properly. Note that this is just a reinforcement of the general contract for Object.equals(java.lang.Object) and the best possible implementation is the default implementation in Object which is most discriminating.

Overrides:

equals in class Object

Since:

TrueZIP 6.4

hashCode

int hashCode()

Archive drivers will be put into hash maps as keys, so be sure to implement this properly. Note that this is just a reinforcement of the general contract for Object.hashCode() and the best possible implementation is the default implementation in Object which is most discriminating.

Overrides:

hashCode in class Object

Since:

TrueZIP 6.4