de.schlichtherle.io
Class ArchiveFileSystem

java.lang.Object
  de.schlichtherle.io.ArchiveFileSystem

All Implemented Interfaces:

Entry

final class ArchiveFileSystem
extends Object
implements Entry

This class implements a virtual file system of archive entries for use by the archive controller provided to the constructor.

WARNING:This class is not thread safe! All calls to non-static methods must be synchronized on the respective ArchiveController object!

Since:

TrueZIP 6.0 (refactored from the former ZipFileSystem)

Version:

$Id: ArchiveFileSystem.java c86df83eaddc 2011/01/19 13:52:55 christian $

Author:

Christian Schlichtherle

Nested Class Summary

private static class	ArchiveFileSystem.AbstractDelta
(package private) static class	ArchiveFileSystem.ArchiveFileSystemException This exception is thrown when a client application tries to perform an illegal operation on an archive file system.
(package private) static class	ArchiveFileSystem.ArchiveReadOnlyException This exception is thrown when a client tries to modify a read only virtual archive file system.
(package private) static interface	ArchiveFileSystem.Delta This interface encapsulates the methods required to begin and commit a simplified transaction (a delta) on this virtual archive file system.
private class	ArchiveFileSystem.LinkDelta A simple transaction for creating (and hence probably replacing) and linking an entry in this virtual archive file system.

Field Summary

private ArchiveFileSystemController	controller The controller that this filesystem belongs to.
private Map	master The map of ArchiveEntries in this file system.
private boolean	readOnly The read only status of this file system.
private ArchiveEntry	root The archive entry for the virtual root of this file system.
private static String	ROOT_DIRECTORY_NAME Denotes the entry name of the virtual root directory as a valid directory entry name.
private String[]	split For use by split only!
private long	touched The number of times this file system has been modified (touched).

Fields inherited from interface de.schlichtherle.io.Entry

ROOT_NAME, SEPARATOR, SEPARATOR_CHAR

Constructor Summary

ArchiveFileSystem(ArchiveFileSystemController controller)
Creates a new archive file system and ensures its integrity.

ArchiveFileSystem(ArchiveFileSystemController controller, InputArchive archive, long rootTime, boolean readOnly)
Mounts the archive file system from archive and ensures its integrity.

Method Summary

(package private) boolean	canWrite(String entryName)
private ArchiveEntry	createArchiveEntry(String entryName) Like createArchiveEntry(java.lang.String, de.schlichtherle.io.archive.spi.ArchiveEntry), but throws an AssertionError instead of CharConversionException.
private ArchiveEntry	createArchiveEntry(String entryName, ArchiveEntry blueprint) Creates an archive entry which is going to be linked into this virtual archive file system in the near future.
(package private) void	delete(String entryName)
(package private) boolean	exists(String entryName)
private void	fixParents(ArchiveEntry entry) Called from a constructor to fix the parent directories of entry, ensuring that all parent directories of the entry exist and that they contain the respective child.
private void	fixParents(String entryName)
(package private) ArchiveEntry	get(String entryName) Looks up the specified entry in the file system and returns it or null if not existent.
(package private) Enumeration	getArchiveEntries() Returns an enumeration of all ArchiveEntry instances in this file system.
(package private) Icon	getClosedIcon(String entryName)
private String	getEntryName(ArchiveEntry entry)
(package private) Icon	getOpenIcon(String entryName)
(package private) ArchiveEntry	getRoot() Returns the virtual root directory of this file system.
(package private) boolean	isDirectory(String entryName)
(package private) boolean	isFile(String entryName)
private static boolean	isLegalEntryName(String entryName) Checks whether the given entry entryName is a legal entry name.
(package private) boolean	isReadOnly() Indicates whether this file system is read only or not.
(package private) static boolean	isRoot(String entryName) Returns true iff the given entry name refers to the virtual root directory within this controller.
(package private) boolean	isTouched() Indicates whether this file system has been modified since its time of creation or the last call to resetTouched().
(package private) long	lastModified(String entryName)
(package private) long	length(String entryName)
(package private) ArchiveFileSystem.Delta	link(String entryName, boolean createParents) Equivalent to link(entryName, createParents, null).
(package private) ArchiveFileSystem.Delta	link(String entryName, boolean createParents, ArchiveEntry template) Begins a "create and link entry" transaction to ensure that either a new entry for the given entryName will be created or an existing entry is replaced within this virtual archive file system.
(package private) String[]	list(String entryName)
(package private) String[]	list(String entryName, FilenameFilter filenameFilter, File dir)
(package private) File[]	listFiles(String entryName, FileFilter fileFilter, File dir, FileFactory factory)
(package private) File[]	listFiles(String entryName, FilenameFilter filenameFilter, File dir, FileFactory factory)
(package private) void	mkdir(String entryName, boolean createParents)
(package private) boolean	setLastModified(String entryName, long time)
(package private) boolean	setReadOnly(String entryName)
private String[]	split(String entryName) Splits the given entry name in a parent entry name and a base name.
(package private) static String[]	split(String entryName, String[] result)
private void	touch() Ensures that the controller's data structures required to output entries are properly initialized and marks this virtual archive file system as touched.
private void	unlink(String entryName) If this method returns, the entry identified by the given entryName has been successfully deleted from the virtual archive file system.

