com.mucommander.file.archiver
Class Archiver

java.lang.Object
  com.mucommander.file.archiver.Archiver

public abstract class Archiver
extends java.lang.Object

Archiver is an abstract class that represents a generic file archiver and abstracts the underlying compression method and specifics of the format.

Subclasses implement specific archive formats (Zip, Tar...) but cannot be instanciated directly. Instead, the getArchiver methods can be used to retrieve an Archiver instance for a specified archive format. A list of available archive formats can be dynamically retrieved using getFormats.

Archive formats fall into 2 categories:

• Single entry formats: Formats that can only store one entry without any directory structure, e.g. Gzip or Bzip2.
• Many entries formats: Formats that can store multiple entries along with a directory structure, e.g. Zip or Tar.

Author:

Maxence Bernard

Field Summary

static int	BZ2_FORMAT Bzip2 archive format (single entry format)
protected int	format Archive format of this Archiver
protected java.lang.String	formatName Archive format's name of this Archiver
static int	GZ_FORMAT Gzip archive format (single entry format)
protected java.io.OutputStream	out The underlying stream this archiver is writing to
static int	TAR_BZ2_FORMAT Tar archive compressed with Bzip2 format (many entries format)
static int	TAR_FORMAT Tar archive format without any compression (many entries format)
static int	TAR_GZ_FORMAT Tar archive compressed with Gzip format (many entries format)
static int	ZIP_FORMAT Zip archive format (many entries format)

Method Summary

abstract void	close() Closes the underlying OuputStream and ressources used by this Archiver to write the archive.
protected static java.io.OutputStream	createBzip2OutputStream(java.io.OutputStream out) Creates and returns a Bzip2 OutputStream using the given OutputStream as the underlying stream.
abstract java.io.OutputStream	createEntry(java.lang.String entryPath, AbstractFile file) Creates a new entry in the archive with the given path.
static boolean	formatSupportsComment(int format) Returns true if the specified archive format can store an optional comment.
static boolean	formatSupportsManyFiles(int format) Returns true if the specified archive format supports storage of more than one entry.
static Archiver	getArchiver(AbstractFile file, int format) Returns an Archiver for the specified format and that uses the given AbstractFile to write entries to.
static Archiver	getArchiver(java.io.OutputStream out, int format) Returns an Archiver for the specified format and that uses the given OutputStream to write entries to.
int	getFormat() Returns the archiver format used by this Archiver.
static java.lang.String	getFormatExtension(int format) Returns the default archive format extension.
java.lang.String	getFormatName() Returns the name of the archive format used by this Archiver.
static java.lang.String	getFormatName(int format) Returns the name of the given archive format.
static int[]	getFormats(boolean manyEntries) Returns an array of available archive formats, single entry formats or many entries formats depending on the value of the specified boolean parameter.
java.io.OutputStream	getOutputStream() Returns the OutputStream this Archiver is writing to.
protected java.lang.String	normalizePath(java.lang.String entryPath, boolean isDirectory) Normalizes the entry path, that is : replace any \ character occurrence by / as this usually is the default separator for archive files if the entry is a directory, add a trailing slash to the path if it doesn't have one already
void	setComment(java.lang.String comment) Sets an optional comment in the archive, the supportsComment() or formatSupportsComment(int) must first be called to make sure the archive format supports comment, otherwise calling this method will have no effect.
boolean	supportsComment() Returns true if the format used by this Archiver can store an optional comment.
boolean	supportsManyFiles() Returns true if the format used by this Archiver can store more than one entry.

Methods inherited from class java.lang.Object

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

Field Detail

ZIP_FORMAT

public static final int ZIP_FORMAT

Zip archive format (many entries format)

See Also:

Constant Field Values

GZ_FORMAT

public static final int GZ_FORMAT

Gzip archive format (single entry format)

See Also:

Constant Field Values

BZ2_FORMAT

public static final int BZ2_FORMAT

Bzip2 archive format (single entry format)

See Also:

Constant Field Values

TAR_FORMAT

public static final int TAR_FORMAT

Tar archive format without any compression (many entries format)

See Also:

Constant Field Values

TAR_GZ_FORMAT

public static final int TAR_GZ_FORMAT

Tar archive compressed with Gzip format (many entries format)

See Also:

Constant Field Values

TAR_BZ2_FORMAT

public static final int TAR_BZ2_FORMAT

Tar archive compressed with Bzip2 format (many entries format)

See Also:

Constant Field Values

out

protected java.io.OutputStream out

The underlying stream this archiver is writing to

format

protected int format

Archive format of this Archiver

formatName

protected java.lang.String formatName

Archive format's name of this Archiver

Method Detail

getOutputStream

public java.io.OutputStream getOutputStream()

Returns the OutputStream this Archiver is writing to.

Returns:

the OutputStream this Archiver is writing to

getFormat

public int getFormat()

Returns the archiver format used by this Archiver. See format constants.

getFormatName

