net.java.truevfs.comp.zipdriver

Class AbstractZipDriver<E extends AbstractZipDriverEntry>

java.lang.Object

net.java.truecommons.shed.UniqueObject

net.java.truevfs.kernel.spec.FsDriver

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

net.java.truevfs.comp.zipdriver.AbstractZipDriver<E>

Type Parameters:

E - the type of the ZIP driver entries.

All Implemented Interfaces:

ZipCharsetParameters, ZipEntryFactory<E>, ZipFileParameters<E>, ZipOutputStreamParameters, ZipParameters, FsController.Factory<FsManager>, FsModel.Factory<FsManager>

Direct Known Subclasses:

JarDriver, ZipDriver

@Immutable
public abstract class AbstractZipDriver<E extends AbstractZipDriverEntry>
extends FsArchiveDriver<E>
implements ZipOutputStreamParameters, ZipFileParameters<E>

An abstract archive driver for the ZIP file format.

Sub-classes must be thread-safe and should be immutable!

Author:

Christian Schlichtherle

Constructor Summary

Constructors

Constructor and Description
AbstractZipDriver()

Method Summary

Modifier and Type	Method and Description
boolean	check(E local, ZipInputService<E> input) Whether or not the content of the given entry shall get checked/authenticated when reading it.
FsController	decorate(FsController controller) Decorates the given file system controller.
URI	fileSystemUri(FsModel model, String name) A template method for resolving the resource URI which is required to look up the KeyProvider for the entry with the given name in the file system with the given model.
net.java.truecommons.key.spec.KeyManagerMap	getKeyManagerMap() Returns the map of key managers for accessing protected resources (encryption).
int	getLevel() Returns the compression level for entries.
int	getMethod() Returns the default compression method for entries.
int	getOverheadSize() Returns the number of entries which can be additionally accomodated by the internal hash map without resizing it.
net.java.truecommons.cio.IoBufferPool	getPool() Returns the pool for allocating temporary I/O buffers.
boolean	getPostambled() Returns the flag for supporting postambles of arbitrary length.
boolean	getPreambled() Returns the flag for supporting preambles.
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.
URI	mountPointUri(FsModel model) A template method for resolving the resource URI which is required to look up the KeyProvider for the mount point of the file system with the given model.
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.
abstract E	newEntry(String name) Returns a new ZIP driver entry with the given name.
abstract E	newEntry(String name, ZipEntry template) Returns a new ZIP driver entry with the given name and all other properties copied from the given template.
protected ZipInputService<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.
protected 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.
protected ZipInputService<E>	newZipInput(FsModel model, FsInputSocketSource source)
protected boolean	rdc(AbstractZipDriverEntry input, AbstractZipDriverEntry output) Returns true if and only if the content of the given input target entry is eligible for Raw Data Copying (RDC).
protected FsOutputSocketSink	sink(net.java.truecommons.shed.BitField<FsAccessOption> options, FsController controller, FsNodeName name) This implementation modifies options in the following way before it forwards the call to controller: FsAccessOption.STORE is set.
protected ZipCryptoParameters	zipCryptoParameters(FsModel model, Charset charset) Returns the ZIP crypto parameters for the given file system model and character set or null if not available.

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

checkEncodable, getCharset, isArchiveDriver, newController, newEntry, newInput, newOutput, normalize, source, toString

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

Methods inherited from interface net.java.truevfs.comp.zip.ZipCharsetParameters

getCharset

Constructor Detail

AbstractZipDriver

public AbstractZipDriver()

Method Detail

check

public boolean check(E local,
                     @WillNotClose
                     ZipInputService<E> input)

Whether or not the content of the given entry shall get checked/authenticated when reading it. If this method returns true and the check fails, then an IOException gets thrown.

Parameters:

local - the entry to test.

input - the origin of the entry.

Returns:

entry.isEncrypted().

decorate

public FsController decorate(FsController controller)

Decorates the given file system controller.

The implementation in the class ZipDriver decorates the given controller with a package private controller which keeps track of the AES PBE parameters, e.g. the encryption passwords. This method should be overridden in order to return just controller if and only if you are overriding zipCryptoParameters(FsModel, Charset), too, and do not want to use a locatable key manager to resolve passwords for WinZip AES encryption.

Overrides:

decorate in class FsArchiveDriver<E extends AbstractZipDriverEntry>

Parameters:

controller - the file system controller to decorate.

Returns:

The implementation in the class FsArchiveDriver unconditionally returns controller.

fileSystemUri

public URI fileSystemUri(FsModel model,
                         String name)

A template method for resolving the resource URI which is required to look up the KeyProvider for the entry with the given name in the file system with the given model.