Methods inherited from class java.lang.Object

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

Field Detail

ROOT_DIRECTORY_NAME

private static final String ROOT_DIRECTORY_NAME

Denotes the entry name of the virtual root directory as a valid directory entry name.

This constant cannot be used for identity comparison!

Since:

TrueZIP 6.5

See Also:

Constant Field Values

controller

private final ArchiveFileSystemController controller

The controller that this filesystem belongs to.

readOnly

private final boolean readOnly

The read only status of this file system.

master

private Map master

The map of ArchiveEntries in this file system. If this is a read-only file system, this is actually an unmodifiable map. This field should be considered final!

Note that the ArchiveEntries in this map are shared with the InputArchive object provided to this class' constructor.

root

private final ArchiveEntry root

The archive entry for the virtual root of this file system.

touched

private long touched

The number of times this file system has been modified (touched).

split

private final String[] split

For use by split only!

Constructor Detail

ArchiveFileSystem

ArchiveFileSystem(ArchiveFileSystemController controller)
            throws IOException

Creates a new archive file system and ensures its integrity. The root directory is created with its last modification time set to the system's current time. The file system is modifiable and marked as touched!

Parameters:

controller - The controller which will use this file system. This constructor will finally call ArchiveFileSystemController.touch() once it has fully initialized this instance.

Throws:

IOException

ArchiveFileSystem

ArchiveFileSystem(ArchiveFileSystemController controller,
                  InputArchive archive,
                  long rootTime,
                  boolean readOnly)

Mounts the archive file system from archive and ensures its integrity. First, a root directory with the given last modification time is created - it's never loaded from the archive! Then the entries from the archive are loaded into the file system and its integrity is checked: Any missing parent directories are created using the system's current time as their last modification time - existing directories will never be replaced.

Note that the entries in this file system are shared with archive.

Parameters:

controller - The controller which will use this file system. This constructor will solely use the controller as a factory to create missing archive entries using ArchiveFileSystemController.createArchiveEntry(java.lang.String, de.schlichtherle.io.archive.spi.ArchiveEntry).

archive - The archive to mount the file system from.

rootTime - The last modification time of the root of the mounted file system in milliseconds since the epoch.

readOnly - If and only if true, any subsequent modifying operation will result in a ArchiveFileSystem.ArchiveReadOnlyException.

Method Detail

getEntryName

private String getEntryName(ArchiveEntry entry)

isLegalEntryName

private static boolean isLegalEntryName(String entryName)

Checks whether the given entry entryName is a legal entry name. A legal entry name does not denote the virtual root directory, the dot directory (".") or the dot-dot directory ("..") or any of their descendants.

fixParents

private void fixParents(ArchiveEntry entry)

Called from a constructor to fix the parent directories of entry, ensuring that all parent directories of the entry exist and that they contain the respective child. If a parent directory does not exist, it is created using an unkown time as the last modification time - this is defined to be a ghost directory. If a parent directory does exist, the respective child is added (possibly yet again) and the process is continued.

fixParents

private void fixParents(String entryName)

split

private String[] split(String entryName)

Splits the given entry name in a parent entry name and a base name.

Parameters:

entryName - The name of the entry which's parent entry name and base name are to be returned.

Returns:

The split array, which will hold at least two strings:

• Index 0 holds the parent entry name. If entryName is empty or equals SEPARATOR, this is null. Otherwise, this contains the parent name of the entry and always ends with an SEPARATOR.
• Index 1 holds the base name. If entryName is empty or equals SEPARATOR, this is an empty string. Otherwise, this contains the base name of the entry and never contains an SEPARATOR.

Throws:

NullPointerException - If entryName is null.

split

static String[] split(String entryName,
                      String[] result)

isReadOnly

boolean isReadOnly()

Indicates whether this file system is read only or not. The default is false.

isTouched

boolean isTouched()

Indicates whether this file system has been modified since its time of creation or the last call to resetTouched().

touch

private void touch()
            throws IOException

Ensures that the controller's data structures required to output entries are properly initialized and marks this virtual archive file system as touched.

Throws:

ArchiveReadOnlyExceptionn - If this virtual archive file system is read only.

IOException - If setting up the required data structures in the controller fails for some reason.

getArchiveEntries

Enumeration getArchiveEntries()

Returns an enumeration of all ArchiveEntry instances in this file system.

getRoot

ArchiveEntry getRoot()

