IBM WebSphere Developer Technical Journal: JavaServer Pages in WebSphere Application Server Technology for Developers V6 -- Part 1

Document options Document options requiring JavaScript are not displayed Sample code Rate this page Help us improve this content

Level: Intermediate

Scott Johnson (scottjoh@us.ibm.com)IBM WebSphere Application Server Development

19 Jan 2004

This article, the first in a three-part series, describes the internal operations of the batch compiler and explores the batch compiler configuration parameters that are available in WebSphere Application Server Technology for Developers V6.0. Also focused on WebSphere Application Server V6.0 TD, Part 2 will cover performance tuning the JSP Engine, and Part 3 will examine the architecture of the JavaServer Pages Engine.

Introduction

JavaServer Pages (JSPs) can be compiled during Web application development, before an application is deployed. Batch compilation of JSPs in a predeployed application simplifies the deployment process and improves the run time performance of JSPs by eliminating first-request compilations. The batch compiler also operates on enterprise applications that have been deployed into IBM WebSphere Application Server.

This article will describe the internal operations of the batch compiler, and will explore all of the batch compiler configuration parameters that are available in WebSphere Application Server Version 6.0 TD. Parts 2 and 3 of this series will cover performance tuning the JSP Engine and examining the architecture of the JavaServer Pages Engine, respectively, in WebSphere Application Server Technology for Developers V6.0 TD.

Back to top

Batch compiler operation

The batch compiler validates the syntax of JSPs, translates the JSPs into Java source files, and compiles the Java source files into Java Servlet classfiles. Similarly, it validates Tag files and generates their Java implementation classes.

The batch compiler has many configuration parameters that enable the application developer, or deployer, to control its behavior (see Batch Compiler Configuration Parameters). Even though it can be configured in many ways, there is only one required configuration parameter: the batch compiler target. The default values for the configuration parameters will be satisfactory in most cases, which makes the tool easy to use

Supported JSP and servlet specifications

The batch compiler will operate on Web modules supporting the Servlet 2.4 specification, or previous specifications back to Servlet 2.2. It will operate on JSPs written to the JSP 2.0 specification, or previous specifications back to JSP 1.0. It will recognize a Servlet 2.4 (JSP 2.0) deployment descriptor (web.xml) and use any jsp-config elements it may contain. In a Servlet 2.3 (JSP 1.2) or Servlet 2.2 (JSP 1.1) deployment descriptor, the batch compiler will recognize and use any taglib elements that the descriptor may contain.

The batch compiler target

The batch compiler can be executed against compressed or expanded Enterprise Application Archives (EARs) and Web Application Archives (WARs), as well as enterprise applications and Web modules that have been deployed into WebSphere Application Server. When the target is a deployed enterprise application, the server does not need to be running in order for the batch compiler to be executed. If the batch compiler is executed while the target sever is running, the server will not be aware of an updated class file and will not load that class file unless the enterprise application is restarted. When the target is a compressed EAR or WAR, the batch compiler must expand it before executing. Table 3 describes the batch compiler's expansion of EARs and WARs.

Processing of Web modules

The batch compiler operates on one Web module at a time. If the target is either an EAR or an installed enterprise application that contains more than one Web module, the batch compiler operates on each Web module individually. This occurs because JSPs are configured on a Web module basis, via the Web module's web.xml deployment descriptor.

Within a Web module, the batch compiler processes one directory at a time. It validates and translates each JSP individually, and then invokes the Java compiler for the entire group of generated Java source files in that directory. If one JSP fails during the Java compilation phase, the Java compiler may not create classfiles for most or all of the JSPs that successfully compiled in that directory.

JSP file extensions

The batch compiler uses four things to determine what file extensions it should process:

1. Standard JSP file extensions
   • *.jsp
   • *.jspx
   • *.jsw
   • *.jsv
2. The url-pattern property of the jsp-property-group elements in the deployment descriptor in Servlet 2.4 Web modules
3. The jsp.file.extensions JSP Engine configuration parameter (for pre-Servlet 2.4 Web modules)
4. The batch compiler configuration parameter jsp.file.extensions

