net.java.truevfs.kernel.spec

Class FsArchiveDriver<E extends FsArchiveEntry>

java.lang.Object

net.java.truecommons.shed.UniqueObject

net.java.truevfs.kernel.spec.FsDriver

net.java.truevfs.kernel.spec.FsArchiveDriver<E>

Type Parameters:

E - the type of the archive entries.

All Implemented Interfaces:

FsController.Factory<FsManager>, FsModel.Factory<FsManager>

Direct Known Subclasses:

AbstractZipDriver, TarDriver

@Immutable
public abstract class FsArchiveDriver<E extends FsArchiveEntry>
extends FsDriver

An abstract factory for components required for accessing archive files. Implementations of this abstract base class are used to access specific archive formats like ZIP, TAR et al.

Subclasses should be immutable.

Author:

Christian Schlichtherle

Constructor Summary

Constructors

Constructor and Description
FsArchiveDriver()

Method Summary

Modifier and Type	Method and Description
void	checkEncodable(String name) Ensures that the given entry name can get encoded by this driver's character set.
FsController	decorate(FsController controller) Decorates the given file system controller.
abstract Charset	getCharset() Returns the character set to use for encoding character based meta data such as entry names or file comments to binary data when writing an archive file.
abstract net.java.truecommons.cio.IoBufferPool	getPool() Returns the pool for allocating temporary I/O buffers.
boolean	getRedundantContentSupport() Returns true if and only if the archive files produced by this archive driver may contain redundant archive entry contents.
boolean	getRedundantMetaDataSupport() Returns true if and only if the archive files produced by this archive driver may contain redundant archive entry meta data.
boolean	isArchiveDriver() Returns true if and only if this is an archive driver, that is, if file systems of this type must be a member of a parent file system.
FsController	newController(FsManager context, FsModel model, FsController parent) Returns a new file system controller for the mount point of the given file system model.
abstract E	newEntry(net.java.truecommons.shed.BitField<FsAccessOption> options, String name, net.java.truecommons.cio.Entry.Type type, net.java.truecommons.cio.Entry template) Returns a new entry for the given name.
E	newEntry(String name, net.java.truecommons.cio.Entry.Type type, net.java.truecommons.cio.Entry template) Equivalent to newEntry(FsAccessOptions.NONE, name, type, template).
net.java.truecommons.cio.InputService<E>	newInput(FsModel model, net.java.truecommons.shed.BitField<FsAccessOption> options, FsController controller, FsNodeName name) This method gets called by an archive controller in order to create a new input service for its target archive file.
protected abstract net.java.truecommons.cio.InputService<E>	newInput(FsModel model, FsInputSocketSource source) Creates a new input service for reading archive entries for the given model from the target archive file referenced by source.
net.java.truecommons.cio.OutputService<E>	newOutput(FsModel model, net.java.truecommons.shed.BitField<FsAccessOption> options, FsController controller, FsNodeName name, net.java.truecommons.cio.InputService<E> input) This method gets called by an archive controller in order to create a new output service for its target archive file.
protected abstract net.java.truecommons.cio.OutputService<E>	newOutput(FsModel model, FsOutputSocketSink sink, net.java.truecommons.cio.InputService<E> input) Creates a new input service for writing archive entries for the given model to the target archive file referenced by sink.
static String	normalize(String name, net.java.truecommons.cio.Entry.Type type) Normalizes the given entry name so that it forms a valid entry name for ZIP and TAR files by ensuring that the returned entry name ends with the separator character '/' if and only if type is DIRECTORY.
protected FsOutputSocketSink	sink(net.java.truecommons.shed.BitField<FsAccessOption> options, FsController controller, FsNodeName name) Called to prepare writing an archive file artifact of this driver to the node name in controller using options and the nullable template.
protected FsInputSocketSource	source(net.java.truecommons.shed.BitField<FsAccessOption> options, FsController controller, FsNodeName name) Called to prepare reading an archive file artifact of this driver from name in controller using options.
String	toString() Returns a string representation of this object for debugging and logging purposes.

Methods inherited from class net.java.truevfs.kernel.spec.FsDriver

decorate, newModel

Methods inherited from class net.java.truecommons.shed.UniqueObject

equals, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FsArchiveDriver

public FsArchiveDriver()

Method Detail

checkEncodable

public final void checkEncodable(String name)
                          throws CharConversionException

Ensures that the given entry name can get encoded by this driver's character set.

Parameters:

name - an entry name.

Throws:

CharConversionException - If the entry name contains characters which cannot get encoded.

decorate

public FsController decorate(FsController controller)

Decorates the given file system controller.

Parameters:

controller - the file system controller to decorate.

Returns:

The implementation in the class FsArchiveDriver unconditionally returns controller.

getCharset

public abstract Charset getCharset()

