Changelog

• 7.0.0 (31 mar 2019)

  • reworked some parameters for Maven and ANT plug-ins
  • added embedded Gradle plugin com.igormaznitsa.jcp
  • added function STR esc(STR)
  • fixed build under JDK 9+
  • XML functions work through embedded Apache Xalan and Apache Xerces
  • minimal needed Java version changed to 1.8
  • refactoring

• 6.1.4 (16 jun 2018)

  • #19 removed dependencies to meta packages (their sources moved into project)

Full changelog

Introduction

I guess it is most powerful preprocessor for Java because it is a multi-pass one and can work with XML files as data sources. The First version of the preprocessor was published in 2003 and it was very actively used for J2ME developments. Modern version can be used for any kind of Java project because it can be used with ANT, MAVEN and Gradle. Because JDK-9 has supported JEP-238, the preprocessor is useful to generate multi-version JARs, there is example of a maven project which generates JEP-238 JAR for two versions of JDK.

How to use

The Full list of the preprocessor directives can be found in the wiki.

The Preprocessor can be used by different ways:

• as ANT task, and with Android SDK
• as Maven plugin
• with Gradle through ANT task
• as Java framework with direct class calls
• as external utility through CLI (command line interface) The Preprocessor is published in the Maven Central so that can be added in Maven projects without any problems

    <build>
        <plugins>
...
           <plugin>
                <groupId>com.igormaznitsa</groupId>
                <artifactId>jcp</artifactId>
                <version>6.1.4</version>
                <executions>
                    <execution>
                        <id>preprocessSources</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>preprocess</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>clearGeneratedFolders</id>
                        <goals>
                            <goal>clear</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
...
        </plugins>
    </build>    

How to use from command line

The Preprocessor jar can be started under Java as a console application. Let's take a look at short example below how to start in command line under Linux The Easy variant of usage:

java -jar jcp-6.1.4.jar  --i:./test --o:./result

The Example just preprocess files from ./test folder which extensions allowed to be preprocessed by default, and places result into ./result folder, but keep in your mind that the preprocessor copies not all files, XML files will not be preprocessed by default. Files which extension are not marked for preprocessing will be just copied (of course if the extensions is not in the list of excluded file extensions)

More complex example:

java -jar jcp-6.1.4.jar  --c --r --v --f:java,xml --ef:none --i:./test --o:./result  '--p:HelloWorld=$Hello world$'

• --c clear the destination folder before work
• --r remove all Java-style comments from preprocessed result files
• --v show verbose log about preprocessing process
• --f include .java and .xml files into preprocessing (by default the preprocessor doesn't preprocess XNL files and the extension should to be defined explicitly)
• --ef don't exclude any extension from preprocessing
• --i use ./test as source folder
• --o use ./result as destination folder
• --p define named global variable HelloWorld? with the 'Hello world' content
• --z turn on checking of file content before replacement, if the same content then preprocessor will not replace the file
• --es allow whitespace between comment and directive (by default it is turned off)

The Main idea

The Java language was born without any preprocessor in creator's mind and even now there are not any plans to include preprocessing into Java. It was good until mass usage Java on mobile and TV devices where we have bunches of half-compatible devices with (sometime) very bizarre standard framework implementations. In the case, preprocessing allows to decrease support of sources dramatically.
The only possible way to include preprocessing directives into Java and to not break standard processes and Java tool chain is to inject them into comments, take a look at the example below:

//#local TESTVAR="TEST LOCAL VARIABLE"
//#echo TESTVAR=/*$TESTVAR$*/
//#include "./test/_MainProcedure.java"

public static final void testproc()
{
 System.out.println(/*$VARHELLO$*/);
 System.out.println("// Hello commentaries");
 //#local counter=10
        //#while counter!=0
        System.out.println("Number /*$counter$*/");
        //#local counter=counter-1
        //#end
 System.out.println("Current file name is /*$SRV_CUR_FILE$*/");
 System.out.println("Output dir is /*$SRV_OUT_DIR$*/");
 //#if issubstr("Hello","Hello world")
 System.out.println("Substring found");
 //#endif
}

Multi-sectioned documents

Java sources usually have sections, there are the import section and the main section thus JCP has support for such case and there are three section where the preprocessor can write results - the prefix, the middle part and the postfix. Usually I use the prefix to form the import section for Java files. You can switch the text output for sections with //#prefix[+|-] and //#postfix[+|-] directives.

//#prefix+
 import java.lang.*;
 //#prefix-
 public class Main {
  //#prefix+
  import java.util.*;
  //#prefix-
  public static void main(String ... args){}
 }

How to remove all coments from sources

Sometime it is very useful to remove all comments from my sources at all, JCP has such feature which can be turned on by special flag or command line switcher (see wiki). The Example of use for comment removing through CLI interface

java -jar ./jcp-6.1.4.jar --i:/sourceFolder --o:/resultFolder -ef:none --r