|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
U
- The archive builder implementation.V
- The type of settings used for the archive builder implementation.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:
getDefaultFileEntrySettings()
and
getDefaultDirectoryEntrySettings()
.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.ArchiveEntrySettings.combineWith(ArchiveEntrySettings)
method.
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.
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 |
---|
U setDefaultFileEntrySettings(V s) throws IllegalStateException
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.
s
- The new default file entry settings.
this
IllegalStateException
- If the archive builder is closed.setDefaultDirectoryEntrySettings(ArchiveEntrySettings)
V getDefaultFileEntrySettings() throws IllegalStateException
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.
IllegalStateException
- If the archive builder is closed.getDefaultDirectoryEntrySettings()
,
setDefaultFileEntrySettings(ArchiveEntrySettings)
U setDefaultDirectoryEntrySettings(V s) throws IllegalStateException
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.
s
- The new default directory entry settings.
this
IllegalStateException
- If the archive builder is closed.setDefaultFileEntrySettings(ArchiveEntrySettings)
V getDefaultDirectoryEntrySettings() throws IllegalStateException
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.
IllegalStateException
- If the archive builder is closed.getDefaultFileEntrySettings()
,
setDefaultDirectoryEntrySettings(ArchiveEntrySettings)
U addRule(ArchiveEntrySettingsRule<? extends V> rule) throws IllegalStateException
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.
rule
- The rule to append to the end of the rule list.
this
IllegalStateException
- If the archive builder is closed.addRules(Collection)
,
removeRule(ArchiveEntrySettingsRule)
,
getRules()
U addRules(Collection<? extends ArchiveEntrySettingsRule<? extends V>> rules) throws IllegalStateException
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.
rules
- The rules to append to the end of the rule list.
this
IllegalStateException
- If the archive builder is closed.addRule(ArchiveEntrySettingsRule)
,
removeRule(ArchiveEntrySettingsRule)
,
getRules()
boolean removeRule(ArchiveEntrySettingsRule<? extends V> rule) throws IllegalStateException
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.
rule
- The rule to remove from the list.
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.
IllegalStateException
- If the archive builder is closed.addRule(ArchiveEntrySettingsRule)
,
getRules()
List<ArchiveEntrySettingsRule<? extends V>> getRules() throws IllegalStateException
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.
IllegalStateException
- If the archive builder is closed.addRule(ArchiveEntrySettingsRule)
,
removeRule(ArchiveEntrySettingsRule)
U add(NamedReadableFile f) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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
.
f
- The file to add to the archive.
this
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.U add(NamedReadableFile f, AbsoluteLocation parentDirLocation) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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
.
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.
this
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.U add(NamedReadableFile f, AbsoluteLocation parentDirLocation, V settings) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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
.
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.
this
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.U add(DirectoryView d) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
d
- The directory to add to the archive.
this
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.U add(DirectoryView d, AbsoluteLocation parentDirLocation) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
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.
this
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.U add(DirectoryView d, AbsoluteLocation parentDirLocation, V settings) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
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.
this
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.U add(File f) throws IllegalStateException, WrappedIOException, EntityNotFoundException, ArchiveEntryAddException
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
.
f
- The file or directory to add to the archive.
this
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.U add(File f, AbsoluteLocation parentDirLocation) throws IllegalStateException, WrappedIOException, EntityNotFoundException, ArchiveEntryAddException
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
.
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.
this
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.U add(File f, AbsoluteLocation parentDirLocation, V settings) throws IllegalStateException, WrappedIOException, EntityNotFoundException, ArchiveEntryAddException
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
.
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.
this
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.U addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
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.
this
.
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.U addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation, Filter<? super EntityView> filter) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
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.
this
.
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.U addRecursively(DirectoryView d, AbsoluteLocation rootDirLocation, Filter<? super EntityView> filter, ArchiveEntrySettingsRule<? extends V>... rules) throws IllegalStateException, WrappedIOException, ArchiveEntryAddException
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.
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.
this
.
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.U addRecursively(File f, AbsoluteLocation rootDirLocation) throws IllegalStateException, WrappedIOException, EntityNotFoundException, ArchiveEntryAddException
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.
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.
this
.
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.U addRecursively(File f, AbsoluteLocation rootDirLocation, ArchiveEntrySettingsRule<? extends V>... rules) throws IllegalStateException, WrappedIOException, EntityNotFoundException, ArchiveEntryAddException
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.
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.
this
.
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.boolean isClosed()
true
if this archive builder is closed.void close()
FileSystem
).
It is safe to call this method several times on the same archive builder.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |