org.myire.munge.transform

Class TransformationSet

java.lang.Object

org.myire.munge.transform.TransformationSet

Direct Known Subclasses:

FreeMarkerTransformationSet, SaxonTransformationSet

public abstract class TransformationSet
extends java.lang.Object

A TransformationSet transforms source files by applying templates loaded from template files. The result is written to output files.

Source and template files can be specified either as paths to files or directories, or as a path to a directory with a configuration closure, which operates on a PatternFilterable. Relative paths are resolved relative to the project directory.

The output file for a transformation can be specified in several ways:

• The output can be directed to a single file, specified with setOutputFile(Object). If the transformation set contains several transformations, the effect of specifying a single output file is implementation specific.
• The output files can be created in an specific directory, specified with setOutputDir(Object). The name of the output file will be the same as the name of the transformation's source file.
• The output file can be specified by a Closure applied to the source and template file paths of the transformation. The Closure either returns an object specifying the output file of the transformation or null if there should be no explicit output file. In the former case the returned object is resolved with Project::file().

The above variants can be combined. Multiple closures can be added to the output file specification, and they will be called in the order they were added until one returns a non-null value. If all closures return null, the directory or file variant will be used. Should both an output directory and an output file be specified, the former takes precedence.

It is possible to pass parameters to the transformations. This is done by calling parameter(String, Object).

Example of a configuration closure for a transformation set:

     {
         source 'src.xml'
         sources ('srcDir')
         {
           include '*.xml'
         }

         templates 'a.xsl', 'rsrc/b.xsl'
         templates ('templatesDir')
         {
           exclude 'common.xsl'
         }

         outputDir = 'dst'
         outputMapping {
           s, t ->
             if (s.name.startsWith('xyz'))
               'dst/' + s.name + '-' + t.name
             else
               null
         }

         parameters(
           'stringParam': 'value',
           'intParam': 17
         )
     }

Field Summary

Fields

Modifier and Type	Field and Description
protected org.gradle.api.Project	fProject

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TransformationSet(org.gradle.api.Project pProject) Create a new TransformationSet.

Method Summary

Modifier and Type	Method and Description
TransformationSet	configure(groovy.lang.Closure<?> pClosure) Configure this transformation set through a Closure.
protected abstract Transformer	createTransformer(java.lang.ClassLoader pClassLoader) Create the Transformer instance associated with this transformer set.
void	dynamicOutputDirectory(java.lang.Object pDirectoryPath) Specify a directory where the transformations are known to generate dynamic output.
java.io.File	getConfigurationFile() Get the file to configure the underlying transformer with before executing the transformations.
org.gradle.api.file.FileCollection	getDynamicOutputDirectories() Get the directories specified as dynamic output directory.
java.util.List<java.io.File>	getMappedOutputFiles() Get the output file specifications produced by applying all output mappings to the pairs of source and template files.
java.io.File	getOutputDir()
java.io.File	getOutputFile()
java.util.Map<java.lang.String,java.lang.Object>	getParameters() Get the parameters specified for the transformations.
org.gradle.api.file.FileCollection	getSourceFiles() Get the source files that each template file will be applied to.
org.gradle.api.file.FileCollection	getTemplateFiles() Get the template files that will be applied to each source.
void	outputMapping(groovy.lang.Closure<?> pClosure) Add a closure that maps a source file and a template file to an output file.
void	parameter(java.lang.String pName, java.lang.Object pValue) Add a parameter that will be passed to each template when it is applied to a source file.
void	parameters(java.util.Map<java.lang.String,java.lang.Object> pParameters) Add parameters that will be passed to each template when it is applied to a source file.
void	setConfigurationFile(java.lang.Object pFile)
void	setOutputDir(java.lang.Object pDirectoryPath) Specify a directory to create output files in for transformations that don't have an explicit output mapping.
void	setOutputFile(java.lang.Object pFilePath) Specify a single file to write all output to for transformations that don't have an explicit output mapping.
void	source(java.lang.Object pPath) Add a source file or directory to the transformation set.
void	sources(java.lang.Object... pPaths) Add multiple source files and/or directories to the transformation set.
void	sources(java.lang.Object pDirectoryPath, groovy.lang.Closure<?> pConfigClosure) Add a source file directory to the transformation set and specify which of its files to include and/or exclude through a Closure.
void	template(java.lang.Object pPath) Add a template file or directory to the transformation set.
void	templates(java.lang.Object... pPaths) Add multiple template files to the transformation set.
void	templates(java.lang.Object pDirectoryPath, groovy.lang.Closure<?> pConfigClosure) Add a template file directory to the transformation set and specify which of its files to include and/or exclude through a Closure.
int	transform(java.lang.ClassLoader pTransformerClassLoader) Execute all transformations in this set.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

fProject

protected final org.gradle.api.Project fProject

Constructor Detail

TransformationSet

protected TransformationSet(org.gradle.api.Project pProject)

Create a new TransformationSet.

Parameters:

pProject - The project to resolve file paths with.

Throws:

java.lang.NullPointerException - if pProject is null.

Method Detail

getConfigurationFile

@InputFile
 @Optional
public java.io.File getConfigurationFile()

Get the file to configure the underlying transformer with before executing the transformations.

Returns:

The configuration file, or null to use a default configuration.

setConfigurationFile

public void setConfigurationFile(java.lang.Object pFile)

getSourceFiles

@InputFiles
public org.gradle.api.file.FileCollection getSourceFiles()

Get the source files that each template file will be applied to.

Returns:

The source files, never null.

getTemplateFiles

@InputFiles
public org.gradle.api.file.FileCollection getTemplateFiles()

Get the template files that will be applied to each source.

Returns:

The template files, never null.

getOutputFile

