Jsp2Jspx Maven Plugin

Jsp2Jspx Maven plugin handles the conversion of JSP pages to JSP documents, i.e. JSPs in well-formed XML syntax. Making JSP files XML-compliant opens plenty of possibilities for further processing. For instance, if you don’t like some XML document, you can change it with the help of XSL transformations. Indeed, one of the practical applications of this plugin is the automatic conversion of plain JSP pages to Facelets/JSF format, which is yet to be defined, can be relatively easy achieved in 2 steps:

let the jsp2jspx plugin handle JSP to JSPX conversion;
apply extra XSL transformation to get the desired structure of your Facelets/JSF pages.

The idea of this plugin was inspired by Jsp2X open source project.

Plugin Documentation

Usage

To run the plugin, simply call from the command line:

mvn jsp2jspx:jsp2jspx

The following example demonstrates a basic plugin configuration:

<build>
  ...
  <plugins>
    ...
    <plugin>
      <groupId>com.edb.maven.plugins</groupId>
      <artifactId>jsp2jspx-maven-plugin</artifactId>
      <version>1.0.4</version>
      <configuration>
        <sourceDirectory>src/test/resources/jsp</sourceDirectory>
        <outputDirectory>${project.build.directory}/jspx</outputDirectory>
        <inputEncoding>ISO-8859-1</inputEncoding>
        <outputEncoding>UTF-8</outputEncoding>
        <includes>
          <!-- Include all files -->
          <include>**/*.*</include>
        </includes>
        <excludes>
          <!-- But exclude JSP fragments -->
          <exclude>**/*.jspf</exclude>
        </excludes>
      </configuration>
    </plugin>
    ...
  </plugins>
  ...
</build>

Required Parameters

Name	Type	Description
sourceDirectory	File	The base directory where the JSP pages are located. Default value is: `${project.basedir}/src/main/webapp/WEB-INF/jsp`
outputDirectory	File	The directory where the files generated by Jsp2Jspx tool will be stored. Default value is: `${project.build.directory}/generated-sources/jspx`
inputEncoding	String	Specifies the encoding set for JSP files. If not specified, the inputEncoding value will be UTF-8
outputEncoding	String	Specifies the encoding for the generated JSPX files. If not specified, the `outputEncoding` value will be the value of the `inputEncoding` attribute.
includes	String[]	A set of Ant-like inclusion patterns used to select files from the source directory for processing. By default, the patterns `*/.jsp`, `*/.jspf` and `*/.tag` are used to select JSP files.
excludes	String[]	A set of Ant-like exclusion patterns used to prevent certain files from being processed. By default, this set is empty such that no files are excluded.

Technical Overview

JSP to JSPX Transformation Flow

The following section specifies the actual routine that makes JSP to JSPX transformation possible.

A conversion of a single JSP page involves a number of different transformations:

Wrap the entire content of a JSP page in <jsp:root> tag.
If a page is actually a JSP fragment, wrap it in <jspx:fragment> tag.
Detect all taglib declarations and convert them to name space references on the new root element (either <jsp:root> or <jspx:fragment>). Unused taglibs get ignored.
Wrap JSP scriptlets and expressions in <jsp:scriptlet> and <jsp:expression> tags respectively.
Wrap pure text in <jsp:text> tag.
Convert JSP comments (<%-- JSP-style comment --%>) to XML comments ().
Escape some special XML characters in the input: “&”, “<” and “>”. For more information, please see List of XML and HTML character entity references page.
Save converted input to an output file which name is derived from the input file. The extension of mapped according to the JSP standard:
- JSP page -> *.jspx
- JSP fragment -> *.jspfx
- JSP tag -> *.tagx

Implementation Details

The plugin logically consists of 4 main parts:

JSP Syntax Tree – a tree representation of syntactic structure of a JSP page.
Parser takes an input JSP file and builds a JSP Syntax Tree in memory.
Transformer defines a transformation to be applied to a JSP Syntax Tree. It is implemented as a recursive tree walker that can change, delete or add nodes during a walk.
JSP Syntax Tree Serializer is responsible for storing (serializing) transformed JSP Syntax Tree to an output file.

The main class that glues all this stuff is called Jsp2JspxTool. This class encapsulates all the logic as it is described in JSP to JSPX Transformation Flow section. A client code (e.g. Maven’s Mojo) generally needs to instantiate Jsp2JspxTool object and call its convert() method in order to convert a single JSP file to a JSPX document.

The following diagram illustrates how the high-level sub-components collaborate with each other to implement the transformation flow:

The below diagram shows how AbstractSyntaxTreeTransformation is organized in the flow:

Generating JSP parser and JSP syntax tree serializer with ANTLR

The plugin uses ANTLR parser generator to generate Java code for Jsp Parser and Jsp Syntax Tree Serializer sub-components (see Implementation Details section).

The ANTLR grammar files from which Jsp Parser and Jsp Syntax Tree Serializer will be generated are located under src/main/antlr folder.

If you make changes in ANTLR grammar files (either Jsp.g or JspSyntaxTreeSerializer.g), you need to regenerate Java code for the parsers. To do so, call the following goal from the project root:

mvn generate-sources

This will generate a series of files under target/generated-sources/antlr folder.

dkoval/jsp2jspx-maven-plugin