The standard extensions are always used by the batch compiler. If the Web module contains a Servlet 2.4 deployment descriptor, the batch compiler will also process any url-patterns found within the jsp-config element. If the batch compiler target contains the JSP Engine configuration parameter jsp.file.extensions then those extensions are also processed. If the batch compiler configuration parameter jsp.file.extensions is present, the extensions given will also be processed and will override the JSP Engine configuration parameter jsp.file.extensions.

It is a good idea to give JSP "fragments" an extension that will not be processed by the batch compiler. Statically-included fragments that will not stand alone will generate translation or compilation errors if processed. The JSP 2.0 specification suggests the extension .jspf for such files.

JSP Engine configuration parameters

The batch compiler has nine configuration parameters that have equivalents in the WebSphere Application Server JSP Engine. The JSP Engine parameters, if present, act as defaults when the equivalent batch compiler parameter is not given. (See Three groups of configuration parameters and their precedence) These parameters are:

Table 1. Batch compiler parameters and equivalent JSP Engine parameters

The batch compiler does not create, or set the values of, equivalent JSP Engine parameters. This means that if a JSP in a deployed Web module is modified and is recompiled by the JSP Engine at run time, the JSP Engine's configuration parameters will determine the engine's behavior. If precompiled JSPs are never modified in a deployed Web module then this is not an issue. If they are modified in a deployed Web module, then the engine's parameters should be set to the same values used in batch compilation.

Determining when a JSP needs to be compiled

A JSP's classfile is considered to be outdated when its timestamp is different from -- is either newer or older than -- the timestamp of the JSP. The batch compiler will translate and compile a JSP when the classfile is outdated, or when the classfile does not exist. (There are JSP Engine configuration parameters that can be used to disable run time compilation of JSPs even when their class files are outdated. See JSP engine performance considerations .)

A JSP may have dependencies (see trackDependencies). A JSP classfile will be regenerated if the trackDependencies configuration parameter is set to true and if the timestamp of any one of the JSP's dependencies has changed since the JSP was last translated and compiled. The names and timestamps of a JSP's dependencies are stored within the classfile, which enables the batch compiler (and the JSP Engine at run time) to determine if a dependency has changed.

Batch compiler compilation of JSPs may be forced -- regardless of whether or not the classfiles are outdated or dependencies have changed -- by using the parameter forceCompilation (see Optional configuration parameters).

Determining where classfiles are generated

The WebSphere Application Server JSP Engine at run time will load JSP classfiles from either the WebSphere Application Server temp directory or a Web module's WEB-INF/classes directory. The WebSphere Application Server temp directory is typically {WAS_ROOT}/temp . The Engine searches for a classfile in the temp directory first, and second in the Web module's WEB-INF/classes directory. Figure 1 shows the processing logic of the JSP Engine at run time.

The batch compiler supports the generation of classfiles in both the WebSphere Application Server temp directory and a Web module's WEB-INF/classes directory, depending on the type of batch compiler target. In addition, the batch compiler enables generation of classfiles into any directory on the file system, outside the target application. See Table 4 for details.

Generating classfiles into a Web module's WEB-INF/classes directory enables the Web module to be deployed as a self-contained WAR, or a WAR inside of an EAR.

Batch compiler classpath

The batch compiler builds its classpath as shown in Table 2. When the batch compiler target is a WAR (war.path is supplied) the configuration parameter additional.classpath can be used to give extra classpath information.

Table 2. Batch Compiler Classpath

Logging

The batch compiler logs its operations, both to the console and to a log file {WAS_ROOT}/logs/jspBatchCompilerTrace.log . The default logging level, CONFIG, will log processing information and any exceptions or JSP translation or compiler errors encountered. If a finer level of logging is needed for debugging, the log.level parameter can be used (see log.level).

JSP Engine performance considerations

The JSP Engine offers a configuration parameter -- disableJspRuntimeCompilation -- that disables the run time compilation of JSPs. This is the most efficient mode for the engine, because it will never check to see if a class file is outdated, avoiding all file system checks. This setting requires that a JSP's classfile be present, even on the first request. In order to make use of this parameter, all JSP classfiles must exist when the application is deployed. The batch compiler parameter forceCompilation can be used in the final stages of application assembly to ensure that all JSP class files exist before deployment.

