JavaWorkspaceBuilderTF

Build Java projects in a workspace.

Task package:org.schmant.task.base
Java package:org.schmant.task.project
Category:Compiling tasks
Since:0.9
EntityFS-aware?Yes*
Implements:GeneratorTaskFactory
Produces:The interpreted target property. The exact type depends on the type used for the target.

Description:

This task builds Java projects in a ProjectRepository such as an Eclipse workspace. It may optionally preprocess the source files and/or postprocess the class files.

To build the Java projects, this task uses tasks created from a compile task factory. A preprocess task factory can be set to create a preprocess task for each source directory. A postprocess task factory can be set to create one postprocessing task for each directory where this task puts the compiled class files. This task may have one or several directories where it will put its class files, depending on the value of the projectSpecificTargetDirectories property.

If a more fine-grained control over the compilation process than what this task can provide, use the manual method described in the User's Guide.

Required properties

Properties

compileTaskFactorytop

The task factory that is used to create tasks for compiling the Java source files.

Setter method:
setCompileTaskFactory(JavacTaskFactory tf)
parameters:
tf – The compilation task factory.
Default value:
A vanilla Jdk6JavacTF.
copyNonJavaSourceFilesToTargettop

If this property is set, all non-Java source files in the source directories are copied to the target directory.

Setter method:
setCopyNonJavaSourceFilesToTarget(boolean b)
parameters:
b – Should non-Java source files be copied to the target directory?
Default value:
false (Non-Java source files are not copied.)
dependencytop

If a task executor is set, the tasks scheduled in that executor will wait for this dependency.

Setter method:
setDependency(TaskDependency dep)
parameters:
dep – The dependency.
See also:
taskExecutor
dontBuildRegularSourcestop

Should the regular source directories for projects not be built? IntelliJ IDEA modules may have both regular and test sources. Eclipse projects have only regular sources.

Setter method:
setDontBuildRegularSources(boolean b)
parameters:
b – Should regular sources not be built?
Default value:
false (Regular sources are built.)
See also:
dontBuildTestSources
dontBuildTestSourcestop

If the workspace is an IntelliJ IDEA project and its modules (projects) contains test sources, should the test sources also be built?

Setter method:
setDontBuildTestSources(boolean b)
parameters:
b – Should test sources not be built?
Default value:
false (Test sources are built.)
See also:
dontBuildRegularSources
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
postprocessTaskFactorytop

A task factory used for creating class file postprocessing tasks or a closure used for postprocessing files.

If this is set to be a task factory, it will be used to create a task for each directory where this task puts class files.

The task's source property is set to be a DirectoryAndFilter object containing the class files directory and a EFileFilter, which means that only the files (not the directories) will be visible in the class file hierarchy if the preprocess task is EntityFS-aware.

If this is set to be a closure, the closure will be called with a ClosureParameters argument for each directory where this task will put class files.

Setter method:
setPostprocessTaskFactory(java.lang.Object tf)
parameters:
tf – A ProcessTaskFactory or a closure.
See also:
preprocessTaskFactory
preprocessTaskFactorytop

A task factory used for creating Java source file preprocessing tasks or a closure used for preprocessing files.

If this is set to be a task factory, it will be used to create a task for each source directory in the projects that should be built.

The task's source property is set to be a DirectoryAndFilter object containing the source directory and a EFileFilter, which means that only the files (not the directories) will be visible in the source hierarchy if the preprocess task is EntityFS-aware.

If this is set to a closure, the closure will be called with a ClosureParameters object for each source directory in the projects that should be built.

If you want to preprocess the source files before creating this task instead of using this property, the source directories with preprocessed source files can be set in the projectSourceDirectories property.

Setter method:
setPreprocessTaskFactory(java.lang.Object tf)
parameters:
tf – A ProcessTaskFactory or a closure.
See also:
postprocessTaskFactory
projectSourceDirectories
projectFiltertop

Only the Project:s matching this filter will be built.

Setter method:
setProjectFilter(Filter<? super Project> f)
parameters:
f – A project filter. See also ProjectFilter.
Default value:
A JavaProjectFilter.
projectSourceDirectoriestop

This property contains a mapping between project names and source directories. For the projects that occur in the map, the map's source directory is used instead of the project's. This can be use to set alternate source directories for projects with sources that have been preprocessed before this task was created.

Setter method:
addProjectSourceDirectories(Map<String, Object> m)
Set alternate source directories for all projects in a map.
parameters:
m – A map containing alternate source directories for projects.
Interpreted by InterpretAsReadOnlyDirectoryStrategy.
Setter method:
addProjectSourceDirectory(String name, Object dir)
Set an alternate source directory for a project.
parameters:
name – The project name.
dir – A source directory.
Interpreted by InterpretAsReadOnlyDirectoryStrategy.
Setter method:
clearProjectSourceDirectories()
Clear previously set alternate source directories.
See also:
preprocessTaskFactory
projectSpecificTargetDirectoriestop

If this property is set, the task will put each project's built class files in a separate directory named after the project under the target directory.

If this property is not set, the task puts all built class files in a package name hierarchy directly under the target directory.

