RecursiveProcessTF

Run a process task for each entity returned when iterating recursively over a set of source entities.

Description:

Run a process task for each entity returned when iterating recursively over a set of source entities.

The sources property is configured with one or more source directories. When the task is run, it iterates the directories recursively. For each entity (file or directory) it finds, it creates a new task using the task factory. The created task is configured with the found entity as its source entity and a target FutureEntity that is inferred using this task's targetStrategy, and the task is then run.

By default, created tasks are run in the thread running this task. They may also be run by an optional task executor.

Entities in a source directory hierarchy that a proxied task should not be run for can be ignored either by using a DirectoryView that hides the unwanted entities or by using a DirectoryAndFilter. The difference between the two approaches is that when using a DirectoryView, the recursive process task does not iterate down into directories that do not pass the view's EntityFilter(s).

This task is also described in the Schmant User's Guide.

Required properties

• sources
• target
• taskFactory

Properties

If a task executor is used, this property can be set to give all scheduled tasks a dependency.

Setter method:

setDependency(TaskDependency d)
parameters:

d –  A dependency for all tasks.

See also:

taskExecutor

Should header and footer logging from the nested tasks be disabled?

Setter method:

setDisableHeaderLogging(boolean b)
parameters:

b – Disable header and footer logging?

Default value:

true (header and footer logging is disabled)

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

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

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

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.

A collection of source directories and/or files to run recursive process tasks for.

Setter method:

addSource(Object o)

Add one or several source files and/or directories.

parameters:

o – One source file or directory or several source files and/or directories.
Interpreted by InterpretAsDirectoryStrategy or InterpretAsEFileStrategy.

Setter method:

addSources(Object o)

Add one or several source files and/or directories.

parameters:

o – One source file or directory or several source files and/or directories.
Interpreted by InterpretAsDirectoryStrategy or InterpretAsEFileStrategy.

Setter method:

clearSources()

Discard all sources.

Setter method:

setSource(Object o)

Set one or several source files and/or directories and discard previously set sources.

parameters:

o – One source file or directory or several source files and/or directories.
Interpreted by InterpretAsDirectoryStrategy or InterpretAsEFileStrategy.

Setter method:

setSources(Object o)

Set one or several source files and/or directories and discard previously set sources.

parameters:

o – One source file or directory or several source files and/or directories.
Interpreted by InterpretAsDirectoryStrategy or InterpretAsEFileStrategy.

The target for the recursive process task. This is usually a directory, but custom target strategies might use other kinds of targets.

Setter method:

setTarget(Object o)
parameters:

o – 
Interpreted by InterpretAsDirectoryStrategy.

See also:

targetStrategy

The TargetStrategy strategy object that is used to decide where a processed file or directory will be put.

The target strategy is either a TargetStrategy object or a closure that can be evaluated to get the target location. A closure must take the following arguments, in this order:

1. An EntityView – the source entity.
2. A DirectoryView – the target base directory.
3. A RelativeLocation – the source entity's location relative to the source base directory.

Setter method:

setTargetEntityStrategy(Object s)
parameters:

s – A target strategy. This may be a TargetStrategy object or a closure.
Interpreted by RecursiveProcessTask#getTargetFromTargetStrategy(DirectoryView targetDir, RelativeLocation rel).

Default value:

A DefaultTargetStrategy instance. This puts the processed entity in the same place in the target directory hierarchy as the source entity has in the source hierarchy and with the same name as the source entity.

If this property is set, all created tasks are added to the executor instead of run right away.

If this property is not set and this task is added to an executor, all tasks created by this task will be run in the same thread as the task. If this property is set, the tasks will be distributed among all threads that are available to the executor.

Dependencies for the tasks can be set in the dependency property.

Note: When letting this task schedule tasks that it creates in a task executor, this task object cannot be used as a dependency for the tasks depending on the scheduled tasks. Use the dependency object returned from Task.getDependencyForTasksScheduledByThisTask() instead.

Setter method:

setTaskExecutor(TaskExecutor te)
parameters:

te –  A task executor.

See also:

dependency

A process task factory or a closure.

If this is a process task factory, a new task object is created for each processed entity. If the recursive process task encounters entities of types that are not supported by the task factory, they are ignored.

If this is a closure, the same closure instance will be run for each processed entity. The closure is called with one argument of the type ClosureParameters.

Setter method:

setTaskFactory(java.lang.Object f)
parameters:

f – A ProcessTaskFactory or a closure.

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

Implement TreeCopyTF using RecursiveProcessTF.

Example 2

Pre-process Java source files from the src directory hierarchy. Put the resulting files in a directory hierarchy under src_pp.

Example 3

Move Java source files from the src directory hierarchy to the src2 hierarchy. Change their file name extensions to txt.

Example 4

Move all text files from the src directory hierarchy to the doc directory hierarchy. Change their file names to be in upper case.

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