The implementation in the class ZipDriver ignores the given entry name and just returns the expression mountPointUri(model) in order to lookup the same key provider for all entries in a ZIP file.

An alternative implementation in a sub-class could return the expression mountPointUri(model).resolve("/" + name) instead.

Parameters:

model - the file system model.

name - the entry name.

Returns:

The URI for looking up a KeyProvider.

getKeyManagerMap

public net.java.truecommons.key.spec.KeyManagerMap getKeyManagerMap()

Returns the map of key managers for accessing protected resources (encryption).

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

Returns:

KeyManagerMapLocator.SINGLETON, as by the implementation in the class ZipDriver.

getLevel

public int getLevel()

Returns the compression level for entries. This property is only used if the effective compression method is ZipEntry.DEFLATED or ZipEntry.BZIP2. Legal values are Deflater.DEFAULT_COMPRESSION or range from Deflater#BEST_SPEED to Deflater#BEST_COMPRESSION.

The implementation in the class ZipDriver returns Deflater#BEST_COMPRESSION.

Specified by:

getLevel in interface ZipOutputStreamParameters

Returns:

Deflater#BEST_COMPRESSION

getMethod

public int getMethod()

Returns the default compression method for entries. This property is only used if a ZipEntry does not specify a compression method. Legal values are ZipEntry.STORED, ZipEntry.DEFLATED and ZipEntry.BZIP2.

The implementation in the class ZipDriver returns ZipEntry#DEFLATED.

Specified by:

getMethod in interface ZipOutputStreamParameters

Returns:

ZipEntry#DEFLATED

See Also:

ZipEntry.getMethod()

getOverheadSize

public int getOverheadSize()

Returns the number of entries which can be additionally accomodated by the internal hash map without resizing it. When a new ZIP file is created, this constant is used in order to compute the initial capacity of the internal hash map. When an existing ZIP file is appended to, this constant is added to the number of entries in order to compute the initial capacity of the internal hash map.

The implementation in the class ZipDriver returns Maps#OVERHEAD_SIZE.

Specified by:

getOverheadSize in interface ZipOutputStreamParameters

Returns:

Maps#OVERHEAD_SIZE

getPool

public 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.

The implementation in the class AbstractZipDriver returns IoBufferPoolLocator.SINGLETON.get().

Specified by:

getPool in class FsArchiveDriver<E extends AbstractZipDriverEntry>

Returns:

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

getPostambled

public boolean getPostambled()

Returns the flag for supporting postambles of arbitrary length. If this method returns true, then a ZIP file is allowed to contain arbitrary data of arbitrary length as its postamble after the actual ZIP file data. Note that searching for an arbitrary length postamble can seriously degrade the performance when reading a false positive ZIP file, i.e. an arbitrary file which is not compatible to the ZIP File Format Specification, because then the entire file needs to get searched for an End Of Central Directory Record (EOCDR) signature. A valid use case are self extracting ZIP files with very large postambles to host the extraction code.

If this method returns false, then a ZIP file may still have a postamble, but it must not exceed 64KB size, including the End Of Central Directory record with the ZIP file comment. This causes the reading of a false positive ZIP file to fail fast.

The implementation in the class ZipDriver returns false.

Specified by:

getPostambled in interface ZipFileParameters<E extends AbstractZipDriverEntry>

Returns:

false

getPreambled

public boolean getPreambled()

Returns the flag for supporting preambles. If this method returns true, then a ZIP file is allowed to contain arbitrary data as its preamble before the actual ZIP file data. Self Extracting Archives typically use a preamble to store the application code that is required to extract the ZIP file contents.

If this method returns false, then a ZIP file must start with either a Local File Header (LFH) signature, a ZIP64 End Of Central Directory Record (EOCDR) signature or an End Of Central Directory Record (EOCDR) signature.

The implementation in the class ZipDriver returns false.

Specified by:

getPreambled in interface ZipFileParameters<E extends AbstractZipDriverEntry>

Returns:

false

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.

Overrides:

getRedundantContentSupport in class FsArchiveDriver<E extends AbstractZipDriverEntry>

Returns:

The implementation in the class ZipDriver returns true because when reading a ZIP file sequentially, each ZIP entry should "override" any previously read ZIP entry with an equal name. This holds true even if the central directory is used to access the ZIP entries in random order.

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.

Overrides:

getRedundantMetaDataSupport in class FsArchiveDriver<E extends AbstractZipDriverEntry>

Returns:

The implementation in the class ZipDriver returns true because when reading a ZIP file sequentially, each ZIP entry should "override" any previously read ZIP entry with an equal name. This holds true even if the central directory is used to access the ZIP entries in random order.

