Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide 10g (10.1.3.1.0) Part Number B28961-01 |
|
|
View PDF |
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.jsp
x 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 JSP Pages 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.
The javaccmd
parameter is deprecated in Oracle Containers for J2EE 10g (10.1.3.1.0).
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.
Notes:
|
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 feature 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 included into the specification, for portability it is strongly recommended that you use the JSP specification mechanism in all new development.
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" %>