Build a Tar archive using the At4J Tar builder.
| Task package: | org.at4j |
| Java package: | org.schmant.task.at4j.tar |
| Category: | Archiving tasks |
| Since: | 0.8 |
| EntityFS-aware? | Yes* |
| Implements: | ActionTaskFactory GeneratorTaskFactory ProcessTaskFactory |
| Produces: | The interpreted target property. The exact type depends on the type used for the target. |
| See also: | UntarTF |
Description:
Build a new Tar archive by adding file and directory entries to this task.
Each entry has some metadata associated with it, such as the added entity's owner user and group id:s. It is decided by the entry's effective TarEntrySettings. When adding an entity to the Tar task, its effective settings is determined by the following algorithm:
- Start with the default settings for the entity type (file or directory).
- Combine the default settings with the Tar task's default settings for the entity type.
- For each of the Tar task's global rules that are applicable for the entity to add as decided by the rule's filter, combine the settings with the rule's settings.
- Combine the settings with settings provided specifically for the entity.
A rule is a TarEntrySettings object paired with a EntityToArchiveFilter. Only the entries matching the filter will have the settings applied to them. Rules can be added either globally or by using a TarDirectoryWithRules object when adding a directory source.
There are several different kinds of metadata that can be configured using the TarEntrySettings object. See TarStreamBuilder for details.
Files and directories can be added to the Tar file. Directories are always added recursively. The TarTask.addToTarBuilder(org.at4j.tar.builder.TarStreamBuilder, java.lang.Object) method is used to interpret each added object.
There are four supported ways of encoding Tar entries. They are, listed in age order (oldest first):
- Unix V7 format
- POSIX 1003.1-1988 (Ustar)
- Gnu Tar (the default)
- POSIX 1003.1-2001 (Pax)
The contents of a Tar archive is never compressed. On the other hand, the archive itself is often compressed using gzip or bzip2 compression. An archive can be compressed by running the GZipTF or BZip2TF task on the archive file, or by using file proxies like in example 2.
The Tar task uses the platform's default characeter encoding by default in the Tar files it creates. Another character encoding can be set on the entry strategy property.
Appending to existing archives is not supported.
Note on character encodings in Tar files: By default, metadata about Tar entries is encoded using the default character encoding of the platform where the tar file is created. This makes it necessary for those reading Tar files to know which character encoding that was used when the archive was created. This is often, but not always, Codepage 437 on Windows or UTF-8 on Unix. The only exception to this rule is the Pax variables that are always encoded using UTF-8. If Tar entries in a Pax compatible archive contains non-ASCII characters, the Tar entry path is (often) stored in the Pax header, making the archive portable between different platforms.
Required properties
Properties
| entryStrategy | top |
The strategy that decides the format of the created Tar entries. At4J has strategy classes for the four different entry formats listed above:
- V7TarEntryStrategy – Unix V7 entries.
- UstarEntryStrategy – POSIX 1003.1-1988 (ustar) entries.
- GnuTarEntryStrategy – Gnu Tar entries (the default).
- PaxTarEntryStrategy – POSIX 1003.1-2001 (pax) entries.
See example 4 for an example of how to use a different strategy than the default.
- Setter method:
setEntryStrategy(TarEntryStrategy strat)
parameters:strat– The strategy.- Default value:
- A GnuTarEntryStrategy with the default settings.
| logFooter | top |
The message that is logged to info level
after the task has been successfully run.
- Setter method:
setLogFooter(String s)
parameters:s– The footer message.- Default value:
- Empty (no footer message is logged.)
- See also:
- logHeader
| logHeader | top |
The message that is logged to info level
before the task is run.
- Setter method:
setLogHeader(String s)
parameters:s– The header message.- Default value:
- A task class specific message.
- See also:
- logFooter
| overwriteStrategy | top |
The overwrite strategy decides how the task will react if there already is an entity (file or directory) in a location where it wants to create a new entity.
If the strategy is to not overwrite existing entities, the task will fail when it cannot create the entities that it wants to create.
Non-empty directories are never overwritten, regardless of the chosen strategy.
- Setter method:
setOverwrite(boolean b)Setting this to a value ofparameters:truemeans that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.b– Should an existing entity be overwritten?- Setter method:
setOverwriteStrategy(OverwriteStrategy strat)Set the overwrite strategy.parameters:strat– The overwrite strategy.- Default value:
- DontOverwriteAndThrowException
- See also:
- target
| reportLevel | top |
This property is used to change the Report level for all task created by this task factory. The report level is changed for the thread running the task when the it is run, and is restored to its previous level when the it is done.
- Setter method:
setReportLevel(Level l)Set the report levelparameters:l– The new report level.
| rules | top |
The global rules is a list of settings objects paired with entry filters that determine which entries they apply to.
- Setter method:
addRule(ArchiveEntrySettingsRule<? extends TarEntrySettings> rule)Add one rule.parameters:rule– A rule.- Setter method:
addRules(Object o)Add one or several rules.parameters:o– One rule or an array or a collection of rules. Rules are ArchiveEntrySettingsRule<? extends TarEntrySettings> objects.- Setter method:
clearRules()Clear the list of rules.
| sources (required) | top |
A collection of sources that are added to the Tar archive by the task.
Each added source may have some extra information associated with it that the method interpreting it can understand and react to. The following objects may be useful:
- EntityAndAbsoluteLocation – used to tell the task where to put the added entity in the archive
- TarEntryAndSettings – associate custom metadata with an added file or with all entries created when adding a directory recursively.
- TarDirectoryWithRules – use one or several metadata rules in addition to the global metadata rules when adding a directory recursively.
- Setter method:
addSource(Object o)Add one or several sources.parameters:o– The source. This may be a single source object or a collection or array of source objects.
Interpreted byTarTask.addToTarBuilder(org.at4j.tar.builder.TarStreamBuilder, Object).- Setter method:
addSources(Object o)Add one or several sources.parameters:o– The source. This may be a single source object or a collection or array of source objects.
Interpreted byTarTask.addToTarBuilder(org.at4j.tar.builder.TarStreamBuilder, Object).- Setter method:
clearSources()Discard all sources.- Setter method:
setSource(Object o)Set one or several sources and discard previously set sources.parameters:o– The source. This may be a single source object or a collection or array of source objects.
Interpreted byTarTask.addToTarBuilder(org.at4j.tar.builder.TarStreamBuilder, Object).- Setter method:
setSources(Object o)Set one or several sources and discard previously set sources.parameters:o– The source. This may be a single source object or a collection or array of source objects.
Interpreted byTarTask.addToTarBuilder(org.at4j.tar.builder.TarStreamBuilder, Object).
| tarBuilderSettings | top |
The configuration for the TarStreamBuilder object that is used for building the Tar file. This object contains several configurable properties. See the examples below.
- Setter method:
setTarBuilderSettings(TarBuilderSettings settings)
parameters:settings– The Tar builder settings.- Default value:
- The default Tar builder settings.
| target (required) | top |
The Tar file to create.
Since the target is interpreted into a new WritableFile, different new writable file proxies such as the GZipNewWritableFileProxy or the MultiplexingNewWritableFileProxy can be used to modify how the Tar archive is written to its target file. See this example below.
- Setter method:
setTarget(Object o)
parameters:
| traceLogging | top |
If trace logging is enabled for a task, it reports its configuration before it is run.
Trace logging may also be enabled globally for all tasks by calling TraceMode.setTraceMode(boolean).
- Setter method:
setTraceLogging(boolean b)Enable or disable trace logging.parameters:b– Enable trace logging?
Examples
Example 1
Create a Tar archive from the contents of directory
hierarchies d1 and d2, both stored under the directory
ds-1.0 in the Tar file. The archive will be put in the directory
d.
JavaScript
Example 2
Create a Tar archive from the contents of directory
hierarchies d1 and d2, ignoring all .svn
directories. Both directory hierarchies are stored under the directory
ds-1.0 in the Tar file. The Tar archive will be written to two files
in the directory d: the gzip compressed ds-1.0.tar.gz
and the bzip2 compressed ds-1.0.tar.bz2.
JavaScript
Example 3
Create a Tar archive with sources added in many
different ways. The archive will be put in the directory d.
JavaScript
Example 4
Create a Tar archive with custom metadata for its entries. For more information on custom metadata, read the At4J Programmer's Guide.
Groovy
JavaScript
JRuby
Jython
Example 5
Create a Tar archive containing the contents of the
src and bin directories. It uses a directory-specific
rule for the bin directory.
JavaScript
* An EntityFS-aware task is implemented using EntityFS. This means that it uses the filter settings of DirectoryView:s and also that it often can work with other file system implementations than File-based, such as the RAM file system.