The JSP Engine parameters reloadEnabled and reloadInterval can be used when JSPs are modified at run time and need to be reloaded to pick up modifications. The reloadEnabled parameter determines whether or not a JSP file will be retranslated and recompiled at run time if the JSP file or its dependencies (see trackDependencies ) are modified. Note that if reloadEnabled is false (the default) a JSP is still compiled if necessary on the first request to it unless the attribute disableJspRuntimeCompilation is true. If reloading is enabled, reloadInterval determines how many seconds between requests for a JSP the engine will wait before checking to see if reloading of the JSP is necessary.

The JSP Engine also offers a development-mode parameter, trackDependencies. If your server is being used during development it is useful to have a JSP recompiled when its dependencies change. This is the most inefficient mode for the engine as it requires file system checks on every request to a JSP. If you wish to use this engine parameter, be sure to use the equivalent batch compiler parameter before deploying the application into WebSphere Application Server -- the batch compiler will generate all the necessary dependency tracking information which will then be used by the engine at run time. The engine will not automatically create this information, when its trackDependencies parameter is set to true, unless a JSP is recompiled because it has changed or its class file has been deleted.

The JSP Engine parameters useThreadTagPool and usePageTagPool can improve performance of JSPs that make heavy use of custom tags. Be sure to batch compile with the desired batch compiler equivalent parameter set to true, so that the JSP Engine will be able to make use of the pooling at run time.

Back to top

Batch compiler command

Both a Windows batch file (JspBatchCompiler.bat) and UNIX shell script (JspBatchCompiler.sh) for running the batch compiler from the command line can be found in {WAS_ROOT}/bin. An Ant task (see Batch Compiler Ant Task) is also available for executing the batch compiler using Ant.

The batch compiler command looks like this:

JspBatchCompiler
	-ear.path <path> | -war.path <path> | -enterpriseapp.name <name>
	[-response.file <filename>]
	[-webmodule.name <name>]
	[-filename <jsp name | directory name>]
	[-config.root <path>]
	[-cell.name <name>]
	[-node.name <name>]
	[-server.name <name>]
	[-extractToDir <path>]
	[-compileToDir <path>]
	[-compileToWebInf <true|false>]
	[-forceCompilation <true|false>]
	[-trackDependencies <true|false>]
	[-createDebugClassfiles <true|false>]
	[-keepgenerated <true|false>]
	[-keepGeneratedclassfiles <true|false>]
	[-usePageTagPool <true|false>]
	[-useThreadTagPool <true|false>]
	[-classloader.parentFirst <true|false>]
	[-classloader.singleWarClassloader <true|false>]
	[-additional.classpath <classpath>]
	[-verbose <true|false>]
	[-deprecation <true|false>]
	[-compileWithAssert <true|false>]
	[-useJikes <true|false>]
	[-jsp.file.extensions <file extensions to process>]
	[-log.level <SEVERE | WARNING | INFO | CONFIG | FINE | FINER | FINEST | OFF>]

A sample batch compiler command entered from the Windows command prompt:

C:\WAS\AppServer\bin>jspbatchcompiler -enterpriseapp.name sampleApp -forcecompilation true -verbose true

Back to top

Batch compiler configuration parameters

• The batch compiler configuration parameters are not case sensitive. For example:
  
  -usePageTagPool is the same as -usepagetagpool.
  
  
• Each parameter must be followed by its value, and the parameter and its value must be separated by one or more spaces. For example:
  
  -enterpriseapp.name myWebApplication.
  
  
• The parameters can appear in any order on the command line and in a response file. The response.file parameter is described below under Optional Configuration Parameters.

Three groups of configuration parameters and their precedence

The batch compiler is aware of three groups of configuration parameters:

