Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference Release 2 (9.0.2) Part Number A95882-01 |
|
This chapter discusses operation of the OC4J JSP translator, then discusses the ojspc
utility and situations where pre-translation is useful, followed by general discussion of a number of additional JSP deployment considerations.
The chapter is organized as follows:
JSP translators generate 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 functionality of the JSP translator, focusing on its behavior in on-demand translation scenarios such as in OC4J in the Oracle9i Application Server. The following topics are covered:
This section discusses general features of the page implementation class code that is produced by the JSP translator in translating JSP source (.jsp
and .sqljsp
files).
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 pre-translation model, generated code automatically includes the following features:
javax.servlet.jsp.HttpJspPage
interface, which extends the more generic javax.servlet.jsp.JspPage
interface, which in turn extends the standard javax.servlet.Servlet
interface.
_jspService()
method specified by the HttpJspPage
interface. This method, often referred to generically 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.
session="false"
in a page
directive.
For introductory information about key JSP and servlet classes and interfaces, see Appendix A, "Servlet and JSP Technical Background".
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, however, places the static text itself in an inner class within the page implementation class. The service method out.print()
statements reference attributes of the inner class to print the text.
This inner class implementation results in an additional .class
file when the page is translated and compiled. In a client-side pre-translation scenario, be aware this means there is an extra .class
file to deploy.
The name of the inner class will always be based on the base name of the .jsp
file or .sqljsp
file. For mypage.jsp
, for example, the inner class (and its .class
file) will always include "mypage" in its name.
Note:
The OC4J JSP translator can optionally place the static text in a Java resource file, which is advantageous for pages with large amounts of static text. (See "Workarounds for Large Static Content in JSP Pages".) You can request this feature through the JSP
Even when static text is placed in a resource file, the inner class is still produced, and its |
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 MyPage123.jsp
will always result in the string "MyPage123" being part of the page implementation class name, Java source file name, and class file name.
In the current release, the base name is preceded by an underscore ("_"). Translating MyPage123.jsp
results in the page implementation class _MyPage123
in the source file _MyPage123.java
, which is compiled into _MyPage123.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/MyPage123.jsp
, for example, results in class _MyPage123
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_foo12.jsp
results in _My_2d_name__foo12
being the class name, in source file _My_2d_name__foo12.java
. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "foo12".) 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 "foo12".
These conventions are demonstrated in examples provided later in this chapter.
Although the Sun Microsystems JavaServer Pages Specification, Version 1.1 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 doc 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 (implementation details are subject to change in future releases):
package _hr._expenses;
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 (or .sqljsp
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 (implementation details are subject to change in future releases):
public class _UserLogin extends ...
Be aware that the case (lowercase/uppercase) that end users type in the URL must match the case of the actual .jsp
or .sqljsp
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:
UserLogin.jsp
results in the class _UserLogin
.
Userlogin.jsp
results in the class _Userlogin
.
userlogin.jsp
results in the class _userlogin
.
If you care about the case of the class name, then you must name the .jsp
file or .sqljsp
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. For pre-translation scenarios, ojspc
places files differently and has its own set of relevant options--see "Summary of ojspc Output Files, Locations, and Related Options".
Wherever JSP configuration parameters are mentioned, see "JSP Configuration Parameters" for more information.
Note: For information about general conventions used in naming output classes, packages, and files, see "General Conventions for Output Names" |
This section considers both regular JSP pages (.jsp
files) and SQLJ JSP pages (.sqljsp
files or files with language="sqlj"
in a page
directive) in listing files that are generated by the JSP translator. For the file name examples, presume a file Foo.jsp
or Foo.sqljsp
is being translated.
Source files:
.sqlj
file (for example, _Foo.sqlj
) is produced by the OC4J JSP translator if the page is a SQLJ JSP page.
.java
file (for example, _Foo.java
) is produced for the page implementation class and inner class. It is produced either directly by the JSP translator from the.jsp
file, or by the SQLJ translator from the.sqlj
file if the page is a SQLJ JSP page. The currently installed Oracle SQLJ translator is used by default, but you can specify an alternative translator by using the sqljcmd
JSP configuration parameter.
Binary files:
.ser
Java resource files, but they will be .class
files if you enable the SQLJ -ser2class
option through the sqljcmd
configuration parameter. The resource file or .class
file has "Foo" as part of its name.
.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.
.class
file is produced for the inner class of the page implementation class. This file will have "Foo" as part of its name; in the current implementation it would be _Foo$__jsp_StaticText.class
.
.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.
The JSP translator places generated output files under a base temp/_pages
directory as follows:
/j2ee/home/app-deployment/app-name/web-app-name/temp/_pages/...
Note the following, and refer to "Key OC4J Configuration Files" for related information about the noted configuration files:
app-deployment
is the OC4J deployment directory, specified in the OC4J server.xml
file. It is typically the application-deployments
directory.
app-name
is the application name, according to an <application>
element in server.xml
.
web-app-name
is the corresponding "Web application name", mapped to the application name in a <web-app>
element in the OC4J default-web-site.xml
file.
The path under the _pages
directory depends on the path of the .jsp
file under the application root directory.
As an example, consider the page welcome.jsp
in the examples/jsp
subdirectory under the OC4J default Web application directory. The path would be as follows:
/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
, _welcome.class
, and _welcome$__jsp_StaticText.class
for the page implementation class inner class) in the following directory:
/j2ee/home/application-deployments/default/defaultWebApp/temp/_pages/_examples/_jsp
Note the following:
application-deployments
is the OC4J default deployment directory.
default
is the OC4J default application name and defaultWebApp
is the default Web application name, both used for JSP pages placed in the default-web-app
directory.
.jsp
source file is in an 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.
In Oracle9iAS 9.0.2, the OC4J JSP container introduces 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 JSP 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.
Globally included files can be used for the following, for example:
globals.jsa
)
translate_params
equivalent code (typically for a JServ environment)
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.
Subelements:
<include>
Use this 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.
Subelements:
<into>
Attributes:
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 context-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:
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 "/dir1"
. The setting can also include a slash after the directory name, such as "/dir1/"
, 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='yes'?> <!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'> <ojsp-global-include> <include file="/header.html"> <into directory="/dir1" /> </include> <include file="/footer1.html" position="bottom"> <into directory="/dir1" subdir="false" /> <into directory="/dir1/part1/" subdir="false" /> </include> <include file="/footer2.html" position="bottom"> <into directory="/dir1/part2/" subdir="false" /> </include> </ojsp-global-include>
This example accomplishes three objectives:
header.html
file is included at the top of any JSP page in or under the dir1
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" %>
footer1.html
file is included at the bottom of any JSP page in the dir1
directory or its part1
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="/footer1.html" %>
footer2.html
file is included at the bottom of any JSP page in the part2
subdirectory of dir1
. 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" %>
Assume the following ojsp-global-include.xml
file:
<?xml version="1.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" %>
Also see "Migration Away from translate_params".
This section describes the ojspc
utility, provided with OC4J for pre-translation of JSP pages. For consideration of pre-translation scenarios, see "JSP Pre-Translation".
The following topics are covered here:
For a simple JSP (not SQLJ JSP) page, default functionality for ojspc
is as follows:
.jsp
file as an argument.
.jsp
file into Java page implementation class code, producing a .java
file. The page implementation class includes an inner class for static page content.
.java
file, producing two .class
files--one for the page implementation class itself and one for the inner class.
Following is the default ojspc
functionality for a SQLJ JSP page:
.sqljsp
file as an argument instead of a .jsp
file, or it takes a .jsp
file with language="sqlj"
in a page
directive.
.sqlj
file for the page implementation class (and inner class).
.sqlj
file. This produces a .java
file for the page implementation class (and inner class) and a SQLJ "profile" file that is, by default, a .ser
Java resource file.
For information about SQLJ profiles and Oracle-specific code generation, see the Oracle9i SQLJ Developer's Guide and Reference.
.java
file, producing two .class
files--one for the page implementation class itself and one for the inner class.
Under some circumstances (see the -extres
option descriptions below), ojspc
options direct the JSP translator to produce a .res
Java resource file for static page content, instead of putting this content into the inner class of the page implementation class. However, the inner class is still created and must still be deployed with the page implementation class.
Because ojspc
invokes the JSP translator, ojspc
output conventions are the same as for the translator in general, as applicable. For general information about JSP translator output, including generated code features, general conventions for output names, generated package and class names, and generated files and locations, see "Functionality of the JSP Translator".
Table 6-1 describes the options supported by the ojspc
pre-translation utility. These options are further discussed in "Option Descriptions for ojspc".
The second column notes comparable or related JSP configuration parameters for on-demand translation environments, such as OC4J.
Notes:
|
Following is the general ojspc
command-line syntax (assume %
is a UNIX prompt):
% ojspc [option_settings] file_list
The file list can include .jsp
files or .sqljsp
files.
Be aware of the following syntax notes:
.jsp
files are translated, they all must use the same character set (either by default or through page
directive contentType
settings).
-extres
, not -extres true
.
Following is an example:
% ojspc -d /myapp/mybindir -srcdir /myapp/mysrcdir -extres MyPage.sqljsp MyPage2.jsp
This section describes the ojspc
options in more detail.
(fully qualified path; ojspc
default: empty)
Use this option to specify additional classpath entries for javac
to use when compiling generated page implementation class source. Otherwise, javac
uses only the system classpath.
(fully qualified path; ojspc
default: current directory)
Use this option to specify an application root directory. The default is the current directory, from which ojspc
was run.
The specified application root directory path is used as follows:
include
directives in the page being translated
The specified directory path is prepended to any application-relative (context-relative) paths in the include
directives of the translated page.
The package will be based on the location of the file being translated relative to the application root directory. The package, in turn, determines the placement of output files. (See "Summary of ojspc Output Files, Locations, and Related Options".)
This option is necessary, for example, so included files can still be found if you run ojspc
from some other directory.
Consider the following example:
/abc/def/ghi/test.jsp
ojspc
from the current directory, /abc
, as follows (assume %
is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
test.jsp
page has the following include
directive:
<%@ include file="/test2.jsp" %>
test2.jsp
page is in the /abc
directory, as follows:
/abc/test2.jsp
This example requires no -appRoot
setting, because the default application root setting is the current directory, which is the /abc
directory. The include
directive uses the application-relative /test2.jsp
syntax (note the beginning "/"), so the included page will be found as /abc/test2.jsp
.
The package in this case is _def._ghi
, based simply on the location of test.jsp
relative to the current directory, from which ojspc
was run (the current directory is the default application root). Output files are placed accordingly.
If, however, you run ojspc
from some other directory, suppose /home/mydir
, then you would need an -appRoot
setting as in the following example:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still _def._ghi
, based on the location of test.jsp
relative to the specified application root directory.
(fully qualified path; ojspc
default: current directory)
Use this option to specify a base directory for ojspc
placement of generated binary files--.class
files and Java resource files. (The .res
files produced for static content by the -extres
option are Java resource files, as are .ser
profile files produced by the SQLJ translator for SQLJ JSP pages.)
The specified path is taken as a file system path (not an application-relative or page-relative path).
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc
).
It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced.
(boolean; ojspc
default: false
)
Enable this flag to instruct ojspc
to generate a line map to the original .jsp
file for debugging. Otherwise, line-mapping will be to the generated page implementation class.
This flag is useful for source-level JSP debugging, such as when using Oracle9i JDeveloper.
(fully qualified Java class name; ojspc
default: empty)
Use this option to specify a Java class that the generated page implementation class will extend.
(boolean; ojspc
default: false
)
Enable this flag to instruct ojspc
to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into an inner class of the generated page implementation class.
The resource file name is based on the JSP page name. In the current OC4J JSP implementation, it will be the same core name as the JSP name (unless special characters are included in the JSP name), but with an underscore ("_") prefix and .res
suffix. Translation of MyPage.jsp
, for example, would create _MyPage.res
in addition to normal output. The exact implementation for name generation may change in future releases, however.
The resource file is placed in the same directory as .class
files.
If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Workarounds for Large Static Content in JSP Pages".
(boolean; ojspc
default: false
)
Enable this option for ojspc
to display usage information and then exit. As a shortcut, -h
is also accepted.
(fully qualified Java interface name; ojspc
default: empty)
Use this option to specify a Java interface that the generated page implementation class will implement.
(boolean; ojspc
default: false
)
Enable this flag to direct ojspc
to not compile the generated page implementation class Java source. This allows you to compile it later with an alternative Java compiler.
(backward compatibility for include
; ojspc
default: false
)
This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS release 2, for functionality of include
directives. If you enable this option, page locations in nested include
directives are relative to the top-level page. If the option is disabled, page locations are relative to the immediate parent page, as per the JSP 1.2 specification.
(fully qualified package name; ojspc
default: per .jsp
file location)
Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.
Without setting this option, the package name is determined according to the location of the .jsp
file relative to the current directory (from which you ran ojspc
).
Consider an example where you run ojspc
from the /myapproot
directory, while the .jsp
file is in the /myapproot/src/jspsrc
directory (assume %
is a UNIX prompt):
% cd /myapproot % ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp
This results in myroot.mypackage
being used as the package name.
If this example did not use the -packageName
option, the JSP translator (in its current implementation) would use _src._jspsrc
as the package name, by default. (Be aware that such implementation details are subject to change in future releases.)
(flag for size reduction of custom tag code; ojspc
default: false
)
The Oracle9iAS release 2 implementation reduces the size of generated code for custom tag usage, but enabling this option results in even further size reduction. There may be performance consequences regarding tag handler reuse, however. See "Tag Handler Code Generation".
(flag for request-time introspection; ojspc
default: false
)
Enabling this allows request-time JavaBean introspection whenever compile-time introspection is not possible. When compile-time introspection is possible and succeeds, this parameter is ignored and there is no request-time introspection.
As an example of a scenario for use of request-time introspection, assume a tag handler returns a generic java.lang.Object
instance in VariableInfo
of the tag-extra-info class during translation and compilation, but actually generates more specific objects during request-time (runtime). In this case, if req_time_introspection
is enabled, the JSP container will delay introspection until request-time. (See "Scripting Variables and Tag-Extra-Info Classes" for information about use of VariableInfo
.)
(-S
followed by SQLJ option setting; ojspc
default: empty)
For SQLJ JSP pages, use the ojspc
-S
option to pass an Oracle SQLJ option to the SQLJ translator. You can use multiple occurrences of -S
, with one SQLJ option per occurrence.
Unlike when you run the SQLJ translator directly, use a space between a SQLJ option and its value (this is for consistency with other ojspc
options).
For example (from a UNIX prompt):
% ojspc -S-default-customizer -d /myapproot/mybindir MyPage.jsp
This command invokes the Oracle SQLJ -default-customizer
option to choose an alternative profile customizer, as well as setting the ojspc -d
option.
Here is another example:
% ojspc -S-ser2class true -S-status true -d /myapproot/mybindir MyPage.jsp
This command enables the SQLJ -ser2class
option (to convert the profile to a .class
file) and the SQLJ -status
option (to display status information as the .sqlj
file is translated).
Note the following for particular Oracle SQLJ options:
-encoding
option; instead, use the contentType
parameter in a page
directive in the JSP page.
-classpath
option if you use the ojspc -addclasspath
option.
-compile
option if you use the ojspc -noCompile
option.
-d
option if you use the ojspc
-d
option.
-dir
option if you use the ojspc -srcdir
option.
For information about Oracle SQLJ translator options, see the Oracle9i SQLJ Developer's Guide and Reference.
(fully qualified path; ojspc
default: current directory)
Use this option to specify a base directory location for ojspc
placement of generated source files--.sqlj
files (for SQLJ JSP pages) and .java
files.
The specified path is taken simply as a file system path (not an application-relative or page-relative path).
Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.
The default is to use the current directory (your current directory when you executed ojspc
).
It is recommended that you use this option to place generated source files into a clean directory so that you conveniently know what files have been produced.
(flag to generate static text as characters; ojspc
default: false
)
Enabling this option directs the JSP translator to generate static text in JSP pages as characters instead of bytes. The default setting is false
, which improves performance in outputting static text blocks.
Enable this flag if your application requires the ability to change the character encoding dynamically during runtime, such as in the following example:
<% response.setContentType("text/html; charset=UTF-8"); %>
(boolean; ojspc
default: false
)
Enable this option to direct ojspc
to report its translation steps as it executes.
The following example shows -verbose
output for the translation of myerror.jsp
(in this example, ojspc
is run from the directory where myerror.jsp
is located; assume %
is a UNIX prompt):
% ojspc -verbose myerror.jsp Translating file: myerror.jsp 1 JSP files translated successfully. Compiling Java file: ./_myerror.java
(boolean; ojspc
default: false
)
Enable this option for ojspc
to display the JSP version number and then exit.
(XML validation of web.xml
and TLD files; ojspc
default: false
)
This specifies whether XML validation is performed on the application web.xml
file and any tag library description (TLD) files. Because the Tomcat JSP reference implementation does not perform XML validation, this option is disabled by default.
By default, ojspc
generates the same set of files that are generated by the JSP translator in an on-demand translation scenario, and places them in or under the current directory (from which ojspc
was executed).
Here are the files:
.sqlj
source file (SQLJ JSP pages only)
.java
source file
.class
file for the page implementation class
.class
file for the inner class for static text
.ser
) or, optionally, a .class
file for the SQLJ profile (SQLJ JSP pages only)
This assumes standard SQLJ code generation. Oracle-specific SQLJ code generation produces no profiles.
.res
) for the static text of the page
For more information about files that are generated by the JSP translator, see "Generated Files and Locations".
To summarize some of the commonly used options described under "Option Descriptions for ojspc", you can use the following ojspc
options to affect file generation and placement:
-appRoot
to specify an application root directory
-srcdir
to place source files in a specified location
-d
to place binary files (.class
files and Java resource files) in a specified location
-noCompile
to not compile the generated page implementation class source (as a result of this, no .class
files are produced)
In the case of SQLJ JSP pages, translated .java
files are still produced, but not compiled.
-extres
to put static text into a Java resource file
-S-ser2class
(SQLJ -ser2class
option, for SQLJ JSP pages only) to generate the SQLJ profile in a .class
file instead of a .ser
Java resource file
For output file placement, the directory structure underneath the current directory (or directories specified by the -d
and -srcdir
options, as applicable) is based on the package. The package is based on the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the -appRoot
option.
For example, suppose you run ojspc
as follows (presume %
is a UNIX prompt):
% cd /abc % ojspc def/ghi/test.jsp
Then the package is _def._ghi
, and output files will be placed in the directory /abc/_def/_ghi
, where the _def/_ghi
subdirectory structure is created as part of the process.
If you specify alternate output locations through the -d
and -srcdir
options, a _def/_ghi
subdirectory structure is created under the specified directories.
Now presume that you run ojspc
from some other directory, as follows:
% cd /home/mydir % ojspc -appRoot /abc /abc/def/ghi/test.jsp
The package is still _def._ghi
, according to the location of test.jsp
relative to the specified application root. Output files will be placed in the directory /home/mydir/_def/_ghi
or in a _def/_ghi
subdirectory under locations specified through the -d
and -srcdir
options. In either case, the _def/_ghi
subdirectory structure is created as part of the process.
This section covers general deployment considerations and scenarios, mostly independent of your target environment.
It discusses the following topics:
This section provides an overview of OC4J deployment features and standard WAR deployment features.
See Oracle9iAS Containers for J2EE User's Guide for detailed information about deployment for the OC4J environment.
In OC4J, deploy each application through a standard EAR (Enterprise archive) file. Specify the name of the application and the name and location of the EAR file through an <application>
element in the OC4J j2ee/home/config/server.xml
file.
For production, use Oracle Enterprise Manager (OEM) for deployment. OEM is recommended for managing OC4J and other components of Oracle9iAS in a production environment. Refer to the Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for information.
OC4J also supports the admin.jar
tool for deployment, typically in a development environment. This modifies server.xml
and other configuration files for you, based on settings you specify to the tool. Or you can modify the configuration files manually (not generally recommended). Note that in Oracle9iAS 9.0.2, if you modify configuration files without going through OEM, you must run the dcmctl
tool, using its updateConfig
command, to inform Oracle9iAS Distributed Configuration Management (DCM) of the updates. (This does not apply in an OC4J standalone mode, where OC4J is being run apart from Oracle9iAS.) Here is the dcmctl
command:
dcmctl updateConfig -ct oc4j
The dcmctl
tool is documented in the Oracle9i Application Server Administrator's Guide.
The EAR file includes the following:
application.xml
configuration file, in /META-INF
orion-application.xml
configuration file, in /META-INF
The WAR file includes the following:
web.xml
configuration file, in /WEB-INF
In the web.xml
file for any particular application, you can override global settings for individual configuration parameters or for the definition of the JSP servlet (oracle.jsp.runtimev2.JspServlet
by default). Each application uses its own instance of the JSP servlet.
orion-web.xml
configuration file, in /WEB-INF
WEB-INF/classes
and in JAR files in WEB-INF/lib
The EAR file goes in the OC4J applications directory, which is specified in the application-directory
setting in the <application-server>
element of the server.xml
file, and is typically the j2ee/home/applications
directory. This would be the same directory as is specified for the EAR file location in the <application>
element in server.xml
.
Through the OC4J auto-deployment feature, a new EAR file in the applications directory (as specified in server.xml
) is detected automatically and hierarchically extracted.
See the Oracle9iAS Containers for J2EE User's Guide for more information about deployment and about the admin.jar
tool (which has additional uses as well). Also see "Key OC4J Configuration Files" for a summary of important configuration files in OC4J.
The Sun Microsystems JavaServer Pages Specification, Version 1.1 supports the packaging and deployment of Web applications, including JavaServer Pages, according to the Sun Microsystems Java Servlet Specification, Version 2.2 (and higher).
In typical JSP 1.1 implementations, you can deploy JSP pages through the WAR mechanism, creating WAR files through the JAR utility. The JSP pages can be delivered in source form and are deployed along with any required support classes and static HTML files.
According to the servlet 2.2 (and higher) specification, a Web application includes a deployment descriptor file--web.xml
--that contains information about the JSP pages and other components of the application. The web.xml
file must be included in the WAR file.
The servlet 2.2 specification also defines an XML DTD for web.xml
deployment descriptors and specifies exactly how a servlet container must deploy a Web application to conform to the deployment descriptor.
Through these logistics, a WAR file is the best way to ensure that a Web application is deployed into any standard servlet environment exactly as the developer intends.
Deployment configurations in the web.xml
deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. You can specify many additional features in web.xml
as well, such as timeout values for sessions, mappings of file name extensions to MIME types, and mappings of error codes to JSP error pages.
For more information about standard WAR deployment, see the Sun Microsystems Java Servlet Specification, Version 2.2 (and higher).
Oracle9i JDeveloper supports many types of deployment profiles, including simple archive, J2EE application (EAR file), J2EE EJB module (EJB JAR file), J2EE Web module (WAR file), J2EE client module (client JAR file), tag library for JSP 1.1 (tag library JAR file), business components EJB session bean profile, business components CORBA server for VisiBroker, and business components archive profile.
When creating a Business Components for Java (BC4J) Web application using Oracle9i JDeveloper, a J2EE Web module deployment archive is generated, containing both the BC4J and the Web application files.
The JDeveloper deployment wizards create all the necessary code to deploy business components as a J2EE Web module. Typically, a JSP client accesses the BC4J application in a J2EE Web Module configuration. The JSP client can also use data tags, data Web beans, or UIX tags to access the business components. (See the Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference for an overview of the BC4J and UIX tag libraries.)
A J2EE Web module is packaged as a WAR file that contains one or more Web components (servlets and JSP pages) and web.xml
, the deployment descriptor file.
JDeveloper lets you create the deployment profile containing the Web components and the web.xml
file, and packages them into a standard J2EE EAR file for deployment. JDeveloper takes the resulting EAR file and deploys it to one or more Oracle9iAS instances.
For information about JDeveloper, refer to the JDeveloper online help, or to the following site on the Oracle Technology Network:
http://otn.oracle.com/products/jdev/content.html
JSP pages are typically used in an on-demand scenario, where pages are translated as they are invoked, in a sequence that is invisible to the user. Another option, however, is to pre-translate JSP pages, which may be useful in saving end users the translation overhead the first time a page is executed.
You also might want to pre-translate pages so that you can deploy binary files only, as discussed in "Deployment of Binary Files Only".
You can use the Oracle ojspc
utility for pre-translation, or you can use the standard jsp_precompile
mechanism.
When you pre-translate with ojspc
, use the -d
option to set an appropriate output base directory for placement of generated binary files.
Consider the example in "JSP Translator Output File Locations", where the JSP page is located in the examples/jsp
subdirectory under the OC4J default Web application directory:
/j2ee/home/default-web-app/examples/jsp/welcome.jsp
A user would invoke this with a URL such as the following:
http://host[:port]/examples/jsp/welcome.jsp
(This is just a general example and does not consider OC4J default configuration for the context path.)
In an on-demand translation scenario for this page, as explained in the example, the JSP translator would by default use the following base directory for placement of generated binary files:
/j2ee/home/application-deployments/default/defaultWebApp/temp/_pages
When you pre-translate, set your current directory to the application root directory, then in ojspc
set the _pages
directory as the output base directory. This results in the appropriate package name and file hierarchy. Continuing the example (assume %
is a UNIX prompt):
% cd /j2ee/home/default-web-app % ojspc -d /j2ee/home/application-deployments/default/defaultWebApp/temp/_pages examples/jsp/welcome.jsp
The URL noted above specifies an application-relative path of examples/jsp/welcome.jsp
, so at execution time the JSP container looks for the binary files in an _examples/_jsp
subdirectory under the _pages
directory. This subdirectory would be created automatically by ojspc
if it is run as in the above example.
At execution time, the JSP container would find the pre-translated binaries and would not have to perform translation, assuming that either the source file was not altered after pre-translation, or the JSP main_mode
flag is set to justrun
.
It is also possible to specify JSP pre-translation, without execution, when you invoke the page in the normal way. Accomplish this by enabling the standard jsp_precompile
request parameter when invoking the JSP page from the browser.
Following is an example:
http://host[:port]/foo.jsp?jsp_precompile=true
or:
http://host[:port]/foo.jsp?jsp_precompile
(The =true
is optional.)
Refer to the Sun Microsystems JavaServer Pages Specification, Version 1.1, for more information about this mode of operation.
You can avoid exposing your JSP source, for proprietary or security reasons, by pre-translating the pages and deploying only the translated and compiled binary files. Pages that are pre-translated, either from previous execution in an on-demand translation scenario or by using ojspc
, can be deployed to any standard J2EE environment. There are two aspects to this scenario:
You must take steps to create and archive the binary files in an appropriate hierarchy.
ojspc
, you must first set your current directory to the application root directory. After running ojspc
, archive the output files using the ojspc
output directory as the base directory for the archive. See "The ojspc Pre-Translation Utility" for general information about this utility.
_pages
directory.
In the target environment, place the archive JAR file in the /WEB-INF/lib
directory, or restore the archived directory structure under the appropriate directory, typically under the _pages
directory.
If you have deployed binary files to an OC4J environment, set the JSP configuration parameter main_mode
to the value justrun
or the value reload
to execute JSP pages without the original source.
Without this setting, the JSP translator will always look for the JSP source file to see if it has been modified more recently than the page implementation .class
file, and abort with a "file not found" error if it cannot find the source file.
With main_mode
set appropriately, the end user can invoke a page with the same URL that would be used if the source file were in place.
For how to set configuration parameters in the OC4J environment, see "Setting JSP Configuration Parameters in OC4J".
|
Copyright © 2000, 2002 Oracle Corporation. All Rights Reserved. |
|