net.uworks.andariel
Class Process

java.lang.Object
  extended byorg.apache.tools.ant.ProjectComponent
      extended byorg.apache.tools.ant.Task
          extended bynet.uworks.andariel.Process

public class Process
extends org.apache.tools.ant.Task

Task definition for an ANT task that process files, parsing established directives.

It will take all the parameters defined by the Ant Copy task (manual information), except for "filterset" and "filterchain".

The difference between the Process task and other pre-processing utilities for Java is that this task has been designed to be able to hide from the compiler, so, if used properly, it's still possible to compile the original source tree with whatever compiler we're using, and generate any necessary versions using this task. This can be useful when developing in a IDE, or also when it's absolutely necessary to remove certain code, which can be useful in, for instance, J2ME.

Each processing directive is defined inside a comment, followed by the escape sequence. The type of comment and the escape sequence to be used is defined in the call of the task. Currently, the available types are:

CodeSample
slash-asterisk/* [...] */
slash-slash// [...] [EOL]
xml<!-- [...] -->
hash# [...] [EOL]
bracket{ [...] }
quote' [...] [EOL]
remrem [...] [EOL]
at@ [...] [EOL]
Note: [EOL] represents End-Of-Line

The escape sequence is "#" by default, so, when using the default settings, a directive would look like:

 
 /*#echo propertyName */
 
 

The available directives are:

CodeArgumentDescription
echoProperty name (mandatory)The specified Ant property is written into the processed file
includeFile name (mandatory)The specified file is inserted into the processed file
defineProperty name (mandatory), equal sign and property value (optional)Defines a new Ant property. If no value is specifed, the property will be initalized to empty string
commentComment type (optional)The lines between this directive and the next "endcomment" directive are commented using the specified comment type, which take one of the values of the last table. If no type is defined, it will use the current task type
endcommentNoneEnd the comment process
uncommentComment type (optional)The lines between this directive and the next "endcomment" directive are uncommented using the specified comment type, which take one of the values of the last table. If no type is defined, it will use the current task type
enduncommentNoneEnd the uncomment process
ifLogical expressionDefines a condition. Works like a regular logical expression, where the variables are the Ant properties. Ends with the "endif" directive. Multiple "if" directives can be nested.
elseifLogical expressionMust be defined after a "if" directive. It will recheck the logical expression in case the original directive failed. Any number of "elseif" directive can be present for each "if".
elseNoneIn the case that "if" and "elseif" directives cannot validate the condition, the processing will continue from here.
endifNoneEnds the conditional processing flow.


 Usage:

   Task declaration in the project:
   
     <taskdef name="process" classname="net.uworks.andariel.Process" />
   

   Task calling syntax:
    
     <process file="originalFile" toFile="destinationFile" [processType="type"] [escapeSequence="sequence"] />
    


   Attributes:
       file            -> The filename we want to process
       toFile          -> The destination filename of the processed file
       processType     -> One of the process types specified above. By default is "slash-asterisk"
       escapeSequence  -> A String containing the sequence we want to use to define a process directive. By default is "#"
       selfProcessing  -> Defines if it's allowed to overwrite itself. Must be used with "overwrite" to true to have any effect. By default is false
   Note: Any attribute of the "Copy" task can be used, except for "filterset" and "filterchain".


 Crude Example:

     
     <process file="toprocess.xml" toFile="processed.xml" processType="xml" escapeSequence="#" />
     

 

Since:
Ant 1.5
Version:
$Revision: 1.0 $
Author:
Josep del Rio

Field Summary
protected  java.util.Hashtable completeDirMap
           
protected  java.io.File destDir
           
protected  java.io.File destFile
           
protected  java.util.Hashtable dirProcessMap
           
protected  boolean failonerror
           
protected  java.io.File file
           
protected  java.util.Hashtable fileProcessMap
           
protected  java.util.Vector filesets
           
protected  org.apache.tools.ant.util.FileUtils fileUtils
           
protected  boolean flatten
           
protected  boolean forceOverwrite
           
protected  boolean includeEmpty
           
protected  org.apache.tools.ant.types.Mapper mapperElement
           
protected  boolean preserveLastModified
           
protected  int verbosity
           
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
Process()
          Process task constructor.
 
Method Summary
 void add(org.apache.tools.ant.util.FileNameMapper fileNameMapper)
          A nested filenamemapper
 void addFileset(org.apache.tools.ant.types.FileSet set)
          Adds a set of files to process.
protected  void buildMap(java.io.File fromDir, java.io.File toDir, java.lang.String[] names, org.apache.tools.ant.util.FileNameMapper mapper, java.util.Hashtable map)
          Add to a map of files/directories to process
 org.apache.tools.ant.types.Mapper createMapper()
          Defines the mapper to map source to destination files.
