Network Deployment (Distributed operating systems), v8.0 > Reference > Sets


JSP engine configuration parameters

In WAS, you can configure the 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 separated by spaces, add quotation marks around the value. Some parameters affect the Java source that is generated for a JSP or tag file. These parameters are identified by the statement "This parameter requires regeneration of Java source." This statement indicates that if the configuration parameter is modified, the new value for the parameter does not have any effect until the JSP files are retranslated 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.


compileWithAssert

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

Indicates whether the compiler includes debugging information in the generated class file. When you 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

Whether to 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

Whether the compiler generates deprecation warnings when compiling the generated Java source. When you 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 the com.ibm.wsspi.jsp.disableElCache web container custom property to true to disable the commons-el expression cache if you 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 runtime does not translate and compile JSP files; the JSP engine loads only precompiled class files. JSP source files do not need to be present in order to load class files. When this option is set to true, you can install an application without JSP source, but the application must have precompiled class files. There is a web container custom property with the same name 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 is set 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.

There is a web container custom property, com.ibm.wsspi.jsp.disableTldSearch, that can be used to specify whether, when an application starts, the JSP engines in all web modules installed in a server do not search the application installation directories for the TLD files. 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 quotations, single or double, causes the JSP file translation to fail. For example, when you use functions that contain an expression such as 

<input type="text" value="${fn:substring('1234567', 0,4)}"/>
Because of the double quote 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, 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="true" />
<jsp-attribute name="evalQuotedAndEscapedExpression" value="true" />
<jsp-attribute name="extendedDocumentRoot" value="/opt/extDocRootDir" />
<jsp-attribute name="extendedDocumentRoot" value="${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="false" />

</web-ext>

To apply this behavior globally across all web applications, you 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 you to configure an application with one or more directory paths from which you can serve static files and JSP files. We can 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, you can place the common files in a directory to which you 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" />
<jsp-attribute name="extendedDocumentRoot" value="${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="false" />

</web-ext>

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" />
<jsp-attribute name="extendedDocumentRoot" value="${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="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.

The following example shows a 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>

The following example shows a 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" />
<jsp-attribute name="extendedDocumentRoot" value="${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="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 you 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 your 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 to support JDK 5. Use this parameter instead of the compileWithAssert parameter, although compile WithAssert still works in version 6.1.

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



jsp.file.extensions

For JSP files with extensions other than the four standard extensions, *.jsp, *.jspx, *.jsw, and *.jsv, you 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 semi-colon. 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 totrue 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 or not a JSP file is translated and compiled at runtime 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 v4.x.


reusePropertyGroupConfigOnInclude

For transitioning users: Most properties that are 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 you change the location of the JSP temporary directory to also be 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 JSP files dependencies as well as to the JSP file itself.

The dependencies tracked by the JSP engine are :

  1. files statically included in the JSP file
  2. tag files referenced in the JSP file (excluding tag files that are in JARs)
  3. TLD files referenced in the JSP file (excluding TLDs that are 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. (For more information, 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 runtime 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.

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


useInMemory

Specifies 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 will be written to the system disk. For debugging or creating a JAR file from precompiled JSP code, you will need to disable this option.


useJikes

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 JSP 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 with regard to 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.

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


File serving
Packages and directories for generated .java and .class files
Configure JSP engine parameters


Related


JSP runtime reloading settings
Custom property settings
Web container custom properties
JSP specific web container custom properties
IBM Bindings and Extensions Conversion Tool for Multi-Platforms

+

Search Tips   |   Advanced Search