Build a Zip archive using the At4J Zip builder.
Task package: | org.at4j |
Java package: | org.schmant.task.at4j.zip |
Category: | Archiving tasks |
Since: | 0.8 |
EntityFS-aware? | Yes* |
Implements: | ActionTaskFactory GeneratorTaskFactory ProcessTaskFactory |
Produces: | EFile (the target). |
See also: | ZipTF At4JUnzipTF |
Description:
Build a new Zip archive.
The difference between this task and the ZipTF task is that this task uses the ZipBuilder from the At4J project, which supports more compression methods and is able to configure the Zip files it builds in more different ways than Java's built in Zip utilities.
Each Zip entry has some metadata associated with it. The metadata for each Zip entry is decided by its effective ZipEntrySettings. When adding an entity to the Zip 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 Zip task's default settings for the entity type.
- For each of the Zip 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 ZipEntrySettings 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 ZipDirectoryWithRules object when adding a directory source.
There are several different kinds of metadata that can be configured using the ZipEntrySettings object. See ZipBuilder for details.
Many different objects can be added to the Zip file – files, directories (added recursively) and data read from input streams. The At4JZipTask.addToZipBuilder(org.at4j.zip.builder.ZipBuilder, java.lang.Object) method is used to interpret each added object.
Appending to existing archives is not supported.
Note on character encodings in Zip files: It is not specified in any of the Zip specification documents which character encoding to use when encoding text data in a Zip file. Windows programs (7-Zip, WinZip) use Codepage 437 to encode file names, and the platform's default charset (often Codepage 1252) for other text information such as entry comments. Unix programs use the platform's default character encoding (often UTF-8) for both file names and other text data.
Required properties
Properties
comment | top |
The Zip file comment.
- Setter method:
setComment(String s)
Set the comment.parameters:s
– The comment.- Default value:
- Created by Schmant -- www.schmant.org
compressionLevel | top |
This property sets the compression level for the default file compression. If a custom default file entry settings object is set in the defaultFileEntrySettings property, setting this property overrides the compression level settings of that object.
- Setter method:
setCompressionLevel(CompressionLevel level)
parameters:level
– The compression level.- See also:
- defaultFileEntrySettings
defaultDirectoryEntrySettings | top |
The default directory entry settings.
- Setter method:
setDefaultDirectoryEntrySettings(ZipEntrySettings settings)
parameters:settings
– The default directory entry settings. The default default directory entry settings is combined with this object when calculating the effective settings for a directory entry, so the settings supplied here only has to contain the differences relative to the default default settings.- See also:
- defaultFileEntrySettings
defaultFileEntrySettings | top |
The default file entry settings.
- Setter method:
setDefaultFileEntrySettings(ZipEntrySettings settings)
parameters:settings
– The default file entry settings. The default default file entry settings is combined with this object when calculating the effective settings for a file entry, so the settings supplied here only has to contain the differences relative to the default default settings.- See also:
- defaultDirectoryEntrySettings
- compressionLevel
fileNameEncodingCharset | top |
The charset to use for encoding file names in the Zip file.
- Setter method:
setFileNameEncodingCharset(Charset cs)
parameters:cs
– The charset.- Setter method:
setFileNameEncodingCharset(String name)
parameters:name
– The name of the charset.- Default value:
- The platform's default charset.
- See also:
- textEncodingCharset
internalFileAttributesStrategy | top |
The strategy object for creating each Zip entry's internal file attributes.
- Setter method:
setInternalFileAttributesStrategy(InternalFileAttributesStrategy strat)
parameters:strat
– The strategy.- Default value:
- The default internal file attributes strategy.
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:true
means 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 object paired with entry filters that determines which entries they apply to.
- Setter method:
addRule(ArchiveEntrySettingsRule<? extends ZipEntrySettings> 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 collection of rules. Rules are ArchiveEntrySettingsRule<? extends ZipEntrySettings> objects.- Setter method:
clearRules()
Clear the list of rules.
sources (required) | top |
A collection of sources that are added to the Zip 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
- ZipEntryAndSettings – associate custom metadata with an added file or with all entries created when adding a directory recursively.
- ZipDirectoryWithRules – use one or several metadata rules in addition to the global metadata rules when adding a directory recursively.
Directory sources are added 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 an array of source objects.
Interpreted byAt4JZipTask.addToZipBuilder(org.at4j.zip.builder.ZipBuilder, 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 an array of source objects.
Interpreted byAt4JZipTask.addToZipBuilder(org.at4j.zip.builder.ZipBuilder, 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 an array of source objects.
Interpreted byAt4JZipTask.addToZipBuilder(org.at4j.zip.builder.ZipBuilder, 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 an array of source objects.
Interpreted byAt4JZipTask.addToZipBuilder(org.at4j.zip.builder.ZipBuilder, Object)
.
target (required) | top |
The Zip file to create.
- Setter method:
setTarget(Object o)
parameters:- See also:
- overwriteStrategy
textEncodingCharset | top |
The charset to use for encoding text other than file names in the Zip file.
- Setter method:
setTextEncodingCharset(Charset cs)
parameters:cs
– The charset.- Setter method:
setTextEncodingCharset(String name)
parameters:name
– The name of the charset.- Default value:
- The platform's default charset.
- See also:
- fileNameEncodingCharset
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 Zip archive from the contents of directory
hierarchies d1
and d2
, both stored under the directory
ds-1.0
in the Zip file. The archive will be put in the Directory
d
.
JavaScript
Example 2
Create a Zip 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 Zip file. The archive will be put in the Directory
d
.
JavaScript
Example 3
Create a Zip archive with the sources set in many
different ways. The archive will be put in the Directory d
.
JavaScript
Example 4
Create a Zip archive with custom metadata and a non-standard compression method for its entries. For more information on custom metadata, read the At4J Programmer's Guide.
Groovy
JavaScript
JRuby
Jython
Example 5
Create a Zip archive containing the contents of the
src
and bin
directories. It uses a directory-specific
rule for the bin
directory. Use maximum compression for the files.
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.