+

Search Tips   |   Advanced Search

JSP engine configuration parameters

In WebSphere Application Server, we can configure the JavaServer Pages (JSP) engine configuration parameters for optimal performance in a production server environment and for the needs of developers in a development environment.

The JSP engine parameters are case-sensitive. If the value specified for a parameter is comprised of two or more words that are separated by spaces, we must add quotation marks around the value. Some parameters affect the Java source generated for a JSP or tag file. These parameters are identified by the following statement: "This parameter requires regeneration of Java source." This statement indicates that if the configuration parameter is modified, the value for the parameter does not change anything until the JSP files are re-translated and the Java sources are recompiled.

Use an assembly tool, such as Rational Application Developer, to modify IBM extension and binding files. We can convert extension and binding files within modules from XMI to XML using the IBM Bindings and Extensions Conversion Tool for Multi-Platforms.bprac


allowMultipleAttributeValues

Specifies whether the JSP container can store multiple values for a custom tag attribute. Set this parameter to true to allow the JSP container to store multiple values. The default value for this parameter is false. This parameter requires regeneration of Java source.


compileWithAssert

Specifies whether the generated Java classes should contain support for the Developer Kit, Java Technology Edition 1.4 Assertion facility. The effect of setting this parameter to true is that the -source 1.4 option is passed to the Java compiler. The default for this parameter is false. This parameter requires regeneration of Java source.


classdebuginfo

Specifies whether the compiler includes debugging information in the generated class file. When we set this parameter to true, the -g option is passed to the Java compiler. The default for this parameter is false. This parameter requires regeneration of Java source.


convertAttrValueToString

Convert start and end attributes of the repeat tag to strings before they are used. The default for this parameter is false. This parameter requires regeneration of Java source.


deprecation

Specifies whether the compiler generates deprecation warnings when compiling the generated Java source. When we set this parameter to true, the -deprecation option is passed to the Java compiler. The default for this parameter is false. This parameter requires regeneration of Java source.


disableElCache

Set this parameter to true to disable the commons-el expression cache if we are experiencing out of memory conditions because the hash maps are held by the expression evaluator. The default for this parameter is false.


disableJspRuntimeCompilation

If this option is set to true, the JSP engine at run time does not convert and compile JSP files; the JSP engine loads only precompiled class files. JSP source files do not need to be present to load class files. When this option is set to true, we can install an application without JSP source, but the application must have precompiled class files. A web container custom property with the same name is used to determine the behavior of all web modules installed in a server. If both the web container custom property and the JSP engine option are set, the JSP engine option takes precedence. The default for this parameter is false.


disableTldSearch

Set this option to true to prevent the JSP engine from searching the application installation directories for the taglib descriptor (TLD) files when an application starts. If this option is set to false, when an application starts, the JSP engine searches the application installation directories for the TLD files. The default for this parameter is false.

The web container custom property, com.ibm.wsspi.jsp.disableTldSearch, can be used to specify whether the JSP engines in all web modules installed in a server do not search the application installation directories for the TLD files when an application starts. If conflicting values are set for the web container custom property and the JSP engine option, the setting for the JSP engine option takes precedence.

This option is only available in version levels 7.0.0.3, and higher.


evalQuotedAndEscapedExpression

Set this option to true to handle escape characters and quotations properly when determining whether to evaluate an expression.

During the translation phase of a JSP compile, expressions are evaluated by the JSP engine. Characters such as the escape character (\), or nested single or double quotations, cause the JSP file translation to fail. See the following example of a function containing characters that are evaluated: 

<input type="text" value="${fn:substring('1234567', 0,4)}"/>
Because of the double quotation mark directly before the fn:substring statement, the JSP file fails to compile because the translator did not add the function mapper to the generated Java class. Also, if a dollar sign ($) was escaped using the backslash(\$), the translator still attempts to evaluate the expression instead of treating it as a literal string. To handle escape characters and quotations properly, we must set evalQuotedAndEscapedExpression to true in the ibm-web-ext.xmi or ibm-web-ext.xml file of the failing application.

The following code sample shows an entry in the ibm-web-ext.xmi file: 

<jspAttributes xmi:id="JSPAttribute_1" 
name="evalQuotedAndEscapedExpression" value="true"/>