public java.lang.String getFormatName()

Returns the name of the archive format used by this Archiver.

supportsManyFiles

public boolean supportsManyFiles()

Returns true if the format used by this Archiver can store more than one entry.

supportsComment

public boolean supportsComment()

Returns true if the format used by this Archiver can store an optional comment.

setComment

public void setComment(java.lang.String comment)

Sets an optional comment in the archive, the supportsComment() or formatSupportsComment(int) must first be called to make sure the archive format supports comment, otherwise calling this method will have no effect.

Implementation note: Archiver implementations must override this method to handle comments

Parameters:

comment - the comment to be stored in the archive

normalizePath

protected java.lang.String normalizePath(java.lang.String entryPath,
                                         boolean isDirectory)

Normalizes the entry path, that is :

• replace any \ character occurrence by / as this usually is the default separator for archive files
• if the entry is a directory, add a trailing slash to the path if it doesn't have one already

getArchiver

public static Archiver getArchiver(AbstractFile file,
                                   int format)
                            throws java.io.IOException

Returns an Archiver for the specified format and that uses the given AbstractFile to write entries to. null is returned if the specified format is not valid.

This method will first attempt to get a RandomAccessOutputStream if the given file is able to supply one, and if not, fall back to a regular OutputStream. Note that if the file exists, its contents will be overwritten. Write bufferring is used under the hood to improve performance.

Parameters:

file - the AbstractFile which the returned Archiver will write entries to

format - an archive format

Returns:

an Archiver for the specified format and that uses the given AbstractFile to write entries to ; null if the specified format is not valid.

Throws:

java.io.IOException - if the file cannot be opened for write, or if an error occurred while intializing the archiver

getArchiver

public static Archiver getArchiver(java.io.OutputStream out,
                                   int format)
                            throws java.io.IOException

Returns an Archiver for the specified format and that uses the given OutputStream to write entries to. null is returned if the specified format is not valid. Whenever possible, a RandomAccessOutputStream should be supplied as some formats take advantage of having a random write access.

Parameters:

out - the OutputStream which the returned Archiver will write entries to

format - an archive format

Returns:

an Archiver for the specified format and that uses the given AbstractFile to write entries to ; null if the specified format is not valid.

Throws:

java.io.IOException - if an error occurred while intializing the archiver

createBzip2OutputStream

protected static java.io.OutputStream createBzip2OutputStream(java.io.OutputStream out)
                                                       throws java.io.IOException

Creates and returns a Bzip2 OutputStream using the given OutputStream as the underlying stream.

Parameters:

out - the underlying stream

Returns:

a Bzip2 OutputStream

Throws:

java.io.IOException - if an error occurred while initializing the Bzip2 OutputStream

getFormats

public static int[] getFormats(boolean manyEntries)

Returns an array of available archive formats, single entry formats or many entries formats depending on the value of the specified boolean parameter.

Parameters:

manyEntries - if true, a list of many entries formats (a subset of single entry formats) will be returned

getFormatName

public static java.lang.String getFormatName(int format)

Returns the name of the given archive format. The returned name can be used for display in a GUI.

Parameters:

format - an archive format

getFormatExtension

public static java.lang.String getFormatExtension(int format)

Returns the default archive format extension. Note: some formats such as Tar/Gzip have several common extensions (e.g. tar.gz or tgz), the most common one will be returned.

Parameters:

format - an archive format

formatSupportsManyFiles

public static boolean formatSupportsManyFiles(int format)

Returns true if the specified archive format supports storage of more than one entry.

Parameters:

format - an archive format

formatSupportsComment

public static boolean formatSupportsComment(int format)

Returns true if the specified archive format can store an optional comment.

Parameters:

format - an archive format

createEntry

public abstract java.io.OutputStream createEntry(java.lang.String entryPath,
                                                 AbstractFile file)
                                          throws java.io.IOException

Creates a new entry in the archive with the given path. The specified file is used to determine whether the entry is a directory or a regular file, and to set the entry's size, permissions and date.

If the entry is a regular file (not a directory), an OutputStream which can be used to write the contents of the entry will be returned, null otherwise. The OutputStream must not be closed once it has been used (Archiver takes care of this), only the close method has to be called when all entries have been created.

If this Archiver uses a single entry format, the specified path and file won't be used at all. Also in this case, this method must be invoked only once (single entry), it will throw an IOException if invoked more than once.

Parameters:

entryPath - the path to be used to create the entry in the archive. This parameter is simply ignored if the archive is a single entry format.

file - AbstractFile instance used to determine if the entry is a directory, and to set the entry's date. This parameter is simply ignored if the archive is a single entry format.

Throws:

java.io.IOException - if this Archiver failed to write the entry, or in the case of a single entry archiver, if this method was called more than once.

close

public abstract void close()
                    throws java.io.IOException

Closes the underlying OuputStream and ressources used by this Archiver to write the archive. This method must be called when all entries have been added to the archive.

Throws:

java.io.IOException