Returns the virtual root directory of this file system. This archive entry always exists. It's name may depend on the archive type. It's last modification time is guaranteed to be non-negative, so it's not a ghost directory!

isRoot

static boolean isRoot(String entryName)

Returns true iff the given entry name refers to the virtual root directory within this controller.

get

ArchiveEntry get(String entryName)

Looks up the specified entry in the file system and returns it or null if not existent.

link

ArchiveFileSystem.Delta link(String entryName,
                             boolean createParents)
                       throws ArchiveFileSystem.ArchiveFileSystemException

Equivalent to link(entryName, createParents, null).

Throws:

ArchiveFileSystem.ArchiveFileSystemException

link

ArchiveFileSystem.Delta link(String entryName,
                             boolean createParents,
                             ArchiveEntry template)
                       throws ArchiveFileSystem.ArchiveFileSystemException

Begins a "create and link entry" transaction to ensure that either a new entry for the given entryName will be created or an existing entry is replaced within this virtual archive file system.

This is the first step of a two-step process to create an archive entry and link it into this virtual archive file system. To commit the transaction, call ArchiveFileSystem.LinkDelta.commit() on the returned object after you have successfully conducted the operations which compose the transaction.

Upon a commit operation, the last modification time of the newly created and linked entries will be set to the system's current time at the moment the transaction has begun and the file system will be marked as touched at the moment the transaction has been committed.

Note that there is no rollback operation: After this method returns, nothing in the virtual file system has changed yet and all information required to commit the transaction is contained in the returned object. Hence, if the operations which compose the transaction fails, the returned object may be safely collected by the garbage collector,

Parameters:

entryName - The relative path name of the entry to create or replace.

createParents - If true, any non-existing parent directory will be created in this file system with its last modification time set to the system's current time.

template - If not null, then the newly created or replaced entry shall inherit as much properties from this instance as possible (with the exception of the name). This is typically used for archive copy operations and requires some support by the archive driver.

Returns:

A transaction object. You must call its ArchiveFileSystem.LinkDelta.commit() method in order to commit link the newly created entry into this virtual archive file system.

Throws:

ArchiveReadOnlyExceptionn - If this virtual archive file system is read only.

ArchiveFileSystem.ArchiveFileSystemException - If one of the following is true:

• entryName contains characters which are not supported by the archive file.
• The entry name indicates a directory (trailing /) and its entry does already exist within this file system.
• The entry is a file or directory and does already exist as the respective other type within this file system.
• The parent directory does not exist and createParents is false.
• One of the entry's parents denotes a file.

createArchiveEntry

private ArchiveEntry createArchiveEntry(String entryName,
                                        ArchiveEntry blueprint)
                                 throws CharConversionException

Creates an archive entry which is going to be linked into this virtual archive file system in the near future. The returned entry has properly initialized meta data, but is otherwise left as created by the archive driver.

Parameters:

entryName - The path name of the entry to create or replace. This must be a relative path name.

blueprint - 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 and requires some support by the archive driver.

Returns:

An ArchiveEntry created by the archive driver and properly initialized with meta data.

Throws:

CharConversionException - If entryName contains characters which are not supported by the archive file.

createArchiveEntry

private ArchiveEntry createArchiveEntry(String entryName)

Like createArchiveEntry(java.lang.String, de.schlichtherle.io.archive.spi.ArchiveEntry), but throws an AssertionError instead of CharConversionException.

Throws:

AssertionError - If a CharConversionException occurs.

unlink

private void unlink(String entryName)
             throws IOException

If this method returns, the entry identified by the given entryName has been successfully deleted from the virtual archive file system. If the entry is a directory, it must be empty for successful deletion.

Throws:

ArchiveReadOnlyExceptionn - If the virtual archive file system is read only.

ArchiveIllegalOperationException - If the operation failed for any other reason.

IOException

exists

boolean exists(String entryName)

isFile

boolean isFile(String entryName)

isDirectory

boolean isDirectory(String entryName)

getOpenIcon

Icon getOpenIcon(String entryName)

getClosedIcon

Icon getClosedIcon(String entryName)

canWrite

boolean canWrite(String entryName)

setReadOnly

boolean setReadOnly(String entryName)

length

long length(String entryName)

lastModified

long lastModified(String entryName)

setLastModified

boolean setLastModified(String entryName,
                        long time)
                  throws IOException

Throws:

IOException

list

String[] list(String entryName)

list

String[] list(String entryName,
              FilenameFilter filenameFilter,
              File dir)

listFiles

File[] listFiles(String entryName,
                 FilenameFilter filenameFilter,
                 File dir,
                 FileFactory factory)

listFiles

File[] listFiles(String entryName,
                 FileFilter fileFilter,
                 File dir,
                 FileFactory factory)

mkdir

void mkdir(String entryName,
           boolean createParents)
     throws IOException

Throws:

IOException

delete

void delete(String entryName)
      throws IOException

Throws:

IOException