Returns the character set to use for encoding character based meta data such as entry names or file comments to binary data when writing an archive file. Depending on the archive file format, this may get used for decoding binary data when reading an archive file, too.

This is an immutable property - multiple calls must return the same object.

Returns:

The character set to use for encoding character based meta data such as entry names or file comments to binary data when writing an archive file.

getPool

public abstract net.java.truecommons.cio.IoBufferPool getPool()

Returns the pool for allocating temporary I/O buffers.

This is an immutable property - multiple calls must return the same object.

Returns:

The pool to use for allocating temporary I/O buffers.

getRedundantContentSupport

public boolean getRedundantContentSupport()

Returns true if and only if the archive files produced by this archive driver may contain redundant archive entry contents. If the return value is true, then an archive file may contain redundant archive entry contents, but only the last contents written should get used when reading the archive file.

This is an immutable property - multiple calls must return the same value.

The default value of this property is false as defined by the implementation in the class FsArchiveDriver.

Returns:

true if and only if the archive files produced by this archive driver may contain redundant archive entry contents.

getRedundantMetaDataSupport

public boolean getRedundantMetaDataSupport()

Returns true if and only if the archive files produced by this archive driver may contain redundant archive entry meta data. If the return value is true, then an archive file may contain redundant archive entry meta data, but only the last meta data written should get used when reading the archive file. This usually implies the existence of a central directory in the resulting archive file.

This is an immutable property - multiple calls must return the same value.

The default value of this property is false as defined by the implementation in the class FsArchiveDriver.

Returns:

true if and only if the archive files produced by this archive driver may contain redundant archive entry meta data.

isArchiveDriver

public final boolean isArchiveDriver()

Returns true if and only if this is an archive driver, that is, if file systems of this type must be a member of a parent file system.

Overrides:

isArchiveDriver in class FsDriver

Returns:

The implementation in the class FsArchiveDriver unconditionally returns true.

newController

public final FsController newController(FsManager context,
                                        FsModel model,
                                        @Nonnull
                                        FsController parent)

Returns a new file system controller for the mount point of the given file system model. This is a pure function without side effects.

When called, you may assert the following precondition:

 assert null == parent
         ? null == model.getParent()
         : parent.getModel().equals(model.getParent())
 

The implementation in the class FsArchiveDriver forwards the call to the given file system manager.

Parameters:

context - the calling context.

model - the file system model.

parent - the nullable parent file system controller.

Returns:

A new file system controller for the mount point of the given file system model.

newEntry

public abstract E newEntry(net.java.truecommons.shed.BitField<FsAccessOption> options,
                           String name,
                           net.java.truecommons.cio.Entry.Type type,
                           @CheckForNull
                           net.java.truecommons.cio.Entry template)

Returns a new entry for the given name. The implementation may change this name in order to form a valid entry name for their particular requirements.

Parameters:

options - when called from FsController.make(net.java.truecommons.shed.BitField<net.java.truevfs.kernel.spec.FsAccessOption>, net.java.truevfs.kernel.spec.FsNodeName, net.java.truecommons.cio.Entry.Type, net.java.truecommons.cio.Entry), this is its options parameter, otherwise it's typically an empty set.

name - the entry name.

type - the entry type.

template - if not null, then the new entry shall inherit as much properties from this entry as possible - with the exception of its name and type.

Returns:

A new entry for the given name.

See Also:

newEntry(String, Entry.Type, Entry)

newEntry

public final E newEntry(String name,
                        net.java.truecommons.cio.Entry.Type type,
                        @CheckForNull
                        net.java.truecommons.cio.Entry template)

Equivalent to newEntry(FsAccessOptions.NONE, name, type, template).

Parameters:

name - the entry name.

type - the entry type.

template - if not null, then the new entry shall inherit as much properties from this entry as possible - with the exception of its name and type.

Returns:

A new entry for the given name.

newInput

@CreatesObligation
public net.java.truecommons.cio.InputService<E> newInput(FsModel model,
                                                                            net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                            FsController controller,
                                                                            FsNodeName name)
                                                                     throws IOException

This method gets called by an archive controller in order to create a new input service for its target archive file.

The implementation in FsArchiveDriver simply forwards the call to source(net.java.truecommons.shed.BitField<net.java.truevfs.kernel.spec.FsAccessOption>, net.java.truevfs.kernel.spec.FsController, net.java.truevfs.kernel.spec.FsNodeName) and newInput(FsModel, FsInputSocketSource).

Parameters:

model - the file system model for the target archive file.

options - the options for accessing the target archive file in the parent file system.

controller - the controller for the parent file system with the target archive file.

name - the node name of the target archive file in the parent file system.

Returns:

A new input service for reading the target archive file. Note that this service does not need to be thread-safe!

Throws:

