Oracle9iAS Containers for J2EE Servlet Developer's Guide Release 2 (9.0.3) Part Number A97680-01 |
|
This chapter provides an overview of OC4J deployment and describes how to assemble and configure a Web application in OC4J. It covers the following topics:
Because this is a developer's guide, much of it targets an OC4J standalone user. In a standalone environment, you can use the admin.jar
tool for configuration, and optionally deploy to the OC4J default Web application for simplicity.
In a production environment, OC4J is installed within Oracle9iAS with the goal of managing J2EE enterprise systems. Oracle9iAS can manage multiple clustered OC4J processes and is managed and configured through the Oracle Enterprise Manager. Through Enterprise Manager, you can manage and configure your OC4J processes across multiple application server instances and hosts. Thus, you cannot locally manage your OC4J process by using the admin.jar
tool or by hand-editing the configuration files. This undermines the management provided by Enterprise Manager.
This section discusses each of these scenarios a little further, and provides an overview OC4J configuration files, organized as follows:
Note: Users of previous Oracle9iAS releases, can refer to Oracle9i Application Server Migrating to Release 2 (9.0.3) for information about issues in migrating to Oracle9iAS release 2. |
For information about standard J2EE deployment, refer to the J2EE specification, which is available at the following location:
http://java.sun.com/j2ee/docs.html
For application development, or perhaps for a relatively simple Web solution, you can use a single OC4J instance--known as OC4J standalone--outside of the Oracle9iAS environment. To accomplish this, download the oc4j_extended.zip
file from the Oracle Technology Network (OTN). Any standalone OC4J process is not managed by Enterprise Manager and cannot be used within an Oracle9iAS enterprise environment.
You can start, manage, and control standalone OC4J instances through oc4j.jar
(the OC4J standalone executable) and the admin.jar
command-line tool. Update configuration files through the admin.jar
tool or by modifying the XML configuration files by hand (though this is generally not recommended). The admin.jar
tool modifies server.xml
and other configuration files for you, based on settings you specify to the tool. For information about admin.jar
and about how to start, stop, configure, and manage your standalone process, download the standalone version of the Oracle9iAS Containers for J2EE User's Guide along with OC4J_extended.zip
.
In a simple testing mode, you can also deploy to the OC4J default Web application. The default Web application is introduced and its key directories are documented in "OC4J Default Web Application and Key Directories".
Note: During development, also consider the Oracle9i JDeveloper visual development tool for development and deployment. This tool offers a number of conveniences, as described in "Oracle9i JDeveloper Support for Servlet Development". |
In Oracle9iAS production environments, use Enterprise Manager to manage OC4J and other components and to deploy and configure your applications. The Web module configuration pages are discussed under "Web Module Configuration in Oracle Enterprise Manager". See the Oracle9iAS Containers for J2EE User's Guide for further information about using Enterprise Manager with OC4J. You can also refer to the Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for additional general information about Enterprise Manager.
Configure each OC4J instance and its properties--within the context of an application server instance--using Enterprise Manager. After configuration, you start, manage, and control all OC4J instances through Enterprise Manager. You can group several OC4J processes in a cluster. You must use either the Enterprise Manager tool or its command-line tools for starting, stopping, restarting, configuring, and deploying applications. You cannot use the OC4J standalone tool--admin.jar
--for managing OC4J instances created in an Oracle9iAS instance.
Note that in an Oracle9iAS release 2 environment, if you modify configuration files without going through Enterprise Manager, 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.
For additional information about deploying an application that has EJB modules, see the Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide and Reference.
This section lists key XML configuration files supported by OC4J, primarily of interest in an OC4J standalone environment (given that Enterprise Manager in Oracle9iAS automates much of the configuration process). You can divide these configuration files into three categories:
These files, located in the OC4J configuration files directory, are used by OC4J to configure the server on startup. (The configuration files directory is j2ee/home/config
in a standalone environment, and is configurable in an Oracle9iAS environment.)
These are industry standard files, used to configure a particular application.
These are OC4J-specific files, used to configure a particular application. For the most part, they correspond to the J2EE standard files, supporting OC4J-specific extended functionality.
Among the server configuration files are the following:
server.xml
application.xml
global-web-application.xml
default-web-site.xml
(http-web-site.xml
for OC4J standalone)
The global-web-application.xml
and xxx
-web-site.xml
files and their elements and attributes are described later in this chapter--see "The global-web-application.xml and orion-web.xml Files" and "The default-web-site.xml, http-web-site.xml, and Other Web Site XML Files". For more information about OC4J server configuration files, see Oracle9iAS Containers for J2EE User's Guide.
Standard application-level configuration files include the following:
These are described in J2EE standard documentation. The web.xml
file, of particular interest to servlet developers, is described in the Sun Microsystems Java Servlet Specification, Version 2.3.
OC4J-specific application-level configuration files include the following:
For information, see Oracle9iAS Containers for J2EE User's Guide and Oracle Enterprise Manager Administrator's Guide.
Deploying a Web application on OC4J involves at least the following configuration files:
server.xml
default-web-site.xml
, http-web-site.xml
, or appropriate Web site XML file
global-web-application.xml
web.xml
orion-web.xml
How you design, assemble, and build your application is largely up to you. Presumably you will be designing J2EE-compliant modules. Also, a standard directory structure is required for JAR and WAR deployment files, and it is simplest if you follow that when developing the application.
This section covers the following topics:
An OC4J application can consist of one or more J2EE-compliant modules, including:
A J2EE application might consist of only a single Web application module, the client being a Web browser. Or, it might consist of just a Java client and one or more EJB modules. Most business applications include both a Web application module (servlets, JSP pages, and HTML pages) and one or more EJB modules. Optionally, a Java client might be adopted as the front-end for the application, although there are many large applications that rely solely on a Web browser for client access.
The examples in this chapter are derived from the sample application stateless
, which is provided with OC4J. The actual application name is employee
. This application includes both a Web and an EJB module, but building and deploying the Web module follows the same practice as a Web-only application. The sample is also available at the following location:
http://otn.oracle.com/sample_code/tech/java/oc4j/htdocs/oc4jsamplecode/oc4j-demo-ejb.html#Servlet
Figure 3-1, shows the directory structure under the application root directory for a typical Web application. In OC4J, the root directory is <
app-name
>/<
web-app-name
>
, according to the application name and corresponding Web application name. The application name is defined in the server.xml
file and mapped to a Web application name in the default-web-site.xml
file, http-web-site.xml
file, or other Web site XML file. (The default-web-site.xml
file is for Oracle9iAS environments; http-web-site.xml
is for OC4J standalone. See "The default-web-site.xml, http-web-site.xml, and Other Web Site XML Files".)
For easier application assembly and deployment, it is advisable to set up your Web application files in a pattern that is required for the deployment WAR file. The general rules are as follows:
root
attribute of the <web-app>
element of the xxx
-web-site.xml
file for a particular Web site.
<
app_name
>/<
web-app-name
>/WEB-INF/classes
directory, in subdirectories named after packages as appropriate. For example, if you have a servlet called EmployeeServlet
in the employee
package, then the class file should be as follows:
<app_name>/<web-app-name>/WEB-INF/classes/employee/EmpServlet.class
<
app_name
>/<
web-app-name
>/WEB-INF/lib
.
To build an application, if you are not using Oracle9i JDeveloper, you have several options:
build.xml
file at the application root and use the ant
utility to build the application. This utility is open-source and portable (between application servers, as well as operating systems), and is therefore ideal for Java-based applications. You can obtain ant
and accompanying documentation at the following site:
http://jakarta.apache.org/ant/
Some of the sample applications that come with OC4J are set up to use ant
. You can study the accompanying build.xml
files for models.
or:
make
file to automate the compilation and assembly process and use a standard UNIX make
utility or the open-source gmake
utility to execute it.
or:
A build.xml
file or make
file might include steps to create EAR, WAR, and JAR files as appropriate for deployment, or you can create them manually as described in the next section, "Application Packaging".
This section describes the step for packaging an application for deployment. Once you have completed these steps, the application is ready to deploy as appropriate, depending on the target environment (such as OC4J standalone or Oracle9iAS). See "Introduction to Web Application Deployment and Configuration" for an overview of OC4J deployment. The Oracle9iAS Containers for J2EE User's Guide covers deployment in detail for an Oracle9iAS environment. The standalone version of the user's guide, available with the OC4J standalone download from OTN, covers deployment for the standalone scenario.
For J2EE-compatible deployment, each module requires a JAR file for EJB and client modules, or a WAR (Web ARchive) file for Web modules such as servlets and JSP pages.
The top-level archive file, for the entire application, is the EAR (Enterprise ARchive) file, which wraps any WAR and JAR files.
You can create these archive files using the standard Java JAR utility.
To deploy the application, follow these steps:
application.xml
file to specify the application modules. See the OC4J demos (such as the stateless
application) and the Oracle9iAS Containers for J2EE User's Guide for more information about creating this file.
web.xml
descriptor file. This file is defined in the Servlet 2.3 specification. In addition, there is some introductory information about web.xml
in "The global-web-application.xml and orion-web.xml Files".
ejb-jar.xml
file for each. See the Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide and Reference for more information about deploying EJB modules.
% jar -cvf <app_name>.war .
This creates a JAR file with a .war
extension. You can also examine the contents of the WAR file using the jar
command. Here is an example, taken from the WAR file of the OC4J stateless
sample application:
% cd <app_root>/web % jar -tf employee-web.war META-INF/ META-INF/MANIFEST.MF WEB-INF/ WEB-INF/classes/ WEB-INF/classes/employee/ WEB-INF/classes/employee/EmployeeServlet.class WEB-INF/orion-web.xml WEB-INF/web.xml delete.jsp list.jsp index.html edit.jsp add.jsp
The JAR utility creates the META-INF/MANIFST.MF
file. You should not have to modify it.
jar
command to create this file, as in the following example:
% jar -cvf employee.EAR .
Here is an example of an EAR file for the sample application stateless
:
% jar -tf employee.ear META-INF/ META-INF/MANIFEST.MF META-INF/application.xml META-INF/orion-application.xml employee-ejb.jar employee-web.war employee-client.jar
For more information about EAR files, see the Oracle9iAS Containers for J2EE User's Guide.
% jar -tf employee-ejb.jar META-INF/ META-INF/MANIFEST.MF META-INF/ejb-jar.xml META-INF/orion-ejb-jar.xml employee/ employee/EmpRecord.class employee/Employee.class employee/EmployeeBean.class employee/EmployeeHome.class
See the Oracle9iAS Containers for J2EE Enterprise JavaBeans Developer's Guide and Reference for information about creating an EJB deployment descriptor and deploying an EJB application.
This section discusses XML configuration files that are central to servlet development and invocation in an OC4J environment, including detailed element and attribute descriptions. The following topics are covered:
The detailed discussion in this section regarding configuration files and their elements and attributes assumes an OC4J standalone development environment. In an Oracle9iAS environment using Enterprise Manager, configuration is through Enterprise Manager Web module pages, and many of the files and their properties are invisible to the user.
For considerations in configuring and deploying a production application with Enterprise Manager in Oracle9iAS, see "OC4J Deployment and Configuration with Oracle9iAS and Enterprise Manager".
Note:
The elements described here do not use body values unless noted, and do not have subelements unless noted. Element attribute settings are in quotes. Here is the general syntax for an element with attributes but no subelements or body value:
<elementname attr1="value1" attr2="value2" ... />
If there are subelements (that have no subelements or body value themselves), the syntax is as follows:
<elementname ... > <subelement1 ... /> <subelement2 ... /> ... </elementname>
If a body value is used, the syntax is as follows:
<elementname ... >value</elementname>
This section describes the OC4J-specific global-web-application.xml
and orion-web.xml
files, and their relationships to the standard web.xml
file. Overviews of these files and their features are followed by detailed descriptions of the elements supported by global-web-application.xml
and orion-web.xml
. This section is organized as follows:
The file global-web-application.xml
, in the OC4J configuration files directory, is the descriptor for the OC4J "global Web application". The elements in this file define the default behavior of an OC4J Web application.
There is also, for each Web application, an application-specific web.xml
file and an optional deployment-specific orion-web.xml
file. Both of these files should be in the application /WEB-INF
directory. Use of web.xml
is standard, according to the Servlet 2.3 specification. Elements defined for the orion-web.xml
file are a superset of those defined for web.xml
, adding elements for OC4J-specific features. The orion-web.xml
DTD is also used for global-web-application.xml
--the two files support the same elements.
On deployment of a Web application, OC4J generates an orion-web.xml
file, using the settings from the parent global-web-application.xml
file. You can then update orion-web.xml
as desired to override default values. You can also package orion-web.xml
as part of your EAR file if you want to specify resource mappings or OC4J-specific configuration.
The global-web-application.xml
, orion-web.xml
, and web.xml
files all support a <web-app>
element, which has many subelements. As you can see in "Default global-web-application.xml File", the global-web-application.xml
file typically defines defaults for many settings of the <web-app>
element and its subelements. The <web-app>
element and subelements in the web.xml
file are for desired settings specific to an application. When deploying an application, the <web-app>
element and subelements in orion-web.xml
are for overriding any settings of the web.xml
<web-app>
element for this particular deployment.
OC4J-specific features are supported through the <orion-web-app>
element and its many subelements in the global-web-application.xml
and orion-web.xml
files. The <web-app>
element in these files is a subelement of <orion-web-app>
. This element and its subelements in orion-web.xml
can override global-web-application.xml
settings of OC4J features for a particular application deployment.
The web.xml
descriptor file specifies the following servlet 2.3 standard configurations, among many others:
(Only the Home interface JNDI name is provided, because only the Home interface is looked up through JNDI.)
(Filter settings are outside the <web-app>
element.)
The global-web-application.xml
and orion-web.xml
descriptor files, in addition to being able to specify almost all the same configurations as in the web.xml
<web-app>
element and subelements, can specify the following OC4J-specific configurations:
The element descriptions in this section are applicable to either global-web-application.xml
or to an application-specific orion-web.xml
configuration file. The global-web-application.xml
file configures the global application and sets defaults, and the orion-web.xml
can override these defaults for a particular application deployment as appropriate.
See "Syntax Notes for Element Documentation" for general syntax information.
This is the root element for specifying OC4J-specific configuration of a Web application.
Note:
The |
Subelements:
<classpath> <context-param-mapping> <mime-mappings> <virtual-directory> <access-mask> <cluster-config> <servlet-chaining> <request-tracker> <servlet-filter> <session-tracking> <resource-ref-mapping> <env-entry-mapping> <security-role-mapping> <ejb-ref-mapping> <expiration-setting> <web-app-class-loader> <web-app>
Attributes:
default-buffer-size
: Specifies the default size of the output buffer for servlet responses, in bytes. The default is "2048"
.
default-charset
: This is the ISO character set to use by default. The default is "iso-8859-1"
.
deployment-version
: This is the version of OC4J under which this Web application was deployed. If this value does not match the current version, then the application is redeployed. This is an internal server value and should not be changed.
development
: This is a convenience flag during development. If development
is set to "true"
, then each time you change the servlet source and save it in a particular directory, the OC4J server automatically compiles and redeploys the servlet the next time it is invoked. The directory is determined by the setting of the source-directory
attribute. Supported values for development
are "true"
and "false"
(default).
source-directory
: Specifies where to look for source files for classes to be auto-compiled if the development
attribute is set to "true"
. The default is "WEB-INF/src"
if it exists, otherwise "WEB-INF/classes"
.
directory-browsing
: Specifies whether to allow directory browsing. Supported values are "allow"
and "deny"
(default).
document-root
: Defines the path-relative or absolute directory to use as the root for served pages. The default setting is "../"
.
file-modification-check-interval
: This is the amount of time, in milliseconds, for which a file-modification check is valid. Within that time period of the last check, further checks are not necessary. Zero or a negative number specifies that a check always occurs. The default is "1000"
.
get-locale-from-user
: Specifies whether to determine the specific locale of the logged-in user before looking at the request headers for the information. Supported values are "true"
and "false"
(default, for performance reasons).
jsp-print-null
: Set this flag to "false
" to print an empty string instead of the default "null" string for null output from a JSP page. The default is "true
".
jsp-timeout
: Specify an integer value, in seconds, after which any JSP page will be removed from memory if it has not been requested. This frees up resources in situations where some pages are called infrequently. The default value is 0 (zero), for no timeout.
persistence-path
: Specifies where to store HttpSession
objects for persistence across server restarts. Session objects must contain properly serializable or remoteable values, or EJB references, for this to work. There is no default.
servlet-webdir
: Specifies the servlet runner path for invoking a servlet by name--anything appearing after this in a URL is assumed to be a class name. The default setting is "/servlet"
. This is typically for use in an OC4J standalone environment during development and testing. For deployment, the standard web.xml
mechanisms for defining the context path and servlet path should be used.
Important:
The default setting of |
temporary-directory
: This is the absolute or relative path to a temporary directory that can be used by servlets and JSP pages for scratch files. The default is the ./temp
directory.
This specifies a codebase where classes used by this application can be found (servlets and JavaBeans, for example).
Attribute:
path
: This is the path or URL for the codebase, either absolute or relative to the location of the orion-web.xml
file.
In orion-web.xml
, this overrides the value of a context-param
setting in the web.xml
file. It is used to keep the EAR assembly clean of deployment-specific values. The new value is specified in the tag body.
Attribute:
This defines the path to a file containing MIME mappings to use.
Attribute:
path
: This is the path or URL for the file, either absolute or relative to the location of the orion-web.xml
file.
This adds a virtual directory mapping, used to include files that do not physically reside under the document root among the Web-exposed files.
Attributes:
real-path
: This is a real path, such as /usr/local/realpath
on UNIX or C:\testdir
in Windows.
virtual-path
: This is a virtual path to map to the specified real path.
Use subelements of <access-mask>
to specify optional access masks for this application. You can use host names or domains to filter clients, through <host-access>
subelements, or you can use IP addresses and subnets to filter clients, through <ip-access>
subelements, or you can do both.
Subelements:
<host-access> <ip-access>
Attribute:
default
: Specifies whether to allow requests from clients that are not identified through a <host-access>
or <ip-access>
subelement. Supported values are "allow"
(default) and "deny"
. There are separate mode
attributes for the <host-access>
and <ip-access>
subelements, which are used to specify whether to allow requests from clients that are identified through those subelements.
This subelement of <access-mask>
specifies a host name or domain to allow or deny access.
Attributes:
domain
: This is the host or domain.
mode
: Specifies whether to allow or deny access to the specified host or domain. Supported values are "allow
" (default) or "deny
".
This subelement of <access-mask>
specifies an IP address and subnet mask to allow or deny access.
Attributes:
ip
: This is the IP address, as a 32-bit value (example: "123.124.125.126
").
netmask
: This is the relevant subnet mask (example: "255.255.255.0"
).
mode
: Specifies whether to allow or deny access to the specified IP address and subnet mask. Supported values are "allow
" (default) or "deny
".
Use this element if, and only if, the application is to be clustered. Remove it or comment it out otherwise. Clustered applications have their ServletContext
and HttpSession
data shared between the applications in the cluster. Shared objects must either be serializable or be remote RMI objects implementing the java.rmi.Remote
interface.
See the Oracle9i Application Server Performance Guide for general information about clustering.
Attributes:
host
: This is the multicast host/IP for transmitting and receiving cluster data. The default is "230.0.0.1"
.
id
: This is the ID (number) of this cluster node to identify itself within the cluster. The default is based on the local machine IP.
port
: This is the port through which to transmit and receive cluster data. The default is "9127"
.
This element specifies a servlet to call when the response of the current servlet is set to a specified MIME type. The specified servlet will be called after the current servlet. This is known as servlet chaining and is useful for filtering or transforming certain kinds of output. Servlet chaining is an older servlet mechanism that is similar to servlet filtering. (See <servlet-filter>
below.)
Attributes:
mime-type
: This is the MIME type to trigger the chaining, such as "text/html"
.
servlet-name
: This is the servlet to call when the specified MIME type is encountered. The servlet name is tied to a servlet class through its definition in the <web-app>
element of global-web-application.xml
, web.xml
, or orion-web.xml
.
This element specifies a servlet to use as the request tracker. A request tracker is called for each request, for use as desired. A request tracker might be useful for logging information, for example.
Attribute:
This element specifies a servlet to use as a filter. Filters are invoked for every request, and can be used to either preprocess the request or post-process the response. Optionally, the filter would apply only to requests from servlets that match a specified URL pattern. Using <servlet-filter>
to post-process a response is similar in nature to using <servlet-chaining>
(see above), but is not based on MIME type.
Attributes:
servlet-name
: This is the servlet to call as the filter. The servlet name is tied to a servlet class through its definition in the <web-app>
element of global-web-application.xml
, web.xml
, or orion-web.xml
.
url-pattern
: This is an optional URL pattern to use as a qualifier for requests that are passed through the filter. For example:
url-pattern="/the/*.pattern"
For general information about servlet filters, see "Servlet Filters".
This element specifies the session-tracking settings for this application. Session tracking is accomplished through cookies, assuming a cookie-enabled browser.
For general information about servlet sessions, see "Servlet Sessions".
The servlet to use as the session tracker is specified through a subelement.
Subelement:
<session-tracker>
Attributes:
autojoin-session
: Specifies whether users should be assigned a session as soon as they log in to the application. Supported values are "true"
and "false"
(default).
cookies
: Specifies whether to send session cookies. Supported values are "enabled"
(default) and "disabled"
.
cookie-domain
: This is the relevant domain for cookies. This is useful for sharing session state between nodes of a Web application running on different hosts.
cookie-max-age
: This number is sent with the session cookie and specifies a maximum interval (in seconds) for the browser to save the cookie. By default, the cookie is kept in memory during the browser session and discarded afterward.
This subelement of <session-tracking>
specifies a servlet to use as the session tracker. Session trackers are invoked as soon as a session is created and are useful for logging information, for example.
Attribute:
Use this element to declare a reference to an external resource such as a data source, JMS queue, or mail session. This ties a resource reference name to a JNDI location when deploying.
Subelement:
<lookup-context>
Attributes:
location
: This is the JNDI location from which to look up the resource. For example:
location="jdbc/TheDS"
name
: This is the resource reference name, which matches the name of a resource-ref
element in the web.xml
file. For example:
name="jdbc/TheDSVar"
This subelement of <resource-ref-mapping>
specifies an optional javax.naming.Context
that will be used to retrieve the resource. This is useful when connecting to third-party modules, such as a third-party JMS server, for example. Either use the context implementation supplied by the resource vendor, or, if none exists, write an implementation that in turn negotiates with the vendor software.
Subelement:
<context-attribute>
Attribute:
location
: This is the name to look for in the foreign (such as third-party) context when retrieving the resource.
This subelement of <lookup-context>
(which is a subelement of <resource-ref-mapping>
) specifies an attribute to send to the foreign context.
The only mandatory attribute in JNDI is java.naming.factory.initial
, which is the class name of the context factory implementation.
Attributes:
In orion-web.xml
, this element overrides the value of an env-entry
setting in the web.xml
file. It is used to keep the EAR assembly clean of deployment-specific values. The new value is specified in the tag body.
Attribute:
This element maps a security role to specified users and groups, or to all users. It maps to a security role of the same name in the web.xml
file. The impliesAll
attribute or an appropriate combination of subelements--<group>
, <user>
, or both--should be used.
Subelements:
<group> <user>
Attributes:
impliesAll
: Specifies whether this mapping implies all users. Supported values are "true"
or "false"
(default).
name
: This is the name of the security role. It must match a name specified in a <role-name>
subelement of a <security-role>
element in web.xml
.
Use this subelement of <security-role-mapping>
to specify a group to map to the security role of the parent <security-role-mapping>
element. All the members of the specified group are included in this role.
Attribute:
Use this subelement of <security-role-mapping>
to specify a user to map to the security role of the parent <security-role-mapping>
element.
Attribute:
This element creates a mapping between an EJB reference, defined in an <ejb-ref>
element, and a JNDI location when deploying.
The <ejb-ref>
element can appear within the <web-app>
element of orion-web.xml
or web.xml
, and is used to declare a reference to an EJB.
Attributes:
location
: This is the JNDI location from which to look up the EJB home.
name
: This is the EJB reference name, which matches the <ejb-ref-name>
setting of the <ejb-ref>
element.
This element sets the expiration for a given set of resources. This is useful for caching policies, such as for not reloading images as frequently as documents.
Attributes:
expires
: This is the number of seconds before expiration, or "never"
for no expiration.
url-pattern
: This is the URL pattern that the expiration applies to, such as in the following example:
url-pattern="*.gif"
Use this element for class loading instructions.
Attributes:
search-local-classes-first
: Set this to "true
" to search and load WAR file classes before system classes. The default is "false
".
include-war-manifest-class-path
: Set this to "false
" to not include the class path specified in the WAR file manifest Class-Path
attribute when searching and loading classes from the WAR file (regardless of the search-local-classes-first
setting). The default is "true
".
This element is used as in the standard web.xml
file; see the Servlet 2.3 specification for details. In global-web-application.xml
, defaults for <web-app>
settings can be established. In web.xml
, application-specific <web-app>
settings can override the defaults. In orion-web.xml
, deployment-specific <web-app>
settings can override the settings in web.xml
.
This is an example of a default global-web-application.xml
file (may be subject to change in the shipped product):
<?xml version="1.0" standalone='yes'?> <!DOCTYPE orion-web-app PUBLIC '//Evermind//Orion web-application' 'http://xmlns.oracle.com/ias/dtds/orion-web.dtd'> <orion-web-app jsp-cache-directory="./persistence" servlet-webdir="/servlet" development="false" > <!-- The mime-mappings for this server --> <mime-mappings path="./mime.types" /> <web-app> <!-- <servlet> <servlet-name>xsl</servlet-name> <servlet-class>com.evermind.servlet.XSLServlet </servlet-class> <init-param> <param-name>defaultContentType</param-name> <param-value>text/html</param-value> </init-param> </servlet> --> <servlet> <servlet-name>jsp</servlet-name> <servlet-class>oracle.jsp.runtimev2.JspServlet </servlet-class> </servlet> <servlet> <servlet-name>rmi</servlet-name> <servlet-class>com.evermind.server.rmi.RMIHttpTunnelServlet </servlet-class> </servlet> <servlet> <servlet-name>rmip</servlet-name> <servlet-class>com.evermind.server.rmi.RMIHttpTunnelProxyServlet </servlet-class> </servlet> <servlet> <servlet-name>ssi</servlet-name> <servlet-class>com.evermind.server.http.SSIServlet </servlet-class> </servlet> <servlet> <servlet-name>cgi</servlet-name> <servlet-class>com.evermind.server.http.CGIServlet </servlet-class> </servlet> <servlet> <servlet-name>perl</servlet-name> <servlet-class>com.evermind.server.http.CGIServlet </servlet-class> <init-param> <param-name>interpreter</param-name> <param-value>perl</param-value> </init-param> </servlet> <servlet> <servlet-name>php</servlet-name> <servlet-class>com.evermind.server.http.CGIServlet </servlet-class> <init-param> <param-name>interpreter</param-name> <param-value>php</param-value> </init-param> </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> <servlet-mapping> <servlet-name>cgi</servlet-name> <url-pattern>/*.cgi</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>perl</servlet-name> <url-pattern>/*.pl</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>php</servlet-name> <url-pattern>/*.php</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>php</servlet-name> <url-pattern>/*.php3</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>php</servlet-name> <url-pattern>/*.phtml</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>ssi</servlet-name> <url-pattern>/*.shtml</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>default.jsp</welcome-file> </welcome-file-list> </web-app> </orion-web-app>
This section describes OC4J Web site XML files, including default-web-site.xml
for the default OC4J Web site in Oracle9iAS, and http-web-site.xml
for OC4J standalone. The documentation includes descriptions of the elements and attributes of these files. (All Web site XML files use the same DTD.)
A Web site XML file contains the configurations for an OC4J Web site. The file default-web-site.xml
, in the OC4J configuration files directory, configures the default OC4J Web site for Oracle9iAS and also defines default configurations for any additional Web site XML files. The file http-web-site.xml
configures the HTTP Web site for an OC4J standalone environment.
The names of any additional Web site XML files are defined in the server.xml
file, in the path
attribute of any <web-site>
elements. See the Oracle9iAS Containers for J2EE User's Guide for more information about the server.xml
file.
Configuration settings in Web site XML files include the following:
The element descriptions in this section apply to default-web-site.xml
, http-web-site.xml
, and the Web site XML files for any additional OC4J Web sites.
See "Syntax Notes for Element Documentation" for general syntax information.
This is the root element for configuring an OC4J Web site.
Subelements:
<description> <frontend> <web-app> <default-web-app> <user-web-apps> <access-log>
Attributes:
cluster-island
: A cluster island is two or more Web servers that share session failover state for replication. Use the cluster-island
attribute when clustering the Web tier between multiple OC4J instances in Oracle9iAS. If this attribute is set to a cluster island ID (number spawning from 1 and up), then this Web site will participate as a back-end server in the island specified by the ID. The ID is a chosen number that depends on your clustering configuration. If only one island is used, the ID is always 1.
See the Oracle9i Application Server Performance Guide for general information about clustering.
display-name
: This is for a user-friendly or informal Web site name to display in GUI configuration tools when the site is being administered.
host
: This is the host IP address for this site. If "[ALL]"
is specified, then all IP addresses of the server are used.
log-request-info
: Specifies whether to log information about the incoming request (such as headers) if an error occurs. Supported values are "true"
and "false"
(default).
max-request-size
: Sets a maximum size, in bytes, for incoming requests. If a client sends a request that exceeds this maximum, it will receive a "request entity too large" error. The default maximum is 15000.
secure
: Specifies whether to support SSL (Secure Socket Layer) functionality. Possible values are "true"
and "false"
(default); however, because the OC4J servlet container in Oracle9iAS release 2 does not directly support SSL, leave this at the "false
" setting.
protocol
: Specifies the protocol that the Web site is using. Possible values are "http"
, "https"
, and "ajp13"
(Apache JServ Protocol, or AJP--default); however, in a production environment with Oracle9iAS release 2, you should use only the "ajp13
" setting. The AJP protocol is for use with Oracle HTTP Server and mod_oc4j
. Note that each port must have a corresponding protocol, and vice versa.
The "http
" setting is for development environments or OC4J standalone only. The "https
" setting is not currently supported.
port
: This is the port number for this Web site. Each port must have a corresponding protocol, and vice versa. Also note that for AJP, port 0 has a special meaning. Any nonzero port number is static, but with a port
setting of "0"
, the servlet container dynamically accesses any available port. This functionality is invisible to the user, who is only aware of the Oracle HTTP Server port specified through the browser (such as 7777, typical for access through the Oracle HTTP Server with Oracle9iAS Web Cache enabled).
In OC4J standalone, a port
setting of 8888 is used for direct access to the OC4J listener.
use-keep-alives
: Typical behavior for a servlet container is to close a connection once a request has been completed. With a use-keep-alives
setting of "true"
, however, a connection is maintained across requests. For AJP protocol, connections are always maintained and this attribute is ignored. For other protocols, the default is "true"
; disabling it may cause major performance loss.
virtual-hosts
: This optional setting is useful for virtual sites sharing the same IP address. The value is a comma-delimited list of host names tied to this Web site.
You can use the body of this element for a brief description of the Web site.
This specifies a perceived front-end host and port of this Web site as seen by HTTP clients. When the site is behind something like a load balancer or firewall, the <frontend>
specification is necessary to provide appropriate information to Web application code for functionality such as URL rewriting. Using the host and port specified in the <frontend>
element, the back-end server that is actually running the application knows to refer to the front-end instead of to itself in any URL rewriting. This way, subsequent requests properly come in through the front-end again instead of trying to access the back-end directly.
Attributes:
host
: This is the host name of the front-end server, such as "www.acme.com"
.
port
: This is the port number of the front-end server, such as "80"
.
This element creates a reference to a Web application--a J2EE application, defined in the server.xml
file, that is bound to this particular Web site. Each instance of a J2EE application bound to a particular Web site is a separate Web entity.
The Web application is bound at the location specified by the root
attribute.
Attributes:
application
: This is the name of the J2EE application, as specified by the application
attribute of an <application>
element in the server.xml
file.
load-on-startup
: Optional attribute to specify whether this Web application should be preloaded on application startup. Otherwise, it is loaded upon the first request for it. Supported values are "true"
and "false"
(default).
Preloading of individual servlets, through <load-on-startup>
elements in the application web.xml
file, is possible only if this <web-app>
element load-on-startup
attribute is enabled. See "Servlet Preloading" for more information.
max-inactivity-time
: Optional attribute to specify a period of minutes of inactivity after which the Web application will automatically be shut down. The default is no automatic shutdown.
name
: This is the desired Web application name. For example, if the J2EE application name is MyApp
, and this is the second of several Web sites, you might want a setting of MyWebApp2
. This name must be the same as the corresponding name specified in a <web-module>
element in the application.xml
file, to be bound to this Web site under the specified root context.
root
: The path on this Web site to which the Web application should be bound. For example, if the Web application CatalogApp
at Web site www.site.com
is bound to the root setting "/catalog"
, then it can be accessed as follows:
http://www.site.com/catalog/CatalogApp
shared
: This indicates whether multiple bindings (different Web sites and context roots) can be shared. Supported values are "true"
and "false"
(default). Sharing implies the sharing of everything that makes up a Web application, including sessions, servlet instances, and context values. A possible use for this mode would be to share a Web application between an AJP site and an HTTP site at the same context path.
If an HTTPS Web application is marked as shared, its session tracking strategy reverts from SSL session tracking to session tracking through cookies or URL rewriting. This could possibly make the Web application less secure, but might be necessary to work around issues such as SSL session timeouts not being properly supported in some browsers. Oracle HTTP Server supports HTTPS.
This element creates a reference to the default Web application of this Web site.
The default Web application is bound to "/j2ee
" by default in default-web-site.xml
for an Oracle9iAS environment. In OC4J standalone, the default Web application is bound to "/
" by default in http-web-site.xml
.
Attributes are the same as for the <web-app>
element described immediately above, with the following exceptions:
Use this element to support user directories and applications. Each user has his or her own Web application and associated web-application.xml
file. User applications are reached at /
username
/
from the server root.
Attributes:
max-inactivity-time
: Optional attribute to specify a period of minutes of inactivity after which the user application will automatically be shut down. The default is no automatic shutdown.
path
: This is a path to specify the local directory of the user application, including a wildcard for the user name. The default path setting on UNIX, for example, is "/home/
username
"
, where username
is replaced by the particular user name.
This element specifies information about the access log for this Web site, including the path and what information is included. This is where incoming requests are logged.
Attributes:
format
: Specify one or more of several supported variables that result in information being prepended to log entries. Supported variables are $time
$request
, $ip
, $host
, $path
, $size
, $method
, $protocol
, $user
, $status
, $referer
, $time
, $agent
, $cookie
, $header
, and $mime
. Between variables, you can type in any separator characters that you want to appear between values in the log message. The default setting is as follows:
"$ip - $user - [$time] '$request' $status $size"
As an example, this would result in log messages such as the following (with the second message wrapping around to a second line):
148.87.1.180 - - [06/Nov/2001:10:23:18 -0800] 'GET / HTTP/1.1' 200 2929 148.87.1.180 - - [06/Nov/2001:10:23:53 -0800] 'GET /webservices/statefulTest HTTP/1.1' 200 301
The user is null, the time is in brackets (as specified in the format
setting), the request is in quotes (as specified), and the status and size in the first message are 200 and 2929, respectively.
path
: Specifies the path and name of the access log, such as "./access.log"
. The default setting in default-web-site.xml
is the following:
path="../log/default-web-access.log"
split
: Specifies how often to begin a new access log. Supported values are "none"
(never), "hour"
, "day"
, "week"
, or "month"
. For a value other than "none"
, logs are named according to the suffix
attribute.
suffix
: Specifies timestamp information to append to the base file name of the logs (as specified in the path
attribute) if splitting is used, to make a unique name for each file. The format used is that of java.text.SimpleDateFormat
, and symbols used in suffix
settings are according to the symbology of that class. For information about SimpleDateFormat
and the format symbols that is uses, refer to the Sun Microsystems Javadoc at the following location:
http://java.sun.com/products/jdk/1.2/docs/api/index.html
The default suffix
setting is "-yyyy-MM-dd"
. These characters are case-sensitive, as described in the SimpleDateFormat
documentation.
As an example, assume the following <access-log>
element (using the default suffix
value):
<access-log path="c:\foo\web-site.log" split="day" />
Log files would be named such as in the following example:
c:\foo\web-site-2001-11-17.log
This is an example of a default default-web-site.xml
file (may be subject to change in the shipped product):
<?xml version="1.0" standalone='yes'?> <!DOCTYPE web-site PUBLIC "Oracle9iAS XML Web-site" "http://xmlns.oracle.com/ias/dtds/web-site.dtd"> <!-- change the host name below to your own host name. Localhost will --> <!-- not work with clustering --> <!-- also add cluster-island attribute as below <web-site host="localhost" port="0" protocol="ajp13" display-name="Default Oracle 9iAS Java WebSite" cluster-island="1" > --> <web-site port="0" protocol="ajp13" display-name="Default Oracle9iAS Containers for J2EE Web Site"> <!-- Uncomment the following line when using clustering --> <!-- <frontend host="your_host_name" port="80" /> --> <!-- The default web-app for this site, bound to the root --> <default-web-app application="default" name="defaultWebApp" root="/j2ee" /> <web-app application="default" name="dms" root="/dmsoc4j" /> <web-app application="ojspdemos" name="ojspdemos-web" root="/ojspdemos" /> <!-- Uncomment the following to access these apps. <web-app application="callerInfo" name="callerInfo-web" root="/jazn" /> <web-app application="news" name="news-web" root="/news" /> <web-app application="logger" name="messagelogger-web" root="/messagelogger" /> <web-app application="ws_example" name="ws_example" root="/webservices" /> --> <!-- Access Log, where requests are logged to --> <access-log path="../log/default-web-access.log" /> </web-site>
The direct use of global-web-application.xml
, orion-web.xml
, and default-web-site.xml
elements and attributes described earlier in this chapter is generally for development in an OC4J standalone environment. In an Oracle9iAS environment, such as for production deployment, use Enterprise Manager for such configuration. This section covers Enterprise Manager pages related to Web module configuration and deployment. Some of the pages allow you to alter orion-web.xml
, global-web-application.xml
, and default-web-site.xml
settings. Other pages display web.xml
settings, which you can override through orion-web.xml
settings.
The following Enterprise Manager pages are discussed:
Each page description notes the corresponding web.xml
, orion-web.xml
(or global-web-application.xml
), or default-web-site.xml
elements and attributes. The orion-web.xml
elements and attributes are documented in "Element Descriptions for global-web-application.xml and orion-web.xml". The default-web-site.xml
elements and attributes are covered in "Element Descriptions for Web Site XML Files". For information about web.xml
elements, refer to the Sun Microsystems Java Servlet Specification, Version 2.3.
See the Oracle9iAS Containers for J2EE User's Guide for further information about using Enterprise Manager with OC4J. For general information about using Enterprise Manager to manage your Oracle9iAS environment, see the Oracle9i Application Server Administrator's Guide.
From the Oracle9iAS Application Server Instance Home Page (the main page you reach when you first access Enterprise Manager), you can drill down to any of the running OC4J instances by selecting the name of the instance (OC4J_home
, for example) in the System Components table. Enterprise Manager will display the OC4J Home Page for that instance.
Figure 3-2 and Figure 3-3 show portions of the OC4J Home Page for the OC4J_home
instance.
The OC4J Home Page enables you to access instance properties. In particular, relating to topics covered in this manual, note the following:
Figure 3-4 shows the key portion of the Enterprise Manager Deploy Web Application Page, which is the page for deploying a WAR file. Drill down to this page from any OC4J Home Page, such as the page for OC4J_home
, by clicking the Deploy WAR file button.
In the Deploy Web Application Page, click the Browse button to select a WAR file to deploy. Then specify the application name along with a URL to map to the application. Specifying the application name will result in an entry in the server.xml
file, and there will also be a resulting entry in the default-web-site.xml
file mapping the application name to the URL. This is accomplished through the application
and root
attributes of a <web-app>
subelement of the <web-site>
element. In addition, the mod_oc4j.conf
configuration file for the Oracle HTTP Server mod_oc4j
Apache mod is updated with appropriate mount points.
Figure 3-5 shows the key portion of the Enterprise Manager Website Properties Page for an OC4J instance. Drill down to this page from the OC4J Home Page, such as the page for OC4J_home
, by selecting Website Properties under Instance Properties in the Administration section of the page.
Among other things, this page enables you to specify whether each application should be loaded automatically when OC4J starts. (Otherwise, an application is not loaded until the first request for it.) This corresponds to the load-on-startup
attribute of the appropriate <web-app>
subelement of the <web-site>
element in the default-web-site.xml
file. (For general information about loading an application at OC4J startup, see "Servlet Preloading".)
From the Website Properties Page, drill down to the Web Module Page for any particular Web module. In the sample page above, for example, you can select webapp
to drill down to the Web Module Page for that module.
Figure 3-6 shows the key portion of the Enterprise Manager Web Module Page for the module webapp
. Drill down to the Web Module Page for a particular module by selecting the module name in the Website Properties Page.
From the Web Module Page, you can access several categories of Web module properties through the following links under Properties in the Administration section of the page:
Figure 3-7 and Figure 3-8 show portions of the Enterprise Manager Web Module Properties Page for a particular module. Drill down to this page by selecting General under Properties in the Administration section of the Web Module Page.
Correspondence of these settings to orion-web.xml
elements is as follows.
In the General section:
servlet-webdir
attribute of the <orion-web-app>
element.
temporary-directory
attribute of the <orion-web-app>
element.
default-buffer-size
attribute of the <orion-web-app>
element.
file-modification-check-interval
attribute of the <orion-web-app>
element.
get-locale-from-user
attribute of the <orion-web-app>
element.
In the Session Configuration section:
cookies
attribute of the <session-tracking>
element, which is a subelement of the <orion-web-app>
element.
autojoin-session
attribute of the <session-tracking>
element.
<session-timeout>
subelement of the <session-config>
subelement of the standard <web-app>
element. You can use a <web-app>
subelement under <orion-web-app>
in orion-web.xml
for deployment-specific overrides of <web-app>
settings in the application web.xml
file.
cookie-max-age
attribute of the <session-tracking>
element.
cookie-domain
attribute of the <session-tracking>
element.
persistence-path
attribute of the <orion-web-app>
element.
In the Class Paths section:
path
attribute of a <classpath>
subelement of the <orion-web-app>
element.
In the Session Trackers section:
servlet-name
attribute of a <session-tracker>
element, which is a subelement of the <session-tracking>
element.
In the Virtual Directories section:
real-path
and virtual-path
attributes of a <virtual-directory>
subelement of the <orion-web-app>
element.
In the Tag Libraries section:
Figure 3-9 and Figure 3-10 show portions of the Enterprise Manager Web Module Mappings Page for a particular module. Drill down to this page by selecting Mappings under Properties in the Administration section of the Web Module Page.
These settings all correspond to subelements of the <web-app>
element in the web.xml
file. You can use a <web-app>
subelement under <orion-web-app>
in orion-web.xml
for deployment-specific overrides of these settings. You can use the Advanced Properties Page for this purpose--see "Enterprise Manager Web Module Advanced Properties Page".
In the Servlet Mappings section:
<servlet-name>
and <url-pattern>
subelements of a <servlet-mapping>
subelement of the <web-app>
element.
In the MIME Mappings section:
<mime-type>
and <extension>
subelements of a <mime-mapping>
subelement of the <web-app>
element.
In the Welcome Files section:
<welcome-file>
subelement of the <welcome-file-list>
subelement of the <web-app>
element.
In the Error Pages section:
<error-code>
and <location>
subelements of an <error-page>
subelement of the <web-app>
element.
<exception-type>
and <location>
subelements of an <error-page>
subelement of the <web-app>
element.
Figure 3-11 shows the key portion of the Enterprise Manager Web Module Filtering and Chaining Page for a particular module. Drill down to this page by selecting Filtering and Chaining under Properties in the Administration section of the Web Module Page.
Correspondence of these settings to orion-web.xml
elements is as follows.
In the Servlet Filtering section:
servlet-name
and url-pattern
attributes of a <servlet-filter>
subelement of the <orion-web-app>
element. The servlet name you specify is tied to a servlet class through its standard configuration in the web.xml
file.
In the Servlet Chaining section:
servlet-name
and mime-type
attributes of a <servlet-chaining>
subelement of the <orion-web-app>
element. The servlet name you specify is tied to a servlet class through its standard configuration in the web.xml
file.
Figure 3-12 shows most of the Enterprise Manager Web Module Environment Page for a particular module. Drill down to this page by selecting Environment under Properties in the Administration section of the Web Module Page.
This page shows settings for servlet context parameter overrides, environment entry overrides, and resource references. The overrides indicate settings in the orion-web.xml
file that override corresponding web.xml
settings.
Correspondence of these settings to web.xml
and orion-web.xml
elements is as follows.
In the Servlet Context Parameters section:
web.xml
<context-param>
elements that can be overridden for this deployment, along with any Deployed Value overrides that have already been specified. Enter a new value in the Deployed Value column to specify a new override. Doing so creates a <context-param-mapping>
entry in orion-web.xml
.
In the Environment Entries section:
web.xml
<env-entry>
elements that can be overridden for this deployment, along with any Deployed Value overrides that have already been specified. Enter a new value in the Deployed Value column to specify a new override. Doing so creates an <env-entry-mapping>
entry in orion-web.xml
.
In the Resource References section:
web.xml
and orion-web.xml
settings. The name and type of a resource reference correspond to <res-ref-name>
and <res-type>
subelements under a <resource-ref>
subelement of the <web-app>
element in the web.xml
file. The JNDI location and lookup context correspond to settings under a <resource-ref-mapping>
element and its <lookup-context>
subelement, under the <orion-web-app>
element in the orion-web.xml
file.
Figure 3-13 shows the key portion of the Enterprise Manager Web Module Advanced Properties Page for a particular module. Drill down to this page by selecting Advanced Properties under Properties in the Administration section of the Web Module Page.
You can use the Web Module Advanced Properties Page to edit orion-web.xml
or global-web-application.xml
for any settings not covered by the previously discussed Enterprise Manager Web module pages. (In fact, you can make any orion-web.xml
or global-web-application.xml
entries through the Advanced Properties Page; however, it is advisable to use the previously described pages whenever possible because of their error handling and reporting features.)
|
![]() Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|