The following code sample shows an entry in the ibm-web-ext.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<web-ext
   xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
      version="1.0">
   <file-serving-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir" />
   <jsp-attribute name="evalQuotedAndEscapedExpression" value="true" />
   <jsp-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir","${MY_CUSTOM_VARIABLE}"  />
   
   <reload-interval value="3"/>
   <auto-encode-requests value="false"/>
   <auto-encode-responses value="false"/>
   <enable-directory-browsing value="false"/>
   <enable-file-serving value="true"/>
   <pre-compile-jsps value="false"/>
   <enable-reloading value="true"/>
   <enable-serving-servlets-by-class-name value="false" />	
</web-ext>

To apply this behavior globally across all web applications, we can set the com.ibm.wsspi.jsp.evalQuotedAndEscapedExpression web container custom property to true.


extendedDocumentRoot

Use the extended document root facility when applications require access to files outside of the application web application archive (WAR) directory. This facility enables us to configure an application with one or more directory paths from which we can serve static files and JSP files. Use this attribute when an application requires access to files that exist outside of the web application archive (WAR) directory. For example, if several applications require access to a set of common files, we can place the common files in a directory to which we can link each application as an extended document root directory.

To configure an application with an extended document root, add an extendedDocumentRoot attribute as a file-serving attribute to the ibm-web-ext.xmi or ibm-web-ext.xml file for the application. The value of this attribute is a comma-delimited list of directories that serve as the root directory location for the static files.

The following entry is an example within the ibm-web-ext.xmi file: 

<fileServingAttributes xmi:id="FileServingAttribute_1" name="extendedDocumentRoot" value="/opt/extDocRootDir"/>

The following examples are based on the previous entry in the ibm-web-ext.xmi file with the attribute set to the /opt/extDocRootDir value:

The following entry is an example within the ibm-web-ext.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<web-ext
   xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
      version="1.0">
   <file-serving-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir" />
   <jsp-attribute name="evalQuotedAndEscapedExpression" value="true" />
   <jsp-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir", "${MY_CUSTOM_VARIABLE}"/>
   <reload-interval value="3"/>
   <auto-encode-requests value="false"/>
   <auto-encode-responses value="false"/>
   <enable-directory-browsing value="false"/>
   <enable-file-serving value="true"/>
   <pre-compile-jsps value="false"/>
   <enable-reloading value="true"/>
   <enable-serving-servlets-by-class-name value="false" />	
</web-ext>

Important: To serve static files from an extended document root directory, enable file serving.

To configure an application with an extended document root from which JSP files are served, add an extendedDocumentRoot attribute as a JSP attribute to the ibm-web-ext.xmi or ibm-web-ext.xml file. The value of this attribute is a comma-delimited list of directories that serve as the root directory location for the JSP files.

The following entry is an example within the ibm-web-ext.xmi file: 

<jspAttributes xmi:id="JSPAttribute_1" name="extendedDocumentRoot" value="/opt/extDocRootDir"/>

The following example shows the entry within the ibm-web-ext.xml file: 

<?xml version="1.0" encoding="UTF-8"?>
<web-ext
   xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
      version="1.0">
   <file-serving-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir" />
   <jsp-attribute name="evalQuotedAndEscapedExpression" value="true" />
   <jsp-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir", "${MY_CUSTOM_VARIABLE}" />
   <reload-interval value="3"/>
   <auto-encode-requests value="false"/>
   <auto-encode-responses value="false"/>
   <enable-directory-browsing value="false"/>
   <enable-file-serving value="true"/>
   <pre-compile-jsps value="false"/>
   <enable-reloading value="true"/>
   <enable-serving-servlets-by-class-name value="false" />	
</web-ext>

We can also use an extendedDocumentRoot attribute to define a WebSphere variable on multiple nodes to the appropriate directory.

ibm-web-ext.xmi example: 

<jspAttributes xmi:id="JSPAttribute_2" name="extendedDocumentRoot" 
  		value="${MY_CUSTOM_VARIABLE}"/>

ibm-web-ext.xml example: 

 <jsp-attribute name="extendedDocumentRoot" 
    value="${MY_CUSTOM_VARIABLE}" />
