org.at4j.archive.builder
Interface ArchiveBuilder<U extends ArchiveBuilder<U,V>,V extends ArchiveEntrySettings<V>>

Type Parameters:

U - The archive builder implementation.

V - The type of settings used for the archive builder implementation.

All Known Subinterfaces:

StreamAddCapableArchiveBuilder<U,V>

All Known Implementing Classes:

AbstractArchiveBuilder, AbstractStreamAddCapableArchiveBuilder, TarBuilder, TarStreamBuilder, ZipBuilder

public interface ArchiveBuilder<U extends ArchiveBuilder<U,V>,V extends ArchiveEntrySettings<V>>

This is a generic interface for an archive builder, i.e. an object used to build a file archive containing files and directories.

Files and directories, entries, are added used any of the add methods. Every entry has a unique AbsoluteLocation in the archive's directory hierarchy. If an entry is added at a location where an entry already exists, the previous entry is made invisible, but is still present in the archive.

The builder does not verify the directory hierarchy for added entries. The programs used to read archives usually cope well with missing parent directories of entries.

Every entry also has some metadata associated with it. Exactly what metadata that an entry has depends on the type of archive being built and on the effective ArchiveEntrySettings for the entry when it is added to the archive. The effective settings for an entry is determined thus:

1. Start with the default settings for the entry type. There are different default settings for file and directory entries. See getDefaultFileEntrySettings() and getDefaultDirectoryEntrySettings().
2. Evaluate all global entry settings rules ( ArchiveEntrySettingsRule):s to see if any rule applies to the entry being added. For all rules that apply, their settings are combined with the default settings using the ArchiveEntrySettings.combineWith(ArchiveEntrySettings) method. The rules are applied in the order that they occur in the archive builder's rules list.
3. Combine the resulting settings from the previous two steps with any specific settings supplied to the add method when adding the entry to the archive. The supplied settings are combined with the previous settings using the ArchiveEntrySettings.combineWith(ArchiveEntrySettings) method.

The effect of the algorithm above is that settings from global rules that apply to the entry being added, override the default settings for the entity type, and that specific settings supplied when adding the entry override default settings and settings from the global rules.

When the archive builder is created, it opens the supplied file for writing (or for random access). Entries are written to the archive as they are added. When the archive builder is close():d, it finishes writing the archive file and closes it. Most archive builder methods throw an IllegalStateException if they are called after closing the object.

Archive builders are not safe to use concurrently from several threads without external synchronization.

If the archive file is in a locking FileSystem, the archive builder object acquires a write lock on the file when the object is created. The close() method releases the write lock.

Since:

1.0

Author:

Karl Gustafsson

Method Summary