@OutputFile
 @Optional
public java.io.File getOutputFile()

getOutputDir

@OutputDirectory
 @Optional
public java.io.File getOutputDir()

getMappedOutputFiles

@OutputFiles
public java.util.List<java.io.File> getMappedOutputFiles()

Get the output file specifications produced by applying all output mappings to the pairs of source and template files.

This property is read-only and intended to be used by the Gradle up-to-date check.

Returns:

The file specifications from the output mappings, possibly empty, never null.

getDynamicOutputDirectories

@OutputDirectories
public org.gradle.api.file.FileCollection getDynamicOutputDirectories()

Get the directories specified as dynamic output directory. A dynamic output directory is a directory where a template creates files without an explicit configuration in the transformation set. These directories need to be marked as output directories for the up-to-date checks to work properly.

Returns:

The dynamic output directories, possibly empty, never null.

getParameters

@Input
public java.util.Map<java.lang.String,java.lang.Object> getParameters()

Get the parameters specified for the transformations.

Returns:

The parameters, possibly empty, never null.

source

public void source(java.lang.Object pPath)

Add a source file or directory to the transformation set. If the path specifies a directory, all of its files, including files in any subdirectories, will be added as source files.

Parameters:

pPath - An object that resolves to a file or directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved.

Throws:

java.lang.NullPointerException - if pPath is null.

sources

public void sources(java.lang.Object... pPaths)

Add multiple source files and/or directories to the transformation set.

Parameters:

pPaths - An array of objects that resolve to files and/or directories. See the documentation of org.gradle.api.Project::files() for the possible types that can be resolved.

Throws:

java.lang.NullPointerException - if pPaths is null.

sources

public void sources(java.lang.Object pDirectoryPath,
                    groovy.lang.Closure<?> pConfigClosure)

Add a source file directory to the transformation set and specify which of its files to include and/or exclude through a Closure.

Parameters:

pDirectoryPath - An object that resolves to a directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved.

pConfigClosure - A closure that configures a PatternFilterable.

Throws:

java.lang.NullPointerException - if any of the parameters is null.

template

public void template(java.lang.Object pPath)

Add a template file or directory to the transformation set. If the path specifies a directory, all of its files, including files in any subdirectories, will be added as template files.

Parameters:

pPath - An object that resolves to a file or directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved.

Throws:

java.lang.NullPointerException - if pPath is null.

templates

public void templates(java.lang.Object... pPaths)

Add multiple template files to the transformation set.

Parameters:

pPaths - An array of objects that resolve to files and/or directories. See the documentation of org.gradle.api.Project::files() for the possible types that can be resolved.

Throws:

java.lang.NullPointerException - if pPaths is null.

templates

public void templates(java.lang.Object pDirectoryPath,
                      groovy.lang.Closure<?> pConfigClosure)

Add a template file directory to the transformation set and specify which of its files to include and/or exclude through a Closure.

Parameters:

pDirectoryPath - An object that resolves to a directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved.

pConfigClosure - A closure that configures a PatternFilterable.

Throws:

java.lang.NullPointerException - if any of the parameters is null.

setOutputFile

public void setOutputFile(java.lang.Object pFilePath)

Specify a single file to write all output to for transformations that don't have an explicit output mapping.

Parameters:

pFilePath - An object that resolves to a file. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved. Null means no output file.

setOutputDir

public void setOutputDir(java.lang.Object pDirectoryPath)

Specify a directory to create output files in for transformations that don't have an explicit output mapping.

Parameters:

pDirectoryPath - An object that resolves to a directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved. Null means no output directory.

outputMapping

public void outputMapping(groovy.lang.Closure<?> pClosure)

Add a closure that maps a source file and a template file to an output file.

Parameters:

pClosure - The mapping closure.

Throws:

java.lang.NullPointerException - if pClosure is null.

parameter

public void parameter(java.lang.String pName,
                      java.lang.Object pValue)

Add a parameter that will be passed to each template when it is applied to a source file.

Parameters:

pName - The parameter's name.

pValue - The parameter's value.

Throws:

java.lang.NullPointerException - if pName is null.

parameters

public void parameters(java.util.Map<java.lang.String,java.lang.Object> pParameters)

Add parameters that will be passed to each template when it is applied to a source file.

Parameters:

pParameters - The parameters to add.

Throws:

java.lang.NullPointerException - if pParameters is null.

dynamicOutputDirectory

public void dynamicOutputDirectory(java.lang.Object pDirectoryPath)

Specify a directory where the transformations are known to generate dynamic output.

Parameters:

pDirectoryPath - An object that resolves to a directory. See the documentation of org.gradle.api.Project::file() for the possible types that can be resolved.

Throws:

java.lang.NullPointerException - if pDirectoryPath is null.

configure

public TransformationSet configure(groovy.lang.Closure<?> pClosure)

Configure this transformation set through a Closure.

Parameters:

pClosure - The configuration closure.

Returns:

This instance.

transform

public int transform(java.lang.ClassLoader pTransformerClassLoader)

Execute all transformations in this set. Each template file will be loaded and applied to each source file, and the result will be written to the output file specified by the output mappings or the output directory/file.

Parameters:

pTransformerClassLoader - The class loader to load Transformer implementations with.

Returns:

The number of errors encountered during the transformations.

createTransformer

protected abstract Transformer createTransformer(java.lang.ClassLoader pClassLoader)
                                          throws java.lang.ReflectiveOperationException

Create the Transformer instance associated with this transformer set.

Parameters:

pClassLoader - The class loader with which to load the Transformer implementation class.

Returns:

A new Transformer instance, never null.

Throws:

java.lang.ReflectiveOperationException - if the Transformer implementation class isn't available or cannot be instantiated.