de.schlichtherle.truezip.fs.archive
Class FsArchiveFileSystem<E extends FsArchiveEntry>

java.lang.Object
  de.schlichtherle.truezip.fs.archive.FsArchiveFileSystem<E>

Type Parameters:

E - The type of the archive entries.

All Implemented Interfaces:

EntryContainer<FsArchiveFileSystemEntry<E>>, Iterable<FsArchiveFileSystemEntry<E>>

Direct Known Subclasses:

FsReadOnlyArchiveFileSystem

@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
 class FsArchiveFileSystem<E extends FsArchiveEntry>
extends Object
implements EntryContainer<FsArchiveFileSystemEntry<E>>

A base class for a virtual file system for archive entries.

Author:

Christian Schlichtherle

factory

private final EntryFactory<E extends FsArchiveEntry> factory

master

private final Map<String,FsArchiveFileSystemEntry<E extends FsArchiveEntry>> master

The map of archive file system entries.

Note that the archive entries in this map are shared with the EntryContainer object provided to the constructor of this class.

root

private final FsArchiveFileSystemEntry<E extends FsArchiveEntry> root

The file system entry for the (virtual) root of this file system.

touched

private boolean touched

Whether or not this file system has been modified (touched).

touchListeners

private LinkedHashSet<FsArchiveFileSystemTouchListener<? super E extends FsArchiveEntry>> touchListeners

FsArchiveFileSystem

private FsArchiveFileSystem(EntryFactory<E> factory)

FsArchiveFileSystem

FsArchiveFileSystem(EntryFactory<E> factory,
                    EntryContainer<E> archive,
                    @CheckForNull
                    Entry rootTemplate)

newArchiveFileSystem

static <AE extends FsArchiveEntry> FsArchiveFileSystem<AE> newArchiveFileSystem(EntryFactory<AE> factory)

Returns 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:

factory - the archive entry factory to use.

Throws:

NullPointerException - If factory is null.

newArchiveFileSystem

static <E extends FsArchiveEntry> FsArchiveFileSystem<E> newArchiveFileSystem(EntryFactory<E> factory,
                                                                              EntryContainer<E> archive,
                                                                              @CheckForNull
                                                                              Entry rootTemplate,
                                                                              boolean readOnly)

Returns a new archive file system which populates its entries from the given archive and ensures its integrity.

First, the entries from the archive are loaded into the file system.

