UntarTF

Extract the contents of a Tar archive to a directory.

Task package:org.at4j
Java package:org.schmant.task.at4j.tar
Category:Archiving tasks
Since:0.9
EntityFS-aware?Yes*
Implements:ActionTaskFactory
GeneratorTaskFactory
ProcessTaskFactory
Produces:DirectoryView (the target).
See also:TarTF

Description:

This task extracts the contents of a Tar archive using At4J's TarExtractor class. The last modification times for the extracted archive entries are transferred to the created files and directories.

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

fileNameEncodingCharsettop

The charset used to encode file names in the Tar archive.

Setter method:
setFileNameEncodingCharset(Charset cs)
parameters:
cs – The character encoding.
Setter method:
setFileNameEncodingCharset(String name)
parameters:
name – The name of the character encoding.
Default value:
The platform's default character encoding.
filtertop

A filter that is used to select which entries to extract. There are a number of filter implementations in At4J. All of them implement TarEntryHeaderDataFilter and ConvenientFilter.

Setter method:
setFilter(Filter<? super TarEntryHeaderData> f)
parameters:
f – The filter.
Default value:
No filter (All entries are extracted.)
logFootertop

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
logHeadertop

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
overwriteStrategytop

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 of true means that the DoOverwriteAndLogWarning strategy is used. A value of false gives the DontOverwriteAndThrowException strategy.
parameters:
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
reportLeveltop

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 level
parameters:
l – The new report level.
source (required)top

The Tar file.

Setter method:
setSource(Object f)
parameters:
f – The Tar file.
Interpreted by InterpretAsReadableFileStrategy.
target (required)top

The directory to extract the Tar entries to.

Setter method:
setTarget(Object d)
parameters:
d – The target directory.
Interpreted by InterpretAsDirectoryStrategy.
traceLoggingtop

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

Extract the contents of the Tar archive in the file tf to the directory target.

enableTaskPackage("org.at4j"); new UntarTF(). // The Tar file. This may for instance be a File or an EFile. setSource(tf). // The target directory. This may for instance be a File directory or a // Directory. setTarget(target). run();

Example 2

Extract the text files from the Tar archive in the file tf to the directory target.

enableTaskPackage("org.at4j"); new UntarTF(). // The Tar file. This may for instance be a File or an EFile. setSource(tf). // The target directory. This may for instance be a File directory or a // Directory. setTarget(target). setFilter( // A filter that matches text files. TarFileEntryFilter.FILTER.and( new TarEntryNameGlobFilter("*.txt"))). run();

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