The next example shows a script that compiles the Java source files found in the directory src and its subdirectories, puts the compiled classes in a temporary directory and then bundles them in a Jar file.

There are two important things to point out in the example above:

The following sections will explain each of the bullet points in more detail.

Task:s and TaskFactory:s are closely related. A task object is used just once for running a task and then it is discarded. A task factory is a factory object used for creating one or more task objects. It can be reused to create several tasks with similar configurations, for instance when processing files recursively in a directory hierarchy (see example Example 4.7, “Set version information in all XML files in a directory hierarchy, overwriting the original files, using a RecursiveActionTF”). Build scripts always use task factories to create tasks; tasks objects are never created directly.

To create a task, a build script creates a task factory and sets all of the task's configuration on the factory using its setter methods. Then the script creates one or several tasks from the factory and runs them. Behind the scenes, the task factory configures a TaskSpecification object, which it hands over to the Task object that it creates. After creating the task, if the script continues to configure the same task factory, the task factory makes a copy of the task specification object so that the configuration of the already created task does not change. After creating the next task, the task specification is copied again, and so on. This ensures that the configuration of a running task never is modified.

There are four different categories of tasks:

The source and target properties are interpreted (see below), so the exact types of the properties varies from task to task. source is often a file or a directory and target is often a directory or a FutureFile (see below).

Both Task and TaskFactory implement java.lang.Runnable. Calling run() on a TaskFactory is a shortcut for calling create().run() on it.

The reason for separating the task and task factory functionality into two different classes is illustrated by Example 4.7, “Set version information in all XML files in a directory hierarchy, overwriting the original files, using a RecursiveActionTF” below. It shows how an action task is created and run for each XML file in a directory hierarchy. The task factory is a template for creating tasks that only differ in their source properties.

The Task factory index lists all available task factories.

Some task factory property setter methods take Object arguments. These arguments are interpreted, which means that it is up to the task to interpret them into something useful. This gives a great deal of flexibility in the different kinds of variables that a Schmant script may use. For instance, a Schmant script may use java.io.File objects as simple pointers to the local file system and EntityFS objects when more advanced file system operations are needed, as shown in Example 4.2, “Compile Java files and build a Jar file”.

The example below shows how different types can be used as the source property for a CopyTF.

The reference documentation for each task describes how it interprets each of its interpreted properties. Most tasks use the methods of ArgumentInterpreter, but some tasks have custom interpretation methods of their own. ArgumentInterpreter is described in more detail, along with descriptions of possible implementations of different interpreted types, in Appendix A, ArgumentInterpreter.

If a task factory property can take a collection of objects, for instance several source files for copying, it flattens the arguments given to the property's setter method. This means that the build script can give one or several arguments to the method. Multiple arguments can be stored in arrays or Collection:s. The arrays or collections may even contain other arrays or collections. All arguments are flattened to a single list using a FlatteningList.

There are two ways of representing the target of a generator task – using a File or using a FutureEntity such as a FutureFile or a FutureDirectory. Both are references to the location where the generator task will put its result.

After the generator task has been run, the created entity can be retrieved from the FutureEntity object. This makes it possible to use future entities for representing source entities that do not yet exist when using a TaskExecutor for running tasks, see the section called “Task executors and future entities” for an example.

For an interpreted task factory property, instead of setting the property value directly, a build script may instead set a Producer object that will yield the property value when the task is run. This is useful for setting properties that may not yet be created when the task is configured, and may be a little more compact than using a closure.

All generator tasks and some non-generator tasks are Producer:s. There are also a few other Producer implementations, such as the FutureProperty that produces the property value of another object.

The following example shows how an object produced by one task is fed to another task.

A build script may need to run a task for each file in a directory hierarchy, for instance when processing text files like in the examples below. This can be accomplished in a couple of ways. The most straightforward is perhaps to use an EntityFS FilteringIterator together with a DepthFirstIterator like in the example below.

A simpler and more compact solution, however, is to use a RecursiveActionTF or a RecursiveProcessTF.

The two examples above does exactly the same thing. RecursiveActionTF used together with ReplaceSourceFileTF solves the problem of keeping the results from the text processing task in a temporary file before the original file is replaced, so that that does not have to be implemented in the build script.

If the build script does not want to overwrite the original files, but instead wants to put the results from the text processing in a new location, it can use the RecursiveProcessTF. It creates the target directory hierarchy and puts the created files where they should be.

To determine where to put the target entities, the RecursiveProcessTF uses can use either a TargetStrategy or a closure object. In the examples above, the default target strategy DefaultTargetStrategy is used. It puts the created entities in the same location relative to the target directory as the source entities have relative to the source directory.

The table below lists the different available TargetStrategy:s.

If a closure is used, it should take three parameters – an EntityView (the processed entity), a DirectoryView (the target base directory) and a RelativeLocation (the source entity's location relative to the source base directory). When executed, the closure should return something that can be interpreted by the future entity interpreter (a FutureEntity, for instance).

The following example shows how a closure can be used to put big XML files in one directory hierarchy and small XML files in another.