U	add(DirectoryView d) Add a directory entry to the archive's root directory.
U	add(DirectoryView d, AbsoluteLocation parentDirLocation) Add the directory entry to the specified parent directory in the archive.
U	add(DirectoryView d, AbsoluteLocation parentDirLocation, V settings) Add a directory entry to the specified parent directory in the archive.
U	add(File f) Add a file or directory entry to the archive's root directory.
U	add(File f, AbsoluteLocation parentDirLocation) Add a file or directory entry to the specified parent directory in the archive.
U	add(File f, AbsoluteLocation parentDirLocation, V settings) Add a file or directory entry to the specified parent directory in the archive.
U	add(NamedReadableFile f) Add a file entry to the archive's root directory.
U	add(NamedReadableFile f, AbsoluteLocation parentDirLocation) Add a file entry to the specified parent directory in the archive.
U	add(NamedReadableFile f, AbsoluteLocation parentDirLocation, V settings) Add a file entry to the specified parent directory in the archive.
U	addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation) Add the supplied directory recursively to the specified position in the archive.
U	addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation, Filter<? super EntityView> filter) Add the supplied directory recursively to the specified position in the archive.
U	addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation, Filter<? super EntityView> filter, ArchiveEntrySettingsRule<? extends V>... rules) Add the supplied directory recursively to the specified position in the archive.
U	addRecursively(File f, AbsoluteLocation rootDirLocation) Add the supplied file or directory recursively to the specified position in the archive.
U	addRecursively(File f, AbsoluteLocation rootDirLocation, ArchiveEntrySettingsRule<? extends V>... rules) Add the supplied file or directory recursively to the specified position in the archive.
U	addRule(ArchiveEntrySettingsRule<? extends V> rule) Append an entry settings rule to the end of the rule list.
U	addRules(Collection<? extends ArchiveEntrySettingsRule<? extends V>> rules) Append a list of entry settings rules to the end of the rule list.
void	close() Close this archive builder, finish the archive and release all of the resources associated with the archive builder.
V	getDefaultDirectoryEntrySettings() Get (a copy of) the default settings for the directory entries added to this archive builder.
V	getDefaultFileEntrySettings() Get (a copy of) the default settings for the file entries added to this archive builder.
List<ArchiveEntrySettingsRule<? extends V>>	getRules() Get a copy of the list of rules that are used to determine the entry settings for entries added to this archive.
boolean	isClosed() Is this archive builder closed?
boolean	removeRule(ArchiveEntrySettingsRule<? extends V> rule) Remove an entry settings rule from the rule list.
U	setDefaultDirectoryEntrySettings(V s) Set the default settings for directory entries that are added to the archive from now on.
U	setDefaultFileEntrySettings(V s) Set the default settings for file entries that are added to the archive from now on.

Method Detail

setDefaultFileEntrySettings

U setDefaultFileEntrySettings(V s)
                                                          throws IllegalStateException

Set the default settings for file entries that are added to the archive from now on.

The supplied object is combined with the default default file entry settings object using the ArchiveEntrySettings.combineWith(ArchiveEntrySettings) method. This means that the client does not have to specify values for the properties where the default values should be used.

The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Parameters:

s - The new default file entry settings.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

setDefaultDirectoryEntrySettings(ArchiveEntrySettings)

getDefaultFileEntrySettings

V getDefaultFileEntrySettings()
                                                              throws IllegalStateException

Get (a copy of) the default settings for the file entries added to this archive builder.

The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Returns:

The default settings used for file entries added to the archive builder.

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

getDefaultDirectoryEntrySettings(), setDefaultFileEntrySettings(ArchiveEntrySettings)

setDefaultDirectoryEntrySettings

U setDefaultDirectoryEntrySettings(V s)
                                                               throws IllegalStateException

Set the default settings for directory entries that are added to the archive from now on.

The supplied object is combined with the default default directory entry settings object using the ArchiveEntrySettings.combineWith(ArchiveEntrySettings) method. This means that the client does not have to specify values for the properties where the default values should be used.

The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Parameters:

s - The new default directory entry settings.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

setDefaultFileEntrySettings(ArchiveEntrySettings)

getDefaultDirectoryEntrySettings

V getDefaultDirectoryEntrySettings()
                                                                   throws IllegalStateException

Get (a copy of) the default settings for the directory entries added to this archive builder.

The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Returns:

The default settings used for directory entries added to the archive builder

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

getDefaultFileEntrySettings(), setDefaultDirectoryEntrySettings(ArchiveEntrySettings)

addRule

U addRule(ArchiveEntrySettingsRule<? extends V> rule)
                                      throws IllegalStateException

Append an entry settings rule to the end of the rule list. This rule will be used for entries added to the archive after this method has been called.

The rule list is used when determining the settings that an entry added to the archive should have. The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Parameters:

rule - The rule to append to the end of the rule list.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

addRules(Collection), removeRule(ArchiveEntrySettingsRule), getRules()

addRules

U addRules(Collection<? extends ArchiveEntrySettingsRule<? extends V>> rules)
                                       throws IllegalStateException

Append a list of entry settings rules to the end of the rule list. The rules are appended in the order that they are returned when iterating over the supplied collection.