where MY_CUSTOM_VARIABLE is the WebSphere variable to define on multiple nodes.

ibm-web-ext.xmi file that defines an extended document root both as a file-serving attribute and a JSP attribute: 

<?xml version="1.0" encoding="UTF-8"?>
<com.ibm.ejs.models.base.extensions.webappext:WebAppExtension xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:com.ibm.ejs.models.base.extensions.webappext="webappext.xmi" xmi:id="WebAppExtension_1"
          reloadInterval="3"
          reloadingEnabled="true"
          fileServingEnabled="true">
      <webApp href="WEB-INF/web.xml#WebApp_ID/">
      <fileServingAttributes xmi:id="FileServingAttribute_1" name="extendedDocumentRoot"
       value="/opt/extDocRootDir/">
      <jspAttributes xmi:id="JSPAttribute_1" name="extendedDocumentRoot"
       value="/opt/extDocRootDir/">
<com.ibm.ejs.models.base.extensions.webappext:WebAppExtension>

ibm-web-ext.xml file that defines an extended document root both as a file-serving attribute and a JSP attribute: 

<?xml version="1.0" encoding="UTF-8"?>
<web-ext
   xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
      version="1.0">
   <file-serving-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir" />
   <jsp-attribute name="evalQuotedAndEscapedExpression" value="true" />
   <jsp-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir","${MY_CUSTOM_VARIABLE}"  />
   
   <reload-interval value="3"/>
   <auto-encode-requests value="false"/>
   <auto-encode-responses value="false"/>
   <enable-directory-browsing value="false"/>
   <enable-file-serving value="true"/>
   <pre-compile-jsps value="false"/>
   <enable-reloading value="true"/>
   <enable-serving-servlets-by-class-name value="false" />	
</web-ext>

If the request is a valid partial request for a welcome file, a 404 error is returned. If the JSP file is located inside a JAR file and the reloadEnabled attribute value is true, the time stamp of the JAR file is used for isOutDated checks for recompile purposes. The default for this parameter is null.

For IBM extension and binding files, the .xmi or .xml file name extension is different depending on whether we are using a pre-Java EE 5 application or module or a Java EE 5 or later application or module. An IBM extension or binding file is named ibm-*-ext.xmi or ibm-*-bnd.xmi where * is the type of extension or binding file such as app, application, ejb-jar, or web. The following conditions apply:

However, a Java EE 5 or later module can exist within an application that includes pre-Java EE 5 files and uses the .xmi file name extension.

The ibm-webservices-ext.xmi, ibm-webservices-bnd.xmi, ibm-webservicesclient-bnd.xmi, ibm-webservicesclient-ext.xmi, and ibm-portlet-ext.xmi files continue to use the .xmi file extensions.


ieClassId

Indicates the Java plug-in COM class ID for Internet Explorer.

The <jsp:plugin> tags use this value. The default classid is clsid:8AD9C840-044E-11D1-B3E9-00805F499D93


javaEncoding

Encoding used when the .java file is generated, and when it is compiled by the Java compiler. Set this parameter when the page encoding of our JSP pages is not UTF-8 compatible. When javaEncoding is set, the encoding is passed to the Java compiler through the -encoding argument. Note that encoding is not supported by Jikes. The default is UTF-8. This parameter requires regeneration of Java source.


jdkSourceLevel

This JSP engine parameter was introduced in WAS version 6.1. Use this parameter instead of the compileWithAssert parameter, although compileWithAssert still works in version 6.1.

The default value for this parameter is 17. This parameter requires regeneration of Java source. The following are jdkSourceLevel paramater values:


jspClassLoaderLimit

The WAS creates a JSPExtensionClassLoader object for each JSP in an application. This can result in these objects using increased native memory, which can lead to an OutOfMemoryException. This integer value determines how many JSPExtensionClassLoader objects to keep loaded in memory.

<jspAttributes xmi:id="JSPAttribute_1" name="jspClassLoaderLimit" value="1500"/>


jspClassLoaderExclusionList

While jspClassLoaderLimit specifies the number of JSPExtensionClassLoaderobjects to keep loaded in memory, this comma-delimited list of JSP values indicate what JSPs are not to be unloaded regardless of the limit set by jspClassLoaderLimit.

