FsArchiveFileSystem (TrueZIP Kernel 7.4.1 API)

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

Type Parameters:
E - The type of the archive entries.

All Implemented Interfaces:

Iterable<FsCovariantEntry<E>>

Direct Known Subclasses:

FsReadOnlyArchiveFileSystem
```
@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public class FsArchiveFileSystem<E extends FsArchiveEntry>
extends Object
implements Iterable<FsCovariantEntry<E>>
```
A read/write virtual file system for archive entries. Have a look at the online FAQ to get the concept of how this works.

Author:

Christian Schlichtherle

See Also:
Frequently Asked Questions

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`FsArchiveFileSystem.EntryTable<E extends FsArchiveEntry>`
`private class`	`FsArchiveFileSystem.PathLink` TODO: This implementation yields a potential issue: The state of the file system may be altered between the construction of an instance and the call to the `FsArchiveFileSystem.PathLink.run()` method, which may render the operation illegal and corrupt the file system.
`private static class`	`FsArchiveFileSystem.SegmentLink<E extends FsArchiveEntry>` A data class which represents a segment for use by `FsArchiveFileSystem.PathLink`.
`private static class`	`FsArchiveFileSystem.Splitter` Splits a given path name into its parent path name and base name.

Field Summary

Fields
Modifier and Type	Field and Description
`private FsArchiveDriver<E>`	`factory`
`private FsArchiveFileSystem.EntryTable<E>`	`master`
`static int`	`OVERHEAD_SIZE` The number of entries which can be additionally accomodated by the internal hash map without resizing it, which is 64.
`private static String`	`ROOT_PATH`
`private FsArchiveFileSystem.Splitter`	`splitter`
`private boolean`	`touched` Whether or not this file system has been modified (touched).
`private Set<FsArchiveFileSystemTouchListener<? super E>>`	`touchListeners`

Constructor Summary

Constructors
Modifier	Constructor and Description
`private`	`FsArchiveFileSystem(FsArchiveDriver<E> driver)`
`(package private)`	`FsArchiveFileSystem(FsArchiveDriver<E> driver, EntryContainer<E> archive, Entry rootTemplate)`

Method Summary

Methods
Modifier and Type	Method and Description
`(package private) void`	`addFsArchiveFileSystemTouchListener(FsArchiveFileSystemTouchListener<? super E> listener)` Adds the given listener to the set of archive file system listeners.
`private void`	`fix(String name)` Called from a constructor to fix the parent directories of the file system entry identified by `name`, ensuring that all parent directories of the file system entry exist and that they contain the respective base.
`(package private) FsCovariantEntry<E>`	`getEntry(FsEntryName name)` Returns a covariant file system entry or `null` if no file system entry exists for the given name.
`(package private) Set<FsArchiveFileSystemTouchListener<? super E>>`	`getFsArchiveFileSystemTouchListeners()` Returns a protective copy of the set of archive file system listeners.
`(package private) int`	`getSize()`
`(package private) boolean`	`isReadOnly()` Returns `true` if and only if this archive file system is read-only.
`(package private) boolean`	`isWritable(FsEntryName name)`
`Iterator<FsCovariantEntry<E>>`	`iterator()`
`(package private) FsArchiveFileSystemOperation<E>`	`mknod(FsEntryName name, Entry.Type type, BitField<FsOutputOption> options, Entry template)` 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.
`(package private) static <E extends FsArchiveEntry> FsArchiveFileSystem<E>`	`newEmptyFileSystem(FsArchiveDriver<E> driver)` Returns a new empty archive file system and ensures its integrity.
`private E`	`newEntryChecked(String name, Entry.Type type, BitField<FsOutputOption> mknod, Entry template)` Returns a new archive entry.
`private E`	`newEntryUnchecked(String name, Entry.Type type, BitField<FsOutputOption> mknod, Entry template)` Like `newEntryChecked(path, type, null)`, but wraps any `CharConversionException` in an `AssertionError`.
`(package private) static <E extends FsArchiveEntry> FsArchiveFileSystem<E>`	`newPopulatedFileSystem(FsArchiveDriver<E> driver, EntryContainer<E> archive, Entry rootTemplate, boolean readOnly)` Returns a new archive file system which populates its entries from the given `archive` and ensures its integrity.
`(package private) void`	`removeFsArchiveFileSystemTouchListener(FsArchiveFileSystemTouchListener<? super E> listener)` Removes the given listener from the set of archive file system listeners.
`(package private) void`	`setReadOnly(FsEntryName name)`
`(package private) boolean`	`setTime(FsEntryName name, BitField<Entry.Access> types, long value)`
`(package private) boolean`	`setTime(FsEntryName name, Map<Entry.Access,Long> times)`
`private void`	`touch()` Marks this (virtual) archive file system as touched and notifies the listener if and only if the touch status is changing.
`(package private) void`	`unlink(FsEntryName name)` If this method returns, the file system entry identified by the given `path` has been successfully deleted from this archive file system.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - factory
```
private final FsArchiveDriver<E extends FsArchiveEntry> factory
```
  - master