The rules will be used for entries added to the archive after this method has been called.

The rule list is used when determining the settings that an entry added to the archive should have. The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Parameters:

rules - The rules to append to the end of the rule list.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

addRule(ArchiveEntrySettingsRule), removeRule(ArchiveEntrySettingsRule), getRules()

removeRule

boolean removeRule(ArchiveEntrySettingsRule<? extends V> rule)
                   throws IllegalStateException

Remove an entry settings rule from the rule list. This rule will not be used for the entries added to the archive after this method has been called.

The rule list is used when determining the settings that an entry added to the archive should have. The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Parameters:

rule - The rule to remove from the list.

Returns:

true if a rule was removed from the list, false if not. If no rule was removed from the list, that means that the supplied rule was not present in the list to begin with.

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

addRule(ArchiveEntrySettingsRule), getRules()

getRules

List<ArchiveEntrySettingsRule<? extends V>> getRules()
                                                                                     throws IllegalStateException

Get a copy of the list of rules that are used to determine the entry settings for entries added to this archive.

The actual settings that are used for entries that are added to the archive is determined using the algorithm described in the interface documentation above.

Returns:

A copy of the list of rules that are used to determine the entry settings for entries added to this archive.

Throws:

IllegalStateException - If the archive builder is closed.

See Also:

addRule(ArchiveEntrySettingsRule), removeRule(ArchiveEntrySettingsRule)

add

U add(NamedReadableFile f)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add a file entry to the archive's root directory. The file is added with the default file settings, combined with settings from the global rules that apply to the file, if any.

If the file is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the added file entry will be the name of the added file. If you want another name, use a NamedReadableFileAdapter.

Parameters:

f - The file to add to the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the file cannot be added, for some reason other than an I/O error.

add

U add(NamedReadableFile f,
      AbsoluteLocation parentDirLocation)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add a file entry to the specified parent directory in the archive. The file is added with the default file settings, combined with settings from the global rules that apply to the file, if any.

If the file is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the added file entry will be the name of the added file. If you want another name, use a NamedReadableFileAdapter.

Parameters:

f - The file to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the file cannot be added, for some reason other than an I/O error.

add

U add(NamedReadableFile f,
      AbsoluteLocation parentDirLocation,
      V settings)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add a file entry to the specified parent directory in the archive. The supplied settings is combined with the default file settings and the settings from the global rules that apply to the file, if any.

If the file is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the added file entry will be the name of the added file. If you want another name, use a NamedReadableFileAdapter.

Parameters:

f - The file to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

settings - The custom settings to use for this file. The custom settings are combined with the default settings and global rule settings as described above. If this is set to null, only the default file settings combined with settings from the global rules that apply to this file are used.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the file cannot be added, for some reason other than an I/O error.

add

U add(DirectoryView d)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add a directory entry to the archive's root directory. The directory is added with the default directory settings, combined with settings from the global rules that apply to the directory, if any.

If the directory is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the directory entry will be the name of the added directory.

Parameters:

d - The directory to add to the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the directory cannot be added, for some reason other than an I/O error.

add

U add(DirectoryView d,
      AbsoluteLocation parentDirLocation)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add the directory entry to the specified parent directory in the archive. The directory is added with the default directory settings, combined with settings from the global rules that apply to the directory, if any.

If the directory is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the directory entry will be the name of the added directory.

Parameters:

d - The directory to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the directory cannot be added, for some reason other than an I/O error.

add

U add(DirectoryView d,
      AbsoluteLocation parentDirLocation,
      V settings)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         ArchiveEntryAddException

Add a directory entry to the specified parent directory in the archive. The supplied settings is combined with the default directory settings and the settings from the global rules that apply to the directory, if any.

If the directory is in a locking FileSystem, it is temporarily locked for reading by this method.

The name of the directory entry will be the name of the added directory.

Parameters:

d - The directory to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