<jspAttributes xmi:id="JSPAttribute_2" name="jspClassLoaderExclusionList" value="/test/RappHTML2.jsp,/test/RappHTML4.jsp"/>


jsp.file.extensions

For JSP files with extensions other than the four standard extensions, .jsp, .jspx, .jsw and .jsv, we can configure this the extensions using this parameter. These extensions are added to the standard extensions.

The preferred method for doing this is to create a <jsp-property-group> in web.xml, and add a <url-pattern> tag for each extension.

The JSP engine can handle a list of file extensions that is separated by a colon or semicolon. For example, .ext1;.ext2:.extn


keepgenerated

Indicates that the Java files generated by the JSP compiler during the translation phase of the processing are retained. The default for this parameter is false. This parameter requires regeneration of Java source.


keepGeneratedclassfiles

Indicates that the class files generated by the JSP compiler during the translation phase of the processing are retained. The default for this parameter is true. This parameter requires regeneration of Java source.


modifyPageContextVariable

During the translation phase of a tag file that is compiled, the JSP container implicitly uses the pageContext variable for the PageContext object. The use of the pageContext variable as an implicit variable name in tag files does not comply with the JSP Specification. If compilation errors occur for applications that use a local pageContext variable in their tag file, set the modifyPageContextVariable attribute to true to remove the use of the pageContext variable name in the generated Java code for tag files.


recompileJspOnRestart

Determines whether a JSP file is retranslated and recompiled after application startup for the first time the file is requested. If recompileJspOnRestart is false, a JSP file is still compiled, if necessary, on the first request to that JSP file unless the parameter disableJspRuntimeCompilation is true. The default for this parameter is false.


reloadEnabled

Determines whether a JSP file is translated and compiled at run time if the JSP file or its dependencies (see trackDependencies) are modified.

If reloadEnabled is false, a JSP file is still compiled, if necessary, on the first request to it unless the parameter disableJspRuntimeCompilation is true. The default for this parameter is false.

If this JSP engine parameter is not specified, the equivalent web container parameter for web module class reloading is used. However, for an application whose deployment descriptor is at the Servlet 2.2 level, the default is true. This is done for the support of applications being migrated from WAS Version 4.x.


reloadInterval

If reloading is enabled, reloadInterval determines the delay between checks to see if a JSP file is outdated.

For example, if reloadInterval is 5, the JSP engine checks to see if a JSP file is outdated only when the last such check was done more than 5 seconds prior to the current request for the JSP file. The larger the reloadInterval, the less frequently the JSP engine checks for the need to reload a JSP file. If this JSP engine parameter is not specified, the equivalent web container parameter for web module class reloading is used. However, for an application whose deployment descriptor is at the Servlet 2.2 level, the default is 5 seconds. This is done for the support of applications being migrated from WAS Version 4.x.


reusePropertyGroupConfigOnInclude

For transitioning users: Most properties defined in a JSP attribute group apply to an entire translation unit, for example, the requested JSP file that is matched by its URL pattern and all the files it includes using the include directive. The exceptions are the page-encoding and is-xml properties, which apply separately to each JSP file that is matched by its URL pattern. To revert the behavior to a setting prior to WAS v8.0, set the attribute to true to apply the two property values to the entire translation unit.trns


scratchdir

Directory where the generated class files are created.

The system property com.ibm.websphere.servlet.temp.dir is used to set the scratchdir option on a server-wide basis. The JSP engine scratchdir parameter takes precedence over the system property com.ibm.websphere.servlet.temp.dir. The default for this parameter is profile_root/temp. This parameter requires regeneration of Java source.

Do not specify a directory path that places the JSP temporary directory at the same level or underneath the configuration temporary directory. The default location for the configuration temporary directory is profile_home/config/temp.

For example, if we change the location of the JSP temporary directory to profile_home/config/temp or if you place the JSP temporary directory underneath the configuration temporary directory at profile_home/config/temp/temp, processing errors occur.


trackDependencies

If reloading is enabled, trackDependencies determines whether the JSP engine tracks modifications to the requested JavaServer Pages files dependencies and to the JSP file itself.