mountPointUri

public URI mountPointUri(FsModel model)

A template method for resolving the resource URI which is required to look up the KeyProvider for the mount point of the file system with the given model.

The implementation in the class ZipDriver returns the expression model.getMountPoint().toHierarchicalUri() in order to improve the readability of the URI in comparison to the expression model.getMountPoint().getUri().

Parameters:

model - the file system model.

Returns:

The URI which represents the file system model's mount point.

See Also:

#TRUEZIP-72

newEntry

public 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)

Description copied from class: FsArchiveDriver

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.

Specified by:

newEntry in class FsArchiveDriver<E extends AbstractZipDriverEntry>

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:

FsArchiveDriver.newEntry(String, Entry.Type, Entry)

newEntry

public abstract E newEntry(String name)

Returns a new ZIP driver entry with the given name.

Specified by:

newEntry in interface ZipEntryFactory<E extends AbstractZipDriverEntry>

Parameters:

name - the entry name.

Returns:

A new abstract ZIP driver entry.

newEntry

public abstract E newEntry(String name,
                           ZipEntry template)

Returns a new ZIP driver entry with the given name and all other properties copied from the given template.

Parameters:

name - the entry name.

template - the template entry.

Returns:

A new ZIP driver entry.

newInput

protected final ZipInputService<E> newInput(FsModel model,
                                            FsInputSocketSource source)
                                     throws IOException

Description copied from class: FsArchiveDriver

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

Specified by:

newInput in class FsArchiveDriver<E extends AbstractZipDriverEntry>

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:

FsArchiveDriver.newInput(FsModel, BitField, FsController, FsNodeName)

newOutput

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

Description copied from class: FsArchiveDriver

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

Specified by:

newOutput in class FsArchiveDriver<E extends AbstractZipDriverEntry>

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 FsArchiveDriver.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:

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

newZipInput

@CreatesObligation
protected ZipInputService<E> newZipInput(FsModel model,
                                                            FsInputSocketSource source)
                                                     throws IOException

Throws:

IOException

rdc

protected boolean rdc(AbstractZipDriverEntry input,
                      AbstractZipDriverEntry output)

Returns true if and only if the content of the given input target entry is eligible for Raw Data Copying (RDC). This method gets called twice (once on each side of a copy operation) and should return false unless both target entries can mutually agree on transferring raw (unprocessed) content. Note that it is an error to compare the properties of the target entries because this method may get called before the output target entry gets mutated to compare equal with the input target entry!

The implementation in the class ZipDriver returns !local.isEncrypted() && !remote.isEncrypted() in order to cover the typical case that the cipher keys of both targets are not the same. Note that there is no safe way to explicitly test for this.

Parameters:

input - the input target entry for copying the contents.

output - the output target entry for copying the contents.

Returns:

Whether the content to get copied from the input target entry to the output target entry is eligible for Raw Data Copying (RDC).

sink

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

This implementation modifies options in the following way before it forwards the call to controller:

1. FsAccessOption.STORE is set.
2. If FsAccessOption.GROW is set, then FsAccessOption.APPEND gets set, too, and FsAccessOption.CACHE gets cleared.

The resulting output socket is then wrapped in a private nested class for an upcast in newOutput(net.java.truevfs.kernel.spec.FsModel, net.java.truevfs.kernel.spec.FsOutputSocketSink, net.java.truecommons.cio.InputService<E>). Thus, when overriding this method, newOutput(net.java.truevfs.kernel.spec.FsModel, net.java.truevfs.kernel.spec.FsOutputSocketSink, net.java.truecommons.cio.InputService<E>) should get overridden, too. Otherwise, a class cast exception will be thrown in newOutput(net.java.truevfs.kernel.spec.FsModel, net.java.truevfs.kernel.spec.FsOutputSocketSink, net.java.truecommons.cio.InputService<E>).

Overrides:

sink in class FsArchiveDriver<E extends AbstractZipDriverEntry>

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:

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

zipCryptoParameters

@CheckForNull
protected ZipCryptoParameters zipCryptoParameters(FsModel model,
                                                                Charset charset)

Returns the ZIP crypto parameters for the given file system model and character set or null if not available. To enable the use of this method when writing an archive entry with the client APIs, you must use FsAccessOption.ENCRYPT.

The implementation in the class ZipDriver returns new KeyManagerZipCryptoParameters(this, model, charset).

Parameters:

model - the file system model.

charset - charset the character set used for encoding entry names and the file comment in the ZIP file.

Returns:

The ZIP crypto parameters for the given file system model and character set or null if not available.