settings - The custom settings to use for this directory. The custom settings are combined with the default settings and global rule settings as described above. If this is set to null, only the default directory settings combined with settings from the global rules that apply to this directory are used.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If the directory cannot be added, for some reason other than an I/O error.

add

U add(File f)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         EntityNotFoundException,
                                         ArchiveEntryAddException

Add a file or directory entry to the archive's root directory. The entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, if any.

The name of the file entry will be the name of the added file. If you want another name for the entry, wrap the file in a FileReadableFile and then in a NamedReadableFileAdapter.

Parameters:

f - The file or directory to add to the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

EntityNotFoundException - If the File object does not reference an existing file or directory.

ArchiveEntryAddException - If the entry cannot be added, for some reason other than an I/O error.

add

U add(File f,
      AbsoluteLocation parentDirLocation)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         EntityNotFoundException,
                                         ArchiveEntryAddException

Add a file or directory entry to the specified parent directory in the archive. The entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, if any.

The name of the file entry will be the name of the added file. If you want another name for the entry, wrap the file in a FileReadableFile and then in a NamedReadableFileAdapter.

Parameters:

f - The file or directory to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

EntityNotFoundException - If the File object does not reference an existing file or directory.

ArchiveEntryAddException - If the entry cannot be added, for some reason other than an I/O error.

add

U add(File f,
      AbsoluteLocation parentDirLocation,
      V settings)
                                  throws IllegalStateException,
                                         WrappedIOException,
                                         EntityNotFoundException,
                                         ArchiveEntryAddException

Add a file or directory entry to the specified parent directory in the archive. The supplied settings is combined with the default settings for its entity type (file or directory) and the settings from the global rules that apply to the entry, if any.

The name of the file entry will be the name of the added file. If you want another name for the entry, wrap the file in a FileReadableFile and then in a NamedReadableFileAdapter.

Parameters:

f - The file or directory to add to the archive.

parentDirLocation - The location of the parent directory. It is not required that this directory is present in the archive.

settings - The custom settings to use for this entry. The custom settings are combined with the default settings and global rule settings as described above. If this is set to null, only the default settings combined with settings from the global rules that apply to this entry are used.

Returns:

this

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

EntityNotFoundException - If the File object does not reference an existing file or directory.

ArchiveEntryAddException - If the directory cannot be added, for some reason other than an I/O error.

addRecursively

U addRecursively(DirectoryView d,
                 AbsoluteLocation rootDirLocation)
                                             throws IllegalStateException,
                                                    WrappedIOException,
                                                    ArchiveEntryAddException

Add the supplied directory recursively to the specified position in the archive. Each entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, if any.

If the added directory is in a locking FileSystem, all added entities are temporarily locked by this method as they are being added to the archive.

If an error occurs when adding an entry, the recursive add operation terminates and the rest of the entries that were to be added are ignored. The archive file will then contain all entries that had been added before the error occurred.

Parameters:

d - The directory to add recursively to the archive.

rootDirLocation - The location where to put the root of the added directory tree. If this is the root directory (/), the contents of d are added directly to the archive's root directory.

Returns:

this.

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If an entry cannot be added, for some reason other than an I/O error.

addRecursively

U addRecursively(DirectoryView d,
                 AbsoluteLocation rootDirLocation,
                 Filter<? super EntityView> filter)
                                             throws IllegalStateException,
                                                    WrappedIOException,
                                                    ArchiveEntryAddException

Add the supplied directory recursively to the specified position in the archive. An entity is only added if it passes the supplied filter. Each added entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, if any.

If the added directory is in a locking FileSystem, all added entities are temporarily locked by this method as they are being added to the archive.

If an error occurs when adding an entry, the recursive add operation terminates and the rest of the entries that were to be added are ignored. The archive file will then contain all entries that had been added before the error occurred.

Parameters:

d - The directory to add recursively to the archive.

