|
Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 3 (10.1.3) Part No. B14430-01 |
|
 Previous |
 Next |
|
Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 3 (10.1.3) Part No. B14430-01 |
|
|
Previous |
Next |
This chapter describes the operation of the internal OC4J JSP translator, which translates JSP pages into Java servlet code. The following sections discuss general functionality of the JSP translator, focusing on its behavior in on-demand translation scenarios within the Oracle Application Server:
|
Important: Implementation details in this section regarding package and class naming, file and directory naming, output file locations, and generated code are for illustrative purposes. The exact details are subject to change from release to release. |
The OC4J JSP translator generates standard Java code for a JSP page implementation class. This class is essentially a servlet class wrapped with features for JSP functionality.
This section discusses general features of the page implementation class code that is produced by the JSP translator from JSP source (typically .jsp or .jspx files).
Features of Page Implementation Class Code
When the JSP translator generates servlet code in the page implementation class, it automatically handles some of the standard programming overhead. For both the on-demand translation model and the pretranslation model, generated code automatically includes the following features:
It extends a wrapper class provided by the Web container that implements the javax.servlet.jsp.HttpJspPage interface, which extends the more generic javax.servlet.jsp.JspPage interface, which in turn extends the javax.servlet.Servlet interface.
It implements the _jspService() method specified by the HttpJspPage interface. This method, often referred to as the "service" method, is the central method of the page implementation class. Code from any Java scriptlets, expressions, and JSP tags in the JSP page is incorporated into this method implementation.
It includes code to request an HTTP session unless your JSP source code specifically sets session="false" in a page directive.
Member Variables for Static Text
The service method, _jspService(), of the page implementation class includes print statements—out.print() or equivalent calls on the implicit out object—to print any static text in the JSP page. The JSP translator places the static text itself in a series of member variables in the page implementation class. The service method out.print() statements reference these member variables to print the text.
|
Notes:
|
The JSP translator follows a consistent set of conventions in naming output classes, packages, files, and directories. However, this set of conventions and other implementation details may change from release to release.
One fact that is not subject to change, however, is that the base name of a JSP page will be included intact in output class and file names as long as it does not include special characters. For example, translating MyPage23.jsp will always result in the string "MyPage23" being part of the page implementation class name, Java source file name, and class file name.
The base name is preceded by an underscore ("_"). Translating MyPage23.jsp results in the page implementation class _MyPage23 in the source file _MyPage23.java, which is compiled into _MyPage23.class.
Similarly, where path names are used in creating Java package names, each component of the path is preceded by an underscore. Translating /jspdir/myapp/MyPage23.jsp, for example, results in class _MyPage23 being in the following package:
_jspdir._myapp
The package name is used in creating directories for output .java and .class files, so the underscores are also evident in output directory names. For example, in translating a JSP page in a directory such as webapp/test, the JSP translator by default will create a directory such as webappdeployment/_pages/_test for the page implementation class source. All output directories are created under the standard _pages directory, as described in "Generated Files and Locations".
If you include special characters in a JSP page name or path name, the JSP translator takes steps to ensure that no illegal Java characters appear in the output class, package, and file names.
For example, translating My-name_foo2.jsp results in _My_2d_name__foo2 being the class name, in source file _My_2d_name__foo2.java. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "foo2".)
In this case, you can only be assured that alphanumeric components of the JSP page name will be included intact in the output class and file names. For example, you could search for "My", "name", or "foo2".
The generated source and class file names for a .jspx file are similar, except that _jspx is added to the name. For example, translating MyPage.jspx results in the source file _MyPage_jspx.java, which is compiled into _MyPage_jspx.class.
These conventions are demonstrated in examples provided later in this chapter.
Although the JSP specification defines a uniform process for parsing and translating JSP text, it does not describe how the generated classes should be named. That is up to each JSP implementation.
This section describes how the OC4J JSP translator creates package and class names when it generates code during translation.
|
Note: For information about general conventions that the OC4J JSP translator uses in naming output classes, packages, and files, see "General Conventions for Output Names". |
In an on-demand translation scenario, the URL path that is specified when the user requests a JSP page—specifically, the path relative to the document root or application root—determines the package name for the generated page implementation class. Each directory in the URL path represents a level of the package hierarchy.
It is important to note, however, that generated package names are always lowercase, regardless of the case in the URL.
Consider the following URL as an example:
http://host:port/HR/expenses/login.jsp
In the current OC4J JSP implementation, this results in the following package specification in the generated code:
package _hr._expenses;
(Implementation details are subject to change in future releases.)
No package name is generated if the JSP page is at the application root directory, where the URL is as follows:
http://<host>:<port>/login.jsp
The base name of the .jsp file determines the class name in the generated code.
Consider the following URL example:
http://<host>:<port>/HR/expenses/UserLogin.jsp
In the current OC4J JSP implementation, this yields the following class name in the generated code:
public class _UserLogin extends ...
(Implementation details are subject to change in future releases.)
Be aware that the case (lowercase/uppercase) that users specify in the URL must match the case of the actual .jsp file name. For example, they can specify UserLogin.jsp if that is the actual file name, or userlogin.jsp if that is the actual file name, but not userlogin.jsp if UserLogin.jsp is the actual file name.
Currently, the translator determines the case of the class name according to the case of the file name. For example:
The file name UserLogin.jsp results in the class _UserLogin.
The file name Userlogin.jsp results in the class _Userlogin.
The file name userlogin.jsp results in the class _userlogin.
If you care about the case of the class name, then you must name the .jsp file accordingly. However, because the page implementation class is invisible to the end user, this is usually not a concern.
This section describes files that are generated by the JSP translator and where they are placed in on-demand translation scenarios. (For precompilation scenarios, ojspc places files differently and has its own set of relevant options. See Chapter 4, "Precompiling JSPs with ojspc".)
|
Note: For information about general conventions used in naming output classes, packages, and files, see "General Conventions for Output Names". |
Files Generated by the JSP Translator
For the file name examples, presume a file Foo.jsp is being translated.
Source files:
A .java file (for example, _Foo.java) is produced for the page implementation class by the JSP translator.
Binary files:
A .class file is produced by the Java compiler for the page implementation class. The Java compiler is the JDK javac by default, but you can specify an alternative compiler using the JSP javaccmd configuration parameter.
A .res Java resource file (for example, _Foo.res) is optionally produced for the static page content if the external_resource JSP configuration parameter is enabled.
|
Note: The exact names of generated files for the page implementation class might change in future releases, but will still have the same general form. The names would always include the base name, such as "Foo" in these examples, but might include variations beyond that. |
JSP Translator Output File Locations
The JSP translator places generated output files under a _pages directory that is created under the JSP cache directory, which is specified in the jsp-cache-directory attribute of the <orion-web-app> element in either the global-web-application.xml file or the application orion-web.xml file. Here is the general base location if you assume the default "./persistence" value of jsp-cache-directory:
ORACLE_HOME/j2ee/home/app-deployment/app-name/web-app-name/persistence/_pages/...
In OC4J standalone, here is the location relative to where OC4J is installed:
j2ee/home/app-deployment/app-name/web-app-name/persistence/pages/...
Note the following:
The app-deployment directory is the OC4J deployment directory specified in the OC4J server.xml file. (In OC4J standalone, this is typically the application-deployments directory.)
Also, app-name is the application name, according to an <application> element in server.xml.
And web-app-name is the corresponding "Web application name", mapped to the application name in a <web-app> element in the OC4J Web site XML file (typically default-web-site.xml file in Oracle Application Server or http-web-site.xml in OC4J standalone).
The path under the _pages directory depends on the path of the .jsp file under the application root directory.
As an example, in OC4J standalone, consider the page welcome.jsp in the examples/jsp subdirectory under the OC4J standalone default Web application directory. The path to this page would be as follows, relative to where OC4J is installed:
j2ee/home/default-web-app/examples/jsp/welcome.jsp
Assuming the default application deployment directory, the JSP translator would place the output files ( _welcome.java and _welcome.class) in the following directory:
j2ee/home/application-deployments/default/defaultWebApp/persistence/_pages/_examples/_jsp
Because the .jsp source file is in the examples/jsp subdirectory under the application root directory, the JSP translator generates _examples._jsp as the package name and places the output files into an _examples/_jsp subdirectory under the _pages directory.
|
Important: Implementation details, such as the location of generated output files and use of "_" in output file names, are subject to change in future releases. |
The OC4J Web container provides a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in or under a specified directory, through virtual JSP include directives. During translation, the Web container looks for a configuration file, /WEB-INF/ojsp-global-include.xml, that specifies the included files and the directories for the pages.
This enhancement is particularly convenient for migrating applications that used globals.jsa or translate_params functionality in previous Oracle JSP releases.
Oracle global includes functionality pre-dates the JSP 2.0 specification. Now that this functionality has been folded into the specification, for portability it is strongly recommended that you use the JSP specification mechanism in all new development.
Also be advised that the Oracle global includes functionality may be deprecated in a future release.
Globally included files can be used for the following, for example:
Global bean declarations (formerly supported through globals.jsa)
Common page headers or footers
Code with functionality that is equivalent to that of translate_params
This section provides an overview of the ojsp-global-include.xml file as well as some examples.
The ojsp-global-include.xml file specifies the names of files to include, whether they should be included at the tops or bottoms of JSP pages, and the locations of JSP pages to which the global includes should apply. This section describes the elements of ojsp-global-include.xml.
This is the root element of the ojsp-global-include.xml file. It has no attributes.
Subelement of <ojsp-global-include>:
<include>
Use the <include> subelement of <ojsp-global-include> to specify a file to be included and whether it should be included at the top or bottom of JSP pages.
Subelement of <include>:
<into>
Attributes of <include>:
file: Specify the file to be included, such as "/header.html" or "/WEB-INF/globalbeandeclarations.jsph". The file name setting must start with a slash ("/"). In other words, it must be application-relative, not page-relative.
position: Specify whether the file is to be included at the top or bottom of JSP pages. Supported values are "top" (default) and "bottom".
Use this subelement of <include> to specify a location (a directory, and possibly subdirectories) of JSP pages into which the specified file is to be included. This element has no subelements.
Attributes of <into>:
directory: Specify a directory. Any JSP pages in this directory, and optionally its subdirectories, will statically include the file specified in the file attribute of the <include> element. The directory setting must start with a slash ("/"), such as "/dir". The setting can also include a slash after the directory name, such as "/dir/", or a slash will be appended internally during translation.
subdir: Use this to specify whether JSP pages in all subdirectories of the directory should also have the file statically include. Supported values are "true" (default) and "false".
This section provides examples of global includes.
Assume the following ojsp-global-include.xml file:
<?xml version="1.0" standalone='no'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>
<ojsp-global-include>
<include file="/header.html">
<into directory="/dir" />
</include>
<include file="/footer.html" position="bottom">
<into directory="/dir" subdir="false" />
<into directory="/dir/part/" subdir="false" />
</include>
<include file="/footer2.html" position="bottom">
<into directory="/dir/part2/" subdir="false" />
</include>
</ojsp-global-include>
This example accomplishes three objectives:
The header.html file is included at the top of any JSP page in or under the dir directory. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:
<%@ include file="/header.html" %>
The footer.html file is included at the bottom of any JSP page in the dir directory or its part subdirectory. The result would be the same as if each .jsp file in those directories had the following include directive at the bottom of the page:
<%@ include file="/footer.html" %>
The footer2.html file is included at the bottom of any JSP page in the part2 subdirectory of dir. The result would be the same as if each .jsp file in that directory had the following include directive at the bottom of the page:
<%@ include file="/footer2.html" %>
|
Note: If multiple header or multiple footer files are included into a single JSP page, the order of inclusion is according to the order of<include> elements in the ojsp-global-include.xml file.
|
Assume the following ojsp-global-include.xml file:
<?xml version=".0" standalone='yes'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>
<ojsp-global-include>
<include file="/WEB-INF/nls/params.jsf">
<into directory="/" />
</include>
</ojsp-global-include>
And assume params.jsf contains the following:
<% request.setCharacterEncoding(response.getCharacterEncoding()); %>
The params.jsf file (essentially, the setCharacterEncoding() method call) is included at the top of any JSP page in or under the application root directory. In other words, it is included in any JSP page in the application. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:
<%@ include file="/WEB-INF/nls/parms.jsf" %>