```
private final FsArchiveFileSystem.EntryTable<E extends FsArchiveEntry> master
```
  - OVERHEAD_SIZE
```
public static final int OVERHEAD_SIZE
```
    The number of entries which can be additionally accomodated by the internal hash map without resizing it, which is 64. When a new file system is created, this constant is used in order to compute the initial capacity of the internal hash map. When an existing file system is mounted, this constant is added to the number of entries in order to compute the initial capacity of the internal hash map.
    
    Since:
    
    TrueZIP 7.3
    
    See Also:
    Constant Field Values
  - ROOT_PATH
```
private static final String ROOT_PATH
```
  - splitter
```
private final FsArchiveFileSystem.Splitter splitter
```
  - touched
```
private boolean touched
```
    Whether or not this file system has been modified (touched).
  - touchListeners
```
private Set<FsArchiveFileSystemTouchListener<? super E extends FsArchiveEntry>> touchListeners
```
- Constructor Detail
  - FsArchiveFileSystem
```
private FsArchiveFileSystem(FsArchiveDriver<E> driver)
```
  - FsArchiveFileSystem
```
FsArchiveFileSystem(FsArchiveDriver<E> driver,
                   EntryContainer<E> archive,
                   @CheckForNull
                   Entry rootTemplate)
```
- Method Detail
  - addFsArchiveFileSystemTouchListener