1. JSP Engine configuration parameters for a Web module.
   These are the parameters that have been set for a particular Web module's JSP support, usually within a deployed application. For example, the keepgenerated parameter has been available for many releases of WebSphere Application Server to control the saving or deleting of the Java source that is generated by the JSP Engine.
   • JSP Engine configuration parameters are stored in a Web module's configuration directory, in the file WEB-INF/ibm-web-ext.xmi. An example of a configuration directory is:
     
     {WAS_ROOT}/config/cells/cellname/applications/enterpriseappname/deployments/deployedname/webmodulename
     
     
   • If an application was deployed into WebSphere Application Server with the flag "Use Binary Configuration" set to true, then the WEB-INF/ibm-web-ext.xmi file is looked for in a Web module's binaries directory, not in the configuration directory. An example of a binaries directory is:
     
     {WAS_ROOT}/installedApps/nodename/EnterpriseAppName/WebModuleName/
     
     
   • The entry in ibm-web-ext.xmi for a JSP Engine configuration parameter looks like the following example:
     
     <jspAttributes xmi:id="JSPAttribute_6" name="keepgenerated" value="true"/>
     
     
2. Response file configuration parameters.
   These are the parameters that are found in a batch compiler response file.
3. Batch compiler command line configuration parameters.
   These are the parameters entered on the command line when running the batch compiler.

The batch compiler looks at all three groups of configuration parameters in order to determine which value for a parameter should be used when compiling JSPs. When resolving the value for a given parameter, the precedence is:

1. If the parameter is found on the command line, its value is used. If the parameter is not found on the command line, the batch compiler looks for
2. the parameter in a response file named on the command line. If no response file is named, or if the parameter is not found therein, the batch compiler looks for the parameter in
3. the Web module's JSP Engine configuration parameters. (See JSP Engine configuration parameters.)

If a configuration parameter is not found among these three groups, then a default value is used. The default values for the configuration parameters are given below along with the description of the parameters, in the Required configuration parameters and Optional configuration parameters sections.

Required configuration parameters: the batch compiler target

One and only one of ear.path, war.path and enterpriseapp.name is required. These parameters do not have to be given on the command line; they may appear in a response file instead.

ear.path

war.path

enterpriseapp.name

Optional configuration parameters

response.file

webmodule.name

filename

config.root

cell.name

node.name

server.name

extractToDir

compileToDir

compileToWebInf

forceCompilation

trackDependencies

log.level

Back to top

Batch compiler ant task

The ant task JspC exposes all the batch compiler configuration options. It executes the batch compiler under the covers. It is backward compatible with the WebSphere Application Server 5.x version of the JspC ant task. Table 5 lists all the ant task attributes and their batch compiler equivalents. An example build.xml is shown in Listing 1. The Javadoc for JspC is available in the download file.


Table 5. JspC Ant Task Attributes and their Batch Compiler Equivalents

<project name="jsp" default="jspc_test" basedir=".">
<taskdef name="wsjspc" classname="com.ibm.websphere.ant.tasks.JspC"/>
	<target name="jspc_test" description="example usage of JspC task">
		<wsjspc wasHome="C:\WAS\AppSer"
		earpath="C:\WAS\AppSer\installedApps\sdjt30\myApp.ear"
		webmodulename="examples.war"
		forcecompilation="true"
		verbose="false"
		deprecation="false"
		loglevel="CONFIG"
		/>
	</target>
</project>	

Back to top

Conclusion

The WebSphere Application Server batch compiler is a highly configurable tool that enables compilation of JSPs in compressed and expanded EARs and WARs, as well as in enterprise applications that have been deployed into WebSphere Application Server. It can help simplify application deployment by enabling the precompilation of JSPs directly into a Web module. It is aware of all JSP Engine run time configuration attributes, enabling the generation of JSP class files that can be used in the run time engine without recompilation. During application development, it is a convenient tool for verifying that all JSP files and their included files are valid, and that all classes and JARs they depend on are visible.

Back to top

Acknowledgements

The author wishes to thank Todd Kaplinger and Richard Backhouse for their contributions to this article.

Back to top

Download

Name	Size	Download method
JSPBatchcompilerWAS6TD.zip	7 KB	FTP|HTTP

	Information about download methods

Resources

• WebSphere Application Server Technology for Developers V6
  

About the author

		Scott Johnson is the Team Lead for the WebSphere Application Server JSP Engine. He joined IBM at the Research Triangle Park Lab in 2000, after 17 years as a programmer and project lead.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Back to top