protected  void doFileOperations()
          Actually does the file (and possibly empty directory) copies.
 void execute()
          Performs the process operation.
 java.lang.String getEncoding()
           
protected  org.apache.tools.ant.util.FileUtils getFileUtils()
           
 java.lang.String getOutputEncoding()
           
 boolean getPreserveLastModified()
          Whether to give the copied files the same last modified time as the original files.
 boolean isEnableMultipleMapping()
           
protected  void scan(java.io.File fromDir, java.io.File toDir, java.lang.String[] files, java.lang.String[] dirs)
          Compares source files to destination files to see if they should be copied.
 void setEnableMultipleMappings(boolean enableMultipleMappings)
          Attribute to handle mappers that return multiple mappings for a given source path.
 void setEncoding(java.lang.String encoding)
          Sets the character encoding
 void setEscapeSequence(java.lang.String sequence)
          The escape sequence that will be used to distinguish between normal comments and processing comments.
 void setFailOnError(boolean failonerror)
          If false, note errors to the output but keep going.
 void setFile(java.io.File file)
          Sets a single source file to process.
 void setFlatten(boolean flatten)
          When processing directory trees, the files can be "flattened" into a single directory.
 void setGranularity(long granularity)
          The number of milliseconds leeway to give before deciding a target is out of date.
 void setIncludeEmptyDirs(boolean includeEmpty)
          Used to process empty directories.
 void setOutputEncoding(java.lang.String encoding)
          Sets the character encoding for output files.
 void setOverwrite(boolean overwrite)
          Overwrite any existing destination file(s).
 void setPreserveLastModified(boolean preserve)
          Give the copied files the same last modified time as the original files.
 void setPreserveLastModified(java.lang.String preserve)
          Deprecated. setPreserveLastModified(String) has been deprecated and replaced with setPreserveLastModified(boolean) to consistently let the Introspection mechanism work.
 void setProcessType(java.lang.String type)
          The type of processing instructions.
 void setSelfProcessing(boolean selfProcessing)
          Defines if we can overwrite the file that is being processed.
 void setTodir(java.io.File destDir)
          Sets the destination directory.
 void setTofile(java.io.File destFile)
          Sets the destination file.
 void setVerbose(boolean verbose)
          Used to force listing of all names of copied files.
protected  void validateAttributes()
          Ensure we have a consistent and legal set of attributes, and set any internal flags necessary based on different combinations of attributes.
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

file

protected java.io.File file

destFile

protected java.io.File destFile

destDir

protected java.io.File destDir

filesets

protected java.util.Vector filesets

preserveLastModified

protected boolean preserveLastModified

forceOverwrite

protected boolean forceOverwrite

flatten

protected boolean flatten

verbosity

protected int verbosity

includeEmpty

protected boolean includeEmpty

failonerror

protected boolean failonerror

fileProcessMap

protected java.util.Hashtable fileProcessMap

dirProcessMap

protected java.util.Hashtable dirProcessMap

completeDirMap

protected java.util.Hashtable completeDirMap

mapperElement

protected org.apache.tools.ant.types.Mapper mapperElement

fileUtils

protected org.apache.tools.ant.util.FileUtils fileUtils
Constructor Detail

Process

public Process()
Process task constructor.

Method Detail

getFileUtils

protected org.apache.tools.ant.util.FileUtils getFileUtils()
Returns:
the fileutils object

setFile

public void setFile(java.io.File file)
Sets a single source file to process.

Parameters:
file - the file to process

setTofile

public void setTofile(java.io.File destFile)
Sets the destination file.

Parameters:
destFile - the file to process to

setTodir

public void setTodir(java.io.File destDir)
Sets the destination directory.

Parameters:
destDir - the destination directory

setPreserveLastModified

public void setPreserveLastModified(java.lang.String preserve)
Deprecated. setPreserveLastModified(String) has been deprecated and replaced with setPreserveLastModified(boolean) to consistently let the Introspection mechanism work.

Give the copied files the same last modified time as the original files.

Parameters:
preserve - a boolean string

setPreserveLastModified

public void setPreserveLastModified(boolean preserve)
Give the copied files the same last modified time as the original files.

Parameters:
preserve - if true perverse the modified time, default is false

getPreserveLastModified

public boolean getPreserveLastModified()
Whether to give the copied files the same last modified time as the original files.

Returns:
the preserveLastModified attribute
Since:
1.32, Ant 1.5

setOverwrite

public void setOverwrite(boolean overwrite)
Overwrite any existing destination file(s).

Parameters:
overwrite - if true force overwriting of destination file(s) even if the destination file(s) are younger than the corresponding source file. Default is false.