rootDirLocation - The location where to put the root of the added directory tree. If this is the root directory (/), the contents of d are added directly to the archive's root directory.

filter - The filter that is used to decide if an entity is to be added to the archive or not. This filter does not affect how the method traverses the directory tree in any way.

Returns:

this.

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If an entry cannot be added, for some reason other than an I/O error.

addRecursively

U addRecursively(DirectoryView d,
                 AbsoluteLocation rootDirLocation,
                 Filter<? super EntityView> filter,
                 ArchiveEntrySettingsRule<? extends V>... rules)
                                             throws IllegalStateException,
                                                    WrappedIOException,
                                                    ArchiveEntryAddException

Add the supplied directory recursively to the specified position in the archive. An entity is only added if it passes the supplied filter. Each added entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, combined with the settings from the supplied rules that apply to the entry.

If the added directory is in a locking FileSystem, all added entities are temporarily locked by this method as they are being added to the archive.

If an error occurs when adding an entry, the recursive add operation terminates and the rest of the entries that were to be added are ignored. The archive file will then contain all entries that had been added before the error occurred.

Parameters:

d - The directory to add recursively to the archive.

rootDirLocation - The location where to put the root of the added directory tree. If this is the root directory (/), the contents of d are added directly to the archive's root directory.

filter - The filter that is used to decide if an entity is to be added to the archive or not. This filter does not affect how the method traverses the directory tree in any way.

rules - Settings rules for this add operation.

Returns:

this.

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

ArchiveEntryAddException - If an entry cannot be added, for some reason other than an I/O error.

addRecursively

U addRecursively(File f,
                 AbsoluteLocation rootDirLocation)
                                             throws IllegalStateException,
                                                    WrappedIOException,
                                                    EntityNotFoundException,
                                                    ArchiveEntryAddException

Add the supplied file or directory recursively to the specified position in the archive. Each entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, if any.

If an error occurs when adding an entry, the recursive add operation terminates and the rest of the entries that were to be added are ignored. The archive file will then contain all entries that had been added before the error occurred.

Parameters:

f - The file or directory to add recursively to the archive.

rootDirLocation - The location where to put the root of the added directory tree. If this is the root directory (/), the contents of f (if it is a directory) are added directly to the archive's root directory.

Returns:

this.

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

EntityNotFoundException - If the File object does not reference an existing file or directory.

ArchiveEntryAddException - If an entry cannot be added, for some reason other than an I/O error.

addRecursively

U addRecursively(File f,
                 AbsoluteLocation rootDirLocation,
                 ArchiveEntrySettingsRule<? extends V>... rules)
                                             throws IllegalStateException,
                                                    WrappedIOException,
                                                    EntityNotFoundException,
                                                    ArchiveEntryAddException

Add the supplied file or directory recursively to the specified position in the archive. Each entry is added with the default settings for its entity type (file or directory), combined with settings from the global rules that apply to the entry, combined with settings from the supplied rules that apply to the entry.

If an error occurs when adding an entry, the recursive add operation terminates and the rest of the entries that were to be added are ignored. The archive file will then contain all entries that had been added before the error occurred.

Parameters:

f - The file or directory to add recursively to the archive.

rootDirLocation - The location where to put the root of the added directory tree. If this is the root directory (/), the contents of f (if it is a directory) are added directly to the archive's root directory.

rules - Settings rules for this add operation.

Returns:

this.

Throws:

IllegalStateException - If the archive builder is closed.

WrappedIOException - On I/O errors.

EntityNotFoundException - If the File object does not reference an existing file or directory.

ArchiveEntryAddException - If an entry cannot be added, for some reason other than an I/O error.

isClosed

boolean isClosed()

Is this archive builder closed?

Returns:

true if this archive builder is closed.

close

void close()

Close this archive builder, finish the archive and release all of the resources associated with the archive builder. This releases the write lock on the archive file (if it is in a locking FileSystem).

It is safe to call this method several times on the same archive builder.