Setter method:
setProjectSpecificTargetDirectories(boolean b)
parameters:
b – Use project-specific target directories?
Default value:
false (All projects' class files are put in a package name hierarchy under the target directory.)
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.
target (required)top

The directory where the class files should be put.

Setter method:
setTarget(Object o)
Set the target.
parameters:
o – A read/write directory.
Interpreted by InterpretAsDirectoryStrategy.
taskExecutortop

If this property is set, the supplied TaskExecutor will be used to schedule all the tasks created by this task. If not, the tasks will be run right away when this task is run.

Note: When letting this task schedule the 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 retrieved by calling Task.getDependencyForTasksScheduledByThisTask() instead.

Setter method:
setTaskExecutor(TaskExecutor te)
parameters:
te – The task executor.
See also:
dependency
tempDirectorytop

The directory where this task will put its temporary files. If this is not set, this task will use the target directory's file system's default temporary files directory, or the platform's default temporary files directory if the target file system's is not set.

Setter method:
setTempDirectory(Object o)
parameters:
o – A temporary files 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?
workspace (required)top

The project repository that contains the Java projects to build.

Setter method:
setWorkspace(ProjectRepository pr)
parameters:
pr – The workspace

Examples

Example 1

Build all Java projects in the workspace in /home/me/myproject. Put the class files in /tmp/target.

// Create the Eclipse workspace object wos = new EclipseWorkspace( new File("/home/me/myproject")); // Build all Java projects new JavaWorkspaceBuilderTF(). setWorkspace(wos). // Use a custom factory for the compile tasks setCompileTaskFactory( new Jdk6JavacTF(). addArgument("-Xlint"). setTargetVersion("6"). setEncoding("UTF-8")). setTarget(new File("/tmp/target")).run();

Example 2

Build all Java projects in the workspace in /home/me/myproject. Preprocess the source files to make all public classes, variables and methods public final. Put the class files in /tmp/target.

// Create the Eclipse workspace object wos = new EclipseWorkspace( new File("/home/me/myproject")); // Build all Java projects new JavaWorkspaceBuilderTF(). setWorkspace(wos). // // Set a preprocessing task factory that makes all public stuff public // final... setPreprocessTaskFactory( new RecursiveProcessTF(). setTaskFactory( new TextReplaceTF(). // \\1 matches the first capturing group, \\2 the second addReplace("(\\p{Blank}+)public(\\p{Blank}+)","\\1public final\\2"))). setTarget(new File("/tmp/target")).run();

Example 3

Build all Java projects in the workspace in /home/me/myproject. Put the class files in project-specific target directories under /tmp/target.

// Create the Eclipse workspace object wos = new EclipseWorkspace( new File("/home/me/myproject")); // Build all Java projects new JavaWorkspaceBuilderTF(). setWorkspace(wos). // // Put class files for each project in a separate directory. setProjectSpecificTargetDirectories(true). // // Copy all non-Java source files to the target directories. setCopyNonJavaSourceFilesToTarget(true). setTarget(new File("/tmp/target")).run();

Example 4

For the workspace in /home/me/myproject containing four projects MyProject_foo, MyProject_foo_test, MyProject_bar and MyProject_bar_test, build the projects and bundle the built classes in three different Jar files.

// Create the Eclipse workspace object var wos = new EclipseWorkspace( new File("/home/me/myproject")); // Read information about which classes to put in which Jar files from a // property file. The example uses an inline file for pedagogic reasons. var buildProps = PropertiesUtil.loadFromFile( new CharSequenceReadableFile( "jar.foo.projects = MyProject_foo\n" + "jar.bar.projects = MyProject_bar\n" + "jar.test.projects = MyProject_*_test")); // Create a directory entity for the target directory. Make it read/write. var targetDir = SchmantFileSystems.getEntityForDirectory( new File("/tmp/target"), false); // Create a directory to put the Jar files in var libDir = Directories.newDirectory(targetDir, "lib"); // Create a TaskExecutor to use two threads for running the // tasks. var te = new TaskExecutor(). setNumberOfThreads(2); te.start(); try { // Build all Java projects var buildWorkspaceTask = new JavaWorkspaceBuilderTF(). setWorkspace(wos). // // Put class files for each project in a separate directory. setProjectSpecificTargetDirectories(true). setCopyNonJavaSourceFilesToTarget(true). // Set a task executor to spread out the compiling over several threads setTaskExecutor(te). setTarget(new File("/tmp/target")).create(); te.add(buildWorkspaceTask); // We have to wait for the workspace builder task to finish before we create // the Jar files var buildWorkspaceDependency = buildWorkspaceTask.getDependencyForTasksScheduledByThisTask(); // Get all build properties that have to do with where the classes should be // put var jarPropsItr = buildProps. getPropertiesMatching(new Glob("jar.*.projects")). propertyEntrySet(). iterator(); while(jarPropsItr.hasNext()) { var jarProp = jarPropsItr.next(); // The name of the Jar is the second segment of the property name var jarName = jarProp.getKey().split("\\.")[1]; var projectNamePattern = jarProp.getValue(); // Use a closure to get the source directories. It will be evaluated when // the task runs. Since the task depends on the workspace build task, all // target directories will be created by then. var jarTask = new JarTF(). addSources( function() { // Get all project names that match the Jar pattern return Directories.getAllDirectoriesMatching( targetDir, new Glob(projectNamePattern)); } ). setTarget(new FutureFile(libDir, "myproject-" + jarName + ".jar")). setLevel(9).create(); te.add(jarTask, buildWorkspaceDependency); } te.waitFor(); } finally { te.shutdown(); }

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