setFlatten

public void setFlatten(boolean flatten)
When processing directory trees, the files can be "flattened" into a single directory. If there are multiple files with the same name in the source directory tree, only the first file will be copied into the "flattened" directory, unless the forceoverwrite attribute is true.

Parameters:
flatten - if true flatten the destination directory. Default is false.

setVerbose

public void setVerbose(boolean verbose)
Used to force listing of all names of copied files.

Parameters:
verbose - output the names of copied files. Default is false.

setIncludeEmptyDirs

public void setIncludeEmptyDirs(boolean includeEmpty)
Used to process empty directories.

Parameters:
includeEmpty - if true process empty directories. Default is true.

setEnableMultipleMappings

public void setEnableMultipleMappings(boolean enableMultipleMappings)
Attribute to handle mappers that return multiple mappings for a given source path.

Parameters:
enableMultipleMappings - If true the task will process to all the mappings for a given source path, if false, only the first file or directory is processed. By default, this setting is false to provide backward compatibility with earlier releases.
Since:
1.6

isEnableMultipleMapping

public boolean isEnableMultipleMapping()
Returns:
the value of the enableMultipleMapping attribute

setFailOnError

public void setFailOnError(boolean failonerror)
If false, note errors to the output but keep going.

Parameters:
failonerror - true or false

addFileset

public void addFileset(org.apache.tools.ant.types.FileSet set)
Adds a set of files to process.

Parameters:
set - a set of files to process

createMapper

public org.apache.tools.ant.types.Mapper createMapper()
                                               throws org.apache.tools.ant.BuildException
Defines the mapper to map source to destination files.

Returns:
a mapper to be configured
Throws:
org.apache.tools.ant.BuildException - if more than one mapper is defined

add

public void add(org.apache.tools.ant.util.FileNameMapper fileNameMapper)
A nested filenamemapper

Parameters:
fileNameMapper - the mapper to add
Since:
Ant 1.6.3

setEncoding

public void setEncoding(java.lang.String encoding)
Sets the character encoding

Parameters:
encoding - the character encoding
Since:
1.32, Ant 1.5

getEncoding

public java.lang.String getEncoding()
Returns:
the character encoding, null if not set.
Since:
1.32, Ant 1.5

setOutputEncoding

public void setOutputEncoding(java.lang.String encoding)
Sets the character encoding for output files.

Parameters:
encoding - the character encoding
Since:
Ant 1.6

getOutputEncoding

public java.lang.String getOutputEncoding()
Returns:
the character encoding for output files, null if not set.
Since:
Ant 1.6

setGranularity

public void setGranularity(long granularity)
The number of milliseconds leeway to give before deciding a target is out of date.

Default is 0 milliseconds, or 2 seconds on DOS systems.

Since:
Ant 1.6.2

setProcessType

public void setProcessType(java.lang.String type)
The type of processing instructions. Can be "slash-asterisk", "slash-slash", "xml", "hash", "bracket", "quote", "rem", or "at".

Parameters:
type - the type of processing instructions.

setEscapeSequence

public void setEscapeSequence(java.lang.String sequence)
The escape sequence that will be used to distinguish between normal comments and processing comments.

Parameters:
sequence - the escape sequence .

setSelfProcessing

public void setSelfProcessing(boolean selfProcessing)
Defines if we can overwrite the file that is being processed.

Parameters:
selfProcessing - the new value.

execute

public void execute()
             throws org.apache.tools.ant.BuildException
Performs the process operation.

Throws:
org.apache.tools.ant.BuildException - if an error occurs

validateAttributes

protected void validateAttributes()
                           throws org.apache.tools.ant.BuildException
Ensure we have a consistent and legal set of attributes, and set any internal flags necessary based on different combinations of attributes.

Throws:
org.apache.tools.ant.BuildException - if an error occurs

scan

protected void scan(java.io.File fromDir,
                    java.io.File toDir,
                    java.lang.String[] files,
                    java.lang.String[] dirs)
Compares source files to destination files to see if they should be copied.

Parameters:
fromDir - The source directory
toDir - The destination directory
files - A list of files to process
dirs - A list of directories to process

buildMap

protected void buildMap(java.io.File fromDir,
                        java.io.File toDir,
                        java.lang.String[] names,
                        org.apache.tools.ant.util.FileNameMapper mapper,
                        java.util.Hashtable map)
Add to a map of files/directories to process

Parameters:
fromDir - the source directory
toDir - the destination directory
names - a list of filenames
mapper - a FileNameMapper value
map - a map of source file to array of destination files

doFileOperations

protected void doFileOperations()
Actually does the file (and possibly empty directory) copies. This is a good method for subclasses to override.