The dependencies that are tracked by the JSP engine are:

  1. Files that are statically included in the JSP file
  2. Tag files referenced in the JSP file (excluding tag files in JARs)
  3. TLD files referenced in the JSP file (excluding TLDs in JARs)

The default is false.


useFullPackageNames

If useFullPackageNames is true, the JSP engine generates and loads JSP classes using full package names.

The default is to generate all JSP classes in the same package. (Refer to the Packages and directories for generated .java and .class files topic). The JSP engine's class loader knows how to load JSP classes when they are all in the same package.

The default method of generating all JSP classes in the same package has the benefit of generating smaller file-system paths. Full package names has the benefit of enabling the configuration of precompiled JSP class files as servlets in the web.xml file without the use of the jsp-file attribute, resulting in a single class loader, the web application's class loader, used to load all such JSP classes. Similarly, when the JSP engine's configuration attributes useFullPackageNames and disableJspRuntimeCompilation are both true, a single class loader is used to load all JSP classes, even if the JSP files are not configured as servlets in the web.xml file.

When useFullPackageNames is set to true, the batch compiler generates a generated_web.xml file in the web module's WEB-INF directory. This file contains servlet configuration information for each JSP file that was successfully translated and compiled. The information can optionally be copied into the web module web.xml file so that the JSP files are loaded as servlets by the web container. Note that if a JSP file is configured as a servlet in this way, no reloading of the JSP file is done at run time if the JSP file is modified. This is because the JSP file is treated as a regular servlet and requests for it do not pass through the JSP engine. This parameter requires regeneration of Java source.


useImplicitTagLibs

The JSP engine implicitly recognizes tsx and jsx as tag library prefixes for tag libraries supplied by the JSP engine. If tsx or jsx are used as prefixes for a customer's tag library, the customer's tag library overrides the implicit tag library. However, the implicit tag library is still cached by the JSP engine. Explicitly setting this parameter to false tells the engine not to cache the implicit tag library, and save resources. The default for this parameter is true.

The default URL for the tsx tags is http://websphere.ibm.com/tags/tsx. The default URI for the jsx tags is http://websphere.ibm.com/tags/jsx.

We might need to define the tsx or jsx tag library prefix with a different URI than its default URI. Also, we might need to define the same library prefix with a different URI. In these two situations, we can set the com.ibm.wsspi.jsp.allowtaglibprefixredefinition custom property to avoid translation errors. See documentation about JavaServer Pages custom properties.


useInMemory

That the JSP engine translate and compile Java code in the system memory.

When this option is not set, the JSP engine must perform the following steps:

  1. Write the translated Java file to the file system
  2. Load the Java file from the file system
  3. Compile the code into a class file
  4. Write the class to the file system
  5. Load the class file into a classloader.

No .class file or .java file is written to the system disk. For debugging or creating a JAR file from precompiled JSP code, we need to disable this option.


useJikes

Specifies whether Jikes is used for compiling Java sources.

NOTE: Jikes is not shipped with WAS. The default for this parameter is false. This parameter requires regeneration of Java source.


usePageTagPool

Enables or disables the reuse of custom tag handlers on an individual JavaServer Pages basis. The default for this parameter is false. This parameter requires regeneration of Java source.


useThreadTagPool

When thread-level tag handler pooling is used, tag handlers may be reused among separate occurrences of a custom action across all JSP pages in a single web module across separate requests. The default for this parameter is false. This parameter requires regeneration of Java source.

Enable custom tag handler reuse might reveal problems in the tag handler code regarding the tag's ability to be reused. A custom tag handler should always do two things:


verbose

Indicates that the compiler generates verbose output when compiling the generated Java source code. The effect of setting this parameter to true is that the -verbose option is passed to the Java compiler. The default for this parameter is false. This parameter requires regeneration of Java source.

Enable custom tag handler reuse might reveal problems in the tag handler code regarding the tag's ability to be reused. A custom tag handler should always do two things:


Related:

  • File serving
  • Packages and directories for generated .java and .class files
  • Configure JSP engine parameters
  • JavaServer Pages (JSP) runtime reloading settings
  • Custom property settings
  • Web container custom properties
  • JavaServer Pages specific web container custom properties
  • IBM Bindings and Extensions Conversion Tool for Multi-Platforms