IOException - on any I/O error. If the file system node for the given model exists in the parent file system and is not a Entry.Type.SPECIAL type, then this exception is deemed to indicate a persistent false positive archive file and gets cached until the file system controller for the given model gets synced again. Otherwise, this exception is deemed to indicate a transient false positive archive file and does not get cached.

newInput

@CreatesObligation
protected abstract net.java.truecommons.cio.InputService<E> newInput(FsModel model,
                                                                                        FsInputSocketSource source)
                                                                                 throws IOException

Creates a new input service for reading archive entries for the given model from the target archive file referenced by source.

Parameters:

model - the file system model.

source - the source for reading the target archive file.

Returns:

A new input service. Note that this service does not need to be thread-safe!

Throws:

IOException - on any I/O error.

See Also:

newInput(FsModel, BitField, FsController, FsNodeName)

newOutput

@CreatesObligation
public net.java.truecommons.cio.OutputService<E> newOutput(FsModel model,
                                                                              net.java.truecommons.shed.BitField<FsAccessOption> options,
                                                                              FsController controller,
                                                                              FsNodeName name,
                                                                              @CheckForNull @WillNotClose
                                                                              net.java.truecommons.cio.InputService<E> input)
                                                                       throws IOException

This method gets called by an archive controller in order to create a new output service for its target archive file.

The implementation in FsArchiveDriver simply forwards the call to sink(net.java.truecommons.shed.BitField<net.java.truevfs.kernel.spec.FsAccessOption>, net.java.truevfs.kernel.spec.FsController, net.java.truevfs.kernel.spec.FsNodeName) and newOutput(FsModel, FsOutputSocketSink, InputService).

Parameters:

model - the file system model for the target archive file.

options - the options for accessing the target archive file in the parent file system.

controller - the controller for the parent file system with the target archive file.

name - the node name of the target archive file in the parent file system.

input - the nullable InputService for the target archive file. If not null, then the target archive file is going to get updated. This parameter is guaranteed to be the product of this driver's factory method newInput(FsModel, BitField, FsController, FsNodeName).

Returns:

A new output service for writing the target archive file. Note that this service does not need to be thread-safe!

Throws:

IOException - on any I/O error.

newOutput

@CreatesObligation
protected abstract net.java.truecommons.cio.OutputService<E> newOutput(FsModel model,
                                                                                          FsOutputSocketSink sink,
                                                                                          @CheckForNull @WillNotClose
                                                                                          net.java.truecommons.cio.InputService<E> input)
                                                                                   throws IOException

Creates a new input service for writing archive entries for the given model to the target archive file referenced by sink.

Parameters:

model - the file system model.

sink - the sink for writing the target archive file.

input - the nullable InputService for the target archive file. If not null, then the target archive file is going to get updated. This parameter is guaranteed to be the product of this driver's factory method newInput(FsModel, BitField, FsController, FsNodeName).

Returns:

A new output service for writing the target archive file. Note that this service does not need to be thread-safe!

Throws:

IOException - on any I/O error.

See Also:

newOutput(FsModel, BitField, FsController, FsNodeName, InputService)

normalize

public static String normalize(String name,
                               net.java.truecommons.cio.Entry.Type type)

Normalizes the given entry name so that it forms a valid entry name for ZIP and TAR files by ensuring that the returned entry name ends with the separator character '/' if and only if type is DIRECTORY.

Parameters:

name - an entry name.

type - an entry type.

Returns:

The normalized entry name.

sink

protected FsOutputSocketSink sink(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                  FsController controller,
                                  FsNodeName name)

Called to prepare writing an archive file artifact of this driver to the node name in controller using options and the nullable template.

This method is overridable to enable modifying the given options before forwarding the call to the given controller. The implementation in the class FsArchiveDriver simply forwards the call to the given controller with the given options unaltered.

Parameters:

options - the options for accessing the file system node.

controller - the controller to use for writing an artifact of this driver.

name - the node name.

Returns:

A sink for writing an artifact of this driver.

See Also:

newOutput(FsModel, BitField, FsController, FsNodeName, InputService)

source

protected FsInputSocketSource source(net.java.truecommons.shed.BitField<FsAccessOption> options,
                                     FsController controller,
                                     FsNodeName name)

Called to prepare reading an archive file artifact of this driver from name in controller using options.

This method is overridable to enable modifying the given options before forwarding the call to the given controller. The implementation in the class FsArchiveDriver simply forwards the call to the given controller with the given options unaltered.

Parameters:

options - the options for accessing the file system node.

controller - the controller to use for reading an artifact of this driver.

name - the node name.

Returns:

A source for reading an artifact of this driver.

See Also:

newInput(FsModel, BitField, FsController, FsNodeName)

toString

public String toString()

Returns a string representation of this object for debugging and logging purposes.

Overrides:

toString in class FsDriver