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.