codepro.preprocessor
A simple java preprocessor that copies java source files from a source
directory tree to a destination tree directory. Each java source
file is scanned for specifically formatted comments and the source file is
modified based upon those comments before it is saved into the destination
directory tree.
There are several Ant properties that must be defined
- The "codepro.preprocessor.version.valid" property defines the valid
values for "version" that can appear in the java source code. The
valid version are separated by commas. Some valid versions include
"1.0", "2.0.1", "2.1", etc.
- The "codepro.preprocessor.version.source" property defines the version
for which the current java source files are defined. In other words,
the source files, before preprocessing, are coded for a specific version
and this property defines that version. Valid source versions
include "1.0", "2.0.1", "2.1", etc.
- The "codepro.preprocessor.version.target" property defines the version
for which the preprocessed files are to be generated. In other
words, the source files, after preprocessing, will be modified for a
specific version and this property defines that version. Valid
target versions include "1.0", "2.0.1", "2.1", etc.
Alternately, the target version can be specified via the "targetVersion"
attribute (e.g. <codepro.preprocessor targetVersion="2.1" dir=....... />)
There are several attributes that must be defined
- The "dir" attribute must be specified indicating the location of the
source file(s). Alternately, one or more
FileSets
may be defined specifying the source file(s).
- The "todir" attribute must be specified indicating where destination
files should be placed. If the source location and the destination
location are the same, then only those files whose content changes will be
modified.
Preprocessor statements in Java source files:
A valid preprocessor comment imbedded in a java source file takes the
following form:
- [/*] $codepro.preprocessor.<flowToken>[ version <comparisonToken>
<constant> ]$ [*/]
where
- the leading "/*" is required or forbidden based upon the operation and
source version
- the "<flowToken>" is one of the following: "if", "elseif", "endif"
- the "<comparisonToken>" is one of the following: ">", ">=", "==",
"<=", "<", "!="
- the "<constant>" is a version identifier such as 2.0 or 2.0.1
or the keyword "dev"
- the trailing "*/" is required or forbidden based upon the operation
and source version
The "dev" keyword is used to indicate development time artifacts or
non-development time artifacts and can only be used with the "==" and "!="
comparisonTokens. For example, if there is code that exclusively for
use during development in the runtime workbench and should not exist in the
shipping product, then use "== dev". In addition, if there is code
that is not for use during development in the runtime workbench and should
exist only in the shipping product, then use "!= dev".
For example, if the source version is "2.0.1" (in other words, the Ant
property "codepro.preprocessor.version.source" has a value of "2.0.1"), then
the following java source code snippet would be legal:
/* $codepro.preprocessor.if version > 2.0.1 $
... some code for version 2.1 here ...
$codepro.preprocessor.elseif version == 2.0.1 $ */
... some code for version 2.0.1 here ...
/* $codepro.preprocessor.elseif version < 2.0.1 $
... some code for version 1.0 here ...
$codepro.preprocessor.endif$ */
Note that in the code snippet above, the section that is uncommented
matches the indicated source version of "2.0.1" and all others are commented
so that they will not compile. In summary, if the version expression
evaluates true for the current source version, then the bracketed source
code must be uncommented, otherwise it must be commented.
Preprocessor statements in XML files:
A valid preprocessor comment imbedded in a xml file takes the
following form:
- [<!--] $codepro.preprocessor.<flowToken>[ version <comparisonToken>
<constant> ]$ [-->]
where
- the leading "<!--" is required or forbidden based upon the operation and
source version
- the "<flowToken>" is one of the following: "if", "elseif", "endif"
- the "<comparisonToken>" is one of the following: ">", ">=", "==",
"<=", "<", "!="
- the "<constant>" is a version identifier such as 2.0 or 2.0.1
or the keyword "dev"
- the trailing "-->" is required or forbidden based upon the operation
and source version
The "dev" keyword is used to indicate development time artifacts or
non-development time artifacts and can only be used with the "==" and "!="
comparisonTokens. For example, if there is code that exclusively for
use during development in the runtime workbench and should not exist in the
shipping product, then use "== dev". In addition, if there is code
that is not for use during development in the runtime workbench and should
exist only in the shipping product, then use "!= dev".
For example, if the source version is "2.0.1" (in other words, the Ant
property "codepro.preprocessor.version.source" has a value of "2.0.1"), then
the following xml snippet would be legal:
<!-- $codepro.preprocessor.if version > 2.0.1 $
... some code for version 2.1 here ...
$codepro.preprocessor.elseif version == 2.0.1 $ -->
... some code for version 2.0.1 here ...
<!-- $codepro.preprocessor.elseif version < 2.0.1 $
... some code for version 1.0 here ...
$codepro.preprocessor.endif$ -->
Note that in the code snippet above, the section that is uncommented
matches the indicated source version of "2.0.1" and all others are commented
so that they will not compile. In summary, if the version expression
evaluates true for the current source version, then the bracketed source
code must be uncommented, otherwise it must be commented.
Limitations:
- Preprocessor statements cannot be nested
- Comments in xml files are not allowed between preprocessor statements,
but are allowed outside preprocessor if / elseif / end statement groups.
For example
<!-- ok to have a comment here -->
<!-- $codepro.preprocessor.if version > 2.0.1 $
<!-- cannot have a comment here -->
... some code for version 2.1 here ...
$codepro.preprocessor.endif$ -->
<!-- ok to have a comment here -->
- Single line comments in java source files are allowed between
preprocessor statements, but multiline comments are not allowed. In
other words, multiline comments are allowed before an "if" preprocessor
statement and after an "end" preprocessor statement, but not in between.
For example
Valid:/* $codepro.preprocessor.if version > 2.0.1 $
// First comment line
// Second comment line
... some code for version 2.1 here ...
$codepro.preprocessor.endif$ */
Invalid:
/* $codepro.preprocessor.if version > 2.0.1 $
/*
* First comment line
* Second comment line
*/
... some code for version 2.1 here ...
$codepro.preprocessor.endif$ */
Example Ant script snippet:
<property name="codepro.preprocessor.version.valid" value="1.0,2.0.1,2.1"/>
<property name="codepro.preprocessor.version.source" value="2.0.1"/>
<property name="codepro.preprocessor.version.target" value="2.1"/>
<codepro.preprocessor
dir="foo\my_source_directory"
todir="bar\my_destination_directory">
Each of the statements in the above snippet of code is described
below:
- The "codepro.preprocessor.version.valid" property defines the valid
values for "version" that can appear in the java source code. In
this case, the are "1.0", "2.0.1", and "2.1"
- The "codepro.preprocessor.version.source" property defines the
version for which the current java source files are defined. In
this case, the source files are coded for version "2.0.1" indicating
that any block of code bracketed by codepro.preprocessor statements
should be commented out if the version specified does not match "2.0.1"
and should be uncommented if the version specified matches "2.0.1".
- The "codepro.preprocessor.version.target" property defines the
version for which the preprocessed files are to be generated. In
this case, the existing version 2.0.1 java source is to be preprocessed
into version "2.1" java source. In other words, any statements
bracketed by codepro.preprocessor statements that match version "2.1"
will be modified to be uncommented, while all others will be modified to
be commented. Alternately, the target version can be specified via
the targetVersion attribute, as in the example below
<codepro.preprocessor
targetVersion="2.1"
dir="foo\my_source_directory"
todir="bar\my_destination_directory">
- The "codepro.preprocessor" directive indicates that all *.java files
in "foo\my_source_directory" and its subdirectories should be
preprocessed and copied into the corresponding subfolder in "bar\my_destination_directory".
- Alternately, a single file can be specified using the "file"
attribute rather than the "dir" attribute.
Example java source snippet:
public void myMethod(String arg1) {
/* $codepro.preprocessor.if version > 2.0.1 $
myField = arg1 + " some version greater than 2.0.1";
$codepro.preprocessor.elseif version == 2.0.1 $ */
myField = arg1 + " version is 2.0.1";
/* $codepro.preprocessor.elseif version < 2.0.1 $
myField = arg1 + " some version less than 2.0.1";
$codepro.preprocessor.endif$ */
}
In the code above, if the target version was "2.1" (in other words,
the Ant property "codepro.preprocessor.version.target" has the value
"2.1"), then preprocessor would uncomment the code segment starting with
"/* $codepro.preprocessor.start: version > 2.0.1 $" and all other
segments would be commented. |