Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference Release 2 (9.0.2) Part Number A95882-01 |
|
This chapter covers basic issues in your JSP environment, including key support files, key OC4J configuration files, configuration of the JSP container, and other initial considerations such as application root and classpath functionality.
Before getting started, it is assumed that you can do the following on your system:
The following topics are covered here:
This section summarizes JAR and ZIP files that are used by the JSP container or JSP applications. These files are installed on your system and into your classpath with OC4J:
ojsp.jar
--classes for the JSP container
ojsputil.jar
--classes for tag libraries and utilities provided with OC4J
xmlparserv2.jar
--for XML parsing; required for the web.xml
deployment descriptor and any tag library descriptor files and XML-related tag functionality
xsu12.jar
/ xsu111.jar
--for XML functionality on the client (for JDK 1.2.x or higher, or 1.1.x, respectively)
classes12.zip
/ classes111.zip
--for the Oracle JDBC drivers (for JDK 1.2.x or higher, or 1.1.x, respectively)
translator.zip
--for the Oracle SQLJ translator
runtime12.zip
/ runtime12ee.zip
/ runtime11.zip
/ runtime.zip
/ runtime-nonoracle.zip
--for the Oracle SQLJ runtime (respectively: for JDK 1.2.x or higher with Oracle9i JDBC, JDK 1.2.x or higher enterprise edition with Oracle9i JDBC, JDK 1.1.x with Oracle9i JDBC, any 1.1.x or higher JDK with any Oracle JDBC version, or any JDK environment with non-Oracle JDBC drivers)
jndi.jar
--for JNDI service for lookup of resources such as JDBC data sources and Enterprise JavaBeans
jta.jar
--for the Java Transaction API
There are also files relating to particular areas, such as particular tag libraries. These include the following:
mail.jar
--for e-mail functionality within applications (standard javax.mail
package)
activation.jar
--Java activation files for e-mail functionality
cache.jar
--for the Oracle9i Application Server Java Object Cache (which can be used by the OC4J Web Object Cache as the back-end repository)
This section covers the following topics regarding configuration of the JSP environment:
For non-OC4J environments, including JServ, use the old
Note:
oracle.jsp.JspServlet
front-end servlet instead of the oracle.jsp.runtimev2.JspServlet
version. See "Getting Started in a JServ Environment".
The JSP container is appropriately pre-configured in OC4J. The following settings appear in the OC4J global-web-application.xml
file to map the name of the front-end JSP servlet, and to map the appropriate file name extensions for JSP pages:
<orion-web-app ... > ... <web-app> ... <servlet> <servlet-name>jsp</servlet-name> <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class> ... init params ... </servlet> ... <servlet-mapping> <servlet-name>jsp</servlet-name> <url-pattern>/*.jsp</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>jsp</servlet-name> <url-pattern>/*.JSP</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>jsp</servlet-name> <url-pattern>/*.sqljsp</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>jsp</servlet-name> <url-pattern>/*.SQLJSP</url-pattern> </servlet-mapping> ... </web-app> ... </orion-web-app>
See the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information about the global-web-application.xml
file.
The JSP front-end servlet in OC4J, oracle.jsp.runtimev2.JspServlet
, supports a number of configuration parameters to control JSP operation. This section describes those parameters, starting with a summary table and then providing more complete descriptions.
Table 3-1 summarizes the configuration parameters supported by JspServlet
. For each parameter, the table notes any equivalent ojspc
translation options for pages you are pre-translating, and whether the parameter is for runtime or compile-time use.
Notes:
See "The ojspc Pre-Translation Utility" for a description of the |
This section describes the JSP configuration parameters for OC4J in more detail.
(boolean; default: true
)
Use the default true
setting to print a stack trace whenever a runtime exception occurs. Set it to false
to disable this feature.
(boolean; default: false
)
During development, set this flag to true
to instruct the JSP translator to generate a line map to the original .jsp
file for debugging. Otherwise, lines will be mapped to the generated page implementation class .java
file.
(boolean; default: false
)
Set this flag to true
to instruct the JSP translator to place generated static content (the Java print commands that output static HTML code) into a Java resource file, instead of into the service method of the generated page implementation class.
The resource file name is based on the JSP page name, with the .res
suffix. With Oracle9iAS 9.0.2, translation of MyPage.jsp
, for example, would create _MyPage.res
in addition to normal output. The exact implementation may change in future releases, however.
The translator places the resource file into the same directory as generated 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".
(compiler executable; default: null
)
This parameter is useful in either of the following circumstances:
javac
command-line options (although default settings are typically sufficient)
javac
(optionally including command-line options)
Specifying an alternative compiler results in that executable being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container. You can fully specify the path for the executable, or specify only the executable and let the JSP container look for it in the system path.
For example, set javaccmd
to the value javac -verbose
to run the compiler in verbose mode.
(mode switch for reloading or recompilation; default: recompile
)
This is a flag to direct the mode of operation of the JSP container, particularly for automatic recompilation of JSP pages and reloading of Java classes that have changed.
Here are the supported settings:
justrun
--The runtime dispatcher will not perform any timestamp checking, so there is no recompilation of JSP pages or reloading of Java classes. This mode is the most efficient mode for a deployment environment, where code will not change.
reload
--The dispatcher will check if any classes have been modified since loading, including translated JSP pages, JavaBeans invoked from pages, and any other dependency classes.
recompile
(default)--The dispatcher will check the timestamp of the JSP page, retranslate it and reload it if has been modified since loading, and execute all reload
functionality as well.
(backward compatibility for include
; default: false
)
This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS release 2, for functionality of include
directives. If set to true
, page locations in nested include
directives are relative to the top-level page. If set to false
, page locations are relative to the immediate parent page, as per the JSP 1.2 specification.
(jsp_precompile
checking; default: false
)
Set this to true
to check the HTTP request for a standard jsp_precompile
setting. If precompile_check
is true
and the request enables jsp_precompile
, then the JSP page will be pre-translated only, without execution. Setting precompile_check
to false
improves performance and ignores any jsp_precompile
setting in the request.
For more information about jsp_precompile
, see "Standard JSP Pre-Translation Without Execution", and the Sun Microsystems JavaServer Pages Specification, Version 1.1.
(flag for size reduction of custom tag code; default: false
)
The Oracle9iAS release 2 implementation reduces the size of generated code for custom tag usage, but setting reduce_tag_code
to true
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; default: false
)
A true
setting enables 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
.)
(SQLJ translator executable and options; default: null
)
This parameter is useful in any of the following circumstances:
Specifying a SQLJ translator executable results in its being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container.
You can fully specify the path for the executable, or specify only the executable and let the JSP container look for it in the system path.
For example, to run SQLJ with online semantics checking as user scott/tiger
and with the -ser2class
option enabled, set sqljcmd
to the following value:
sqlj -user=scott/tiger -ser2class=true
Appropriate SQLJ libraries must be in the classpath, and any front-end utility (such as sqlj
in the example) must be in the system path. For Oracle SQLJ, the translator
ZIP or JAR file and the appropriate SQLJ runtime ZIP or JAR file must be in the classpath. See "Key Support Files Provided with OC4J".
(flag to generate static text as characters; default: false
)
A true
setting directs the JSP translator to generate static text in JSP pages as characters, instead of bytes. 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"); %>
Place this statement as close to the beginning of the page as possible.
The false
default setting improves performance in outputting static text blocks.
(default setting for tag handler pooling; default: true
)
You can specify whether JSP tag handler instances are pooled by setting an attribute in the JSP page context. See "Disabling or Enabling Tag Handler Instance Pooling" for information about this.
If there is no setting in the page context, then the behavior is determined by the tags_reuse_default
setting, or is according to a setting of true
(the "default default") if tags_reuse_default
is not specified.
(XML validation of web.xml
and TLD files; default: false
)
This flag 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, xml_validate
is false
by default.
In the OC4J environment, you can set JSP configuration parameters in the global-web-application.xml
file, inside the servlet
tag for the JSP front-end servlet. In the portion of this file shown in "JSP Container Setup", the settings would go where the init params
place holder appears.
The following example lists servlet
tag and subtag settings for the JSP front-end servlet. This sample enables the precompile_check
flag, sets the main_mode
flag to run without checking timestamps, and runs the Java compiler in verbose mode.
<servlet> <servlet-name>jsp</servlet-name> <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class> <init-param> <param-name>precompile_check</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>main_mode</param-name> <param-value>justrun</param-value> </init-param> <init-param> <param-name>javaccmd</param-name> <param-value>javac -verbose</param-value> </init-param> </servlet>
You can override any settings in the global-web-application.xml
file with settings in the web.xml
file for a particular application.
Be aware of the following key configuration files in the OC4J environment.
Global files for all OC4J applications, in the OC4J /j2ee/home/config
directory:
server.xml
--This has an overall <application-server>
element, with an <application>
subelement for each J2EE application. Each <application>
subelement specifies the name of the application and the name and location of its EAR deployment file. The <application-server>
element specifies the name of the general application source directory, where EAR files are placed for deployment and extracted, and the application deployment directory, where OC4J-specific configuration files are generated. Additionally, there is a <web-site>
element for the default Web site, and you can add a <web-site>
element for each additional Web site you want to have on the server.
default-web-site.xml
--This includes a <web-app>
element for each Web application for the default Web site, mapping the application name to the "Web application name". The Web application name corresponds to the WAR deployment file name. Additional Web site XML files, as specified for additional Web sites in the server.xml
file, have the same functionality.
global-web-application.xml
--This is a global configuration file for OC4J Web applications. It establishes default configurations and includes setup and configuration of the JSP front-end servlet, JspServlet
.
application.xml
--This is another parent configuration file for OC4J applications.
data-sources.xml
--This specifies data sources for database connections.
In addition to the global application.xml
file, there is a standard application.xml
file, and optionally an orion-application.xml
file, for each application. These files are in the application EAR file.
Also, in an application WAR file, which is inside the application EAR file, there is a standard web.xml
file and optionally an orion-web.xml
file. These are for application-specific and deployment-specific configuration settings, overriding global-web-application.xml
settings or providing additional settings as appropriate. The global-web-application.xml
and orion-web.xml
files support the same elements, which is a superset of those supported by the web.xml
file.
If the orion-application.xml
and orion-web.xml
files are not present in the archive files, they will be generated during initial deployment, according to settings in the global-web-application.xml
file.
For information about the use of these files, see the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide. For additional information, see "Overview of EAR/WAR Deployment".
This section discusses some initial considerations you should be aware of before running or deploying JSP pages:
The servlet 2.2 and 2.3 specifications provide for each Web application to have its own servlet context. Each servlet context is associated with a directory path in the server file system, which is the base path for modules of the Web application. This is the application root. Each Web application has its own application root. For a Web application in a servlet 2.2 or 2.3 environment, servlets, JSP pages, and static files such as HTML files are all based out of this application root. (By contrast, in servlet 2.0 environments the application root for servlets and JSP pages is distinct from the doc root for static files.)
Note that a servlet URL has the following general form:
http://host[:port]/contextpath/servletpath
When a servlet context is created, a mapping is specified between the application root and the context path portion of a URL. The servlet path is defined in the application web.xml
file. The <servlet>
element within web.xml
associates a servlet class with a servlet name. The <servlet-mapping>
element within web.xml
associates a URL pattern with a named servlet. When a servlet is executed, the servlet container will compare a specified URL pattern with known servlet paths, and pick the servlet path that matches. See the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.
For example, consider an application with the application root /home/dir/mybankapp/mybankwebapp
, which is mapped to the context path /mybank
. Further assume the application includes a servlet whose servlet path is loginservlet
. You can invoke this servlet as follows:
http://host[:port]/mybank/loginservlet
The application root directory name itself is not visible to the end-user.
To continue this example for an HTML page in this application, the following URL points to the file /home/dir/mybankapp/mybankwebapp/dir1/abc.html
:
http://host[:port]/mybank/dir1/abc.html
For each servlet environment there is also a default servlet context. For this context, the context path is simply "/", which is mapped to the default servlet context application root. For example, assume the application root for the default context is /home/dir/defaultapp/defaultwebapp
, and a servlet with the servlet path myservlet
uses the default context. Its URL would be as follows:
http://host[:port]/myservlet
The default context is also used if there is no match for the context path specified in a URL.
Continuing this example for an HTML file, the following URL points to the file /home/dir/defaultapp/defaultwebapp/dir2/def.html
:
http://host[:port]/dir2/def.html
The JSP container uses standard locations on the Web server to look for translated JSP pages, as well as.class
files and .jar
files for any required classes (such as JavaBeans). The container will find files in these locations without any Web server classpath configuration, and has the ability to automatically reload classes in these locations, depending on configuration settings.
The locations for dependency classes are as follows and are relative to the application root:
/WEB-INF/classes/... /WEB-INF/lib
The location for JSP page implementation classes (translated pages) is as follows:
.../_pages/...
The /WEB-INF/classes
directory is for individual Java .class
files. You should store these classes in subdirectories under the classes
directory, according to Java package naming conventions. For example, consider a JavaBean called LottoBean
whose code defines it to be in the oracle.jsp.sample.lottery
package. The JSP container will look for LottoBean.class
in the following location relative to the application root:
/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class
The lib
directory is for .jar
files. Because Java package structure is specified in the .jar
file structure, the .jar
files are all directly in the lib
directory (not in subdirectories). As an example, LottoBean.class
might be stored in lottery.jar
, located as follows relative to the application root:
/WEB-INF/lib/lottery.jar
The _pages
directory is under the following directory in OC4J:
/j2ee/home/application-deployments/app-name/web-app-name/temp
The app-name
is determined through an <application>
element in the OC4J server.xml
file; the web-app-name
, which corresponds to the WAR file name, is mapped to the app-name
through a <web-app>
element in the OC4J default-web-site.xml
file. See the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.
Generated page implementation classes for translated JSP pages are placed in subdirectories under the _pages
directory according to the locations of the original .jsp
files. See "Generated Files and Locations" for information.
|
Copyright © 2000, 2002 Oracle Corporation. All Rights Reserved. |
|