Second, a root directory with the given last modification time is created and linked into the filesystem (so it's never loaded from the archive).

Finally, the file system integrity is checked and fixed: 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 the file system are shared with the given archive entry container.

Parameters:

archive - The archive entry container to read the entries for the population of the archive file system.

factory - the archive entry factory to use.

rootTemplate - The last modification time of the root of the populated file system in milliseconds since the epoch.

readOnly - If and only if true, any subsequent modifying operation on the file system will result in a FsReadOnlyArchiveFileSystemException.

Throws:

NullPointerException - If container, factory or rootTemplate are null.

IllegalArgumentException - If rootTemplate is an instance of FsArchiveFileSystemEntry.

isReadOnly

public boolean isReadOnly()

Returns true if and only if this archive file system is read-only. This method is provided for inheritance - the implementation in this class always returns false.

isTouched

public boolean isTouched()

Returns true if and only if this archive file system has been modified since its time of creation.

touch

private void touch()
            throws FsArchiveFileSystemException

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.

FsArchiveFileSystemException - If the listener vetoed the beforeTouch operation for any reason.

getArchiveFileSystemTouchListeners

Set<FsArchiveFileSystemTouchListener<? super E>> getArchiveFileSystemTouchListeners()

Returns a protective copy of the set of archive file system listeners.

Returns:

A clone of the set of archive file system listeners.

addArchiveFileSystemTouchListener

public final void addArchiveFileSystemTouchListener(FsArchiveFileSystemTouchListener<? super E> listener)

Adds the given listener to the set of archive file system listeners.

Parameters:

listener - the listener for archive file system events.

removeArchiveFileSystemTouchListener

public final void removeArchiveFileSystemTouchListener(@Nullable
                                                       FsArchiveFileSystemTouchListener<? super E> listener)

Removes the given listener from the set of archive file system listeners.

Parameters:

listener - the listener for archive file system events.

getSize

public int getSize()

Description copied from interface: EntryContainer

Returns the number of entries in this container.

Specified by:

getSize in interface EntryContainer<FsArchiveFileSystemEntry<E extends FsArchiveEntry>>

iterator

public Iterator<FsArchiveFileSystemEntry<E>> iterator()

Description copied from interface: EntryContainer

Returns a new iterator over all entries in this container.

First, the iteration must be consistent: Multiple iterators must iterate the same entries in the same order again unless the set of entries has changed.

Next, the iteration should also reflect the natural order of the entries in this container. For example, if this container represents an archive file, the iteration should reflect the natural order of the entries in the archive file.

Specified by:

iterator in interface EntryContainer<FsArchiveFileSystemEntry<E extends FsArchiveEntry>>

Specified by:

iterator in interface Iterable<FsArchiveFileSystemEntry<E extends FsArchiveEntry>>

Returns:

A new non-null iterator over all entries in this container.

getEntry

@Nullable
public final FsArchiveFileSystemEntry<E> getEntry(FsEntryName name)

getEntry

@Nullable
public FsArchiveFileSystemEntry<E> getEntry(String path)

Description copied from interface: EntryContainer

Returns the entry for the given name or null if no entry with this name exists in this container.

Specified by:

getEntry in interface EntryContainer<FsArchiveFileSystemEntry<E extends FsArchiveEntry>>

Parameters:

path - an entry name.

Returns:

The entry for the given name or null if no entry with this name exists in this container.

newEntryUnchecked

private FsArchiveFileSystemEntry<E> newEntryUnchecked(String path,
                                                      Entry.Type type,
                                                      @CheckForNull
                                                      Entry template)

Like newEntryChecked(path, type, null), but wraps any CharConversionException in an AssertionError.

Throws:

AssertionError - if a CharConversionException occurs. The original exception is wrapped as its cause.

newEntryChecked

private FsArchiveFileSystemEntry<E> newEntryChecked(String path,
                                                    Entry.Type type,
                                                    @CheckForNull
                                                    Entry template)
                                                                    throws FsArchiveFileSystemException

Returns a new file system entry for this (virtual) archive file system. This is only a factory method, i.e. the returned file system entry is not yet linked into this (virtual) archive file system.

Parameters:

path - the path name of the archive file system entry.

Throws:

FsArchiveFileSystemException

See Also:

mknod(de.schlichtherle.truezip.fs.FsEntryName, de.schlichtherle.truezip.entry.Entry.Type, de.schlichtherle.truezip.util.BitField, de.schlichtherle.truezip.entry.Entry)

copy

final E copy(E entry)

mknod

public FsArchiveFileSystemOperation<E> mknod(FsEntryName name,
                                             Entry.Type type,
                                             BitField<FsOutputOption> options,
                                             @CheckForNull
                                             Entry template)
                                                             throws FsArchiveFileSystemException

Begins a transaction to create or replace and finally link a chain of one or more archive entries for the given path into this archive file system.

To commit the transaction, you need to call FsArchiveFileSystemOperation.run() on the returned object, which will mark this archive file system as touched and set the last modification time of the created and linked archive file system entries to the system's current time at the moment of the call to this method.

Parameters:

name - an entry name.

type - an entry type.

options - if CREATE_PARENTS is set, any missing parent directories will be created and linked into this file system with its last modification time set to the system's current time.

template - if not null, then the archive file system entry at the end of the chain shall inherit as much properties from this entry as possible - with the exception of its name and type.

Returns:

A new archive file system operation on a chain of one or more archive file system entries for the given path name which will be linked into this archive file system upon a call to its FsArchiveFileSystemOperation.run() method.

Throws:

NullPointerException - if path or type are null.

ArchiveReadOnlyExceptionn - If this archive file system is read only.

FsArchiveFileSystemException - If one of the following is true:

• The file system is read only.
• name contains characters which are not supported by the file system.
• TODO: type is not FILE or DIRECTORY.
• The entry already exists and either the option FsOutputOption.EXCLUSIVE is set or the entry is a directory.
• The entry exists as a different type.
• A parent entry exists but is not a directory.
• A parent entry is missing and createParents is false.

unlink

public void unlink(FsEntryName name)
            throws FsArchiveFileSystemException

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

Throws:

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

FsArchiveFileSystemException - If the operation fails for some other reason.

setTime

public boolean setTime(FsEntryName name,
                       BitField<Entry.Access> types,
                       long value)
                throws FsArchiveFileSystemException

Throws:

FsArchiveFileSystemException

isWritable

public boolean isWritable(FsEntryName name)

setReadOnly

public void setReadOnly(FsEntryName name)
                 throws FsArchiveFileSystemException

Throws:

FsArchiveFileSystemException