```
final void addFsArchiveFileSystemTouchListener(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.
  - fix
```
private void fix(String name)
```
    Called from a constructor to fix the parent directories of the file system entry identified by name, ensuring that all parent directories of the file system entry exist and that they contain the respective base. 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 base is added (possibly yet again) and the process is continued.
    
    Parameters:
    name - the archive file system entry name.
  getEntry
  
  @Nullable final FsCovariantEntry<E> getEntry(FsEntryName name)
  
  Returns a covariant file system entry or null if no file system entry exists for the given name. Modifying the returned object graph is either not supported (i.e. throws an UnsupportedOperationException) or does not show any effect on this file system.
  
  Parameters:
  name - the name of the file system entry to look up.
  
  Returns:
  A covariant file system entry or null if no file system entry exists for the given name.
  
  getFsArchiveFileSystemTouchListeners
  
  Set<FsArchiveFileSystemTouchListener<? super E>> getFsArchiveFileSystemTouchListeners()
  
  Returns a protective copy of the set of archive file system listeners.
  
  Returns:
  A clone of the set of archive file system listeners.
  
  getSize
  
  int getSize()
  
  isReadOnly
  
  boolean isReadOnly()
  
  Returns true if and only if this archive file system is read-only.
  The implementation in the class FsArchiveFileSystem always returns false.
  
  Returns:
  Whether or not the this archive file system is read-only.
  
  isWritable
  
  boolean isWritable(FsEntryName name)
  
  iterator
  
  public Iterator<FsCovariantEntry<E>> iterator()
  
  Specified by:
  
  iterator in interface Iterable<FsCovariantEntry<E extends FsArchiveEntry>>
  
  mknod
  
  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 - the archive file system entry name.
  type - the type of the archive file system entry to create.
  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.
  
  newEmptyFileSystem
  
  static <E extends FsArchiveEntry> FsArchiveFileSystem<E> newEmptyFileSystem(FsArchiveDriver<E> driver)
  
  Returns a new empty archive file system and ensures its integrity. Only 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!
  
  Type Parameters:
  E - The type of the archive entries.
  Parameters:
  driver - the archive driver to use.
  
  Returns:
  A new archive file system.
  
  Throws:
  
  NullPointerException - If factory is null.
  
  newEntryChecked
  
  private E newEntryChecked(String name, Entry.Type type, BitField<FsOutputOption> mknod, @CheckForNull Entry template) throws FsArchiveFileSystemException
  
  Returns a new archive entry. This is only a factory method, i.e. the returned file system entry is not yet linked into this (virtual) archive file system.
  
  Parameters:
  name - the archive entry name.
  type - the type of the archive entry to create.
  template - the nullable template for the archive entry to create.
  
  Returns:
  A new archive entry.
  
  Throws:
  
  FsArchiveFileSystemException - if a CharConversionException occurs as its cause.
  See Also:
  mknod(de.schlichtherle.truezip.fs.FsEntryName, de.schlichtherle.truezip.entry.Entry.Type, de.schlichtherle.truezip.util.BitField<de.schlichtherle.truezip.fs.FsOutputOption>, de.schlichtherle.truezip.entry.Entry)
  
  newEntryUnchecked
  
  private E newEntryUnchecked(String name, Entry.Type type, BitField<FsOutputOption> mknod, @CheckForNull Entry template)
  
  Like newEntryChecked(path, type, null), but wraps any CharConversionException in an AssertionError.
  
  Parameters:
  name - the archive entry name.
  type - the type of the archive entry to create.
  template - the nullable template for the archive entry to create.
  
  Returns:
  A new archive entry.
  
  newPopulatedFileSystem
  
  static <E extends FsArchiveEntry> FsArchiveFileSystem<E> newPopulatedFileSystem(FsArchiveDriver<E> driver, 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.
  
  Type Parameters:
  E - The type of the archive entries.
  Parameters:
  driver - the archive driver to use.
  archive - The archive entry container to read the entries for the population of the archive file system.
  rootTemplate - The nullable template to use for the root entry of the returned archive file system. This must not be an instance of FsCovariantEntry.
  readOnly - If and only if true, any subsequent modifying operation on the file system will result in a FsReadOnlyArchiveFileSystemException.
  
  Returns:
  A new archive file system.
  
  Throws:
  
  NullPointerException - If factory or archive are null.
  
  removeFsArchiveFileSystemTouchListener
  
  final void removeFsArchiveFileSystemTouchListener(@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.
  
  setReadOnly
  
  void setReadOnly(FsEntryName name) throws FsArchiveFileSystemException
  
  Throws:
  
  FsArchiveFileSystemException
  
  setTime
  
  boolean setTime(FsEntryName name, BitField<Entry.Access> types, long value) throws FsArchiveFileSystemException
  
  Throws:
  
  FsArchiveFileSystemException
  
  setTime
  
  boolean setTime(FsEntryName name, Map<Entry.Access,Long> times) throws FsArchiveFileSystemException
  
  Throws:
  
  FsArchiveFileSystemException
  
  touch
  
  private void touch() throws FsArchiveFileSystemException
  
  Marks this (virtual) archive file system as touched and notifies the listener if and only if the touch status is changing.
  
  Throws:
  
  FsReadOnlyArchiveFileSystemException - If this (virtual) archive file system is read only.
  
  FsArchiveFileSystemException - If the listener vetoed the beforeTouch operation for any reason.
  
  unlink
  
  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.
  
  Parameters:
  name - the archive file system entry name.
  
  Throws:
  
  FsReadOnlyArchiveFileSystemException - If this (virtual) archive file system is read-only.
  
  FsArchiveFileSystemException - If the operation fails for some other reason.

Class FsArchiveFileSystem<E extends FsArchiveEntry>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

factory

master

OVERHEAD_SIZE

ROOT_PATH

splitter

touched

touchListeners

Constructor Detail

FsArchiveFileSystem

FsArchiveFileSystem

Method Detail

addFsArchiveFileSystemTouchListener

fix

getEntry

getFsArchiveFileSystemTouchListeners

getSize

isReadOnly

isWritable

iterator

mknod

newEmptyFileSystem

newEntryChecked

newEntryUnchecked

newPopulatedFileSystem

removeFsArchiveFileSystemTouchListener

setReadOnly

setTime

setTime

touch

unlink