Skip Headers

Oracle9iAS Containers for J2EE Servlet Developer's Guide
Release 2 (9.0.3)
Part Number A97680-01
Go To Core Documentation
Core		 Go To Platform Documentation
Platform		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

3
Deployment and Configuration

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:

Introduction to Web Application Deployment and Configuration

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

Deployment and Configuration with OC4J Standalone

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".

OC4J Deployment and Configuration with Oracle9iAS and Enterprise Manager

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.

Overview of Configuration Files

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:

Among the server configuration files are the following:

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:

Application Assembly

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:

Web Application Modules

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

Application Directory Structure

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".)

Figure 3-1 Application Directory Structure

Text description of webmodir.gif follows.

Text description of the illustration webmodir.gif

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:

Application Build Mechanisms

To build an application, if you are not using Oracle9i JDeveloper, you have several options:

or:

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".

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:

  1. Ensure the creation of an 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.

  2. For each Web module in the application, create a 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".

  3. If your application has one or more EJB modules, create an 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.

  4. Create the WAR file for the Web module. When you are in the application root, issue the command: 

    % 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.

  5. Create the EAR file for the Web application. Use the 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.

  6. If your application has one or more EJB modules, also include the EJB deployment descriptor in the EAR file. Here is a sample EJB JAR file: 

    % 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.

Configuration File Descriptions

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:

Syntax Notes for Element Documentation

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>

The global-web-application.xml and orion-web.xml Files

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:

Overview of global-web-application.xml, orion-web.xml, and web.xml

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.

Note:

If you update orion-web.xml and later redeploy, you will lose your changes unless you include the updated orion-web.xml file in the application EAR file.

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.

Standard Descriptor Configurations

The web.xml descriptor file specifies the following servlet 2.3 standard configurations, among many others:

OC4J Descriptor Configurations

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:

Element Descriptions for global-web-application.xml and orion-web.xml

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.

<orion-web-app ... >

This is the root element for specifying OC4J-specific configuration of a Web application.

Note:

The autoreload-jsp-pages and autoreload-jsp-beans attributes of the <orion-web-app> element are not supported by the OC4J JSP container in Oracle9iAS release 2. You can use the JSP main_mode configuration parameter for equivalent functionality. See the Oracle9iAS Containers for J2EE Support for JavaServer Pages Developer's Guide for information about this parameter.

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:

Important:

The default setting of servlet-webdir, or any setting that starts with a slash ("/"), presents a significant security risk and should not be used in a production environment. See "Servlet Security Considerations" for more information.

Note:

The File object for a scratch file can be retrieved by the following code in a servlet or JSP page, according to the servlet specification: 

File file = (File)application.getAttribute(
                     "javax.servlet.context.tempdir");

<classpath ... >

This specifies a codebase where classes used by this application can be found (servlets and JavaBeans, for example).

Attribute:

<context-param-mapping ... >deploymentValue</context-param-mapping>

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:

<mime-mappings ... >

This defines the path to a file containing MIME mappings to use.

Attribute:

<virtual-directory ... >

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:

<access-mask ... >

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:

<host-access ... >

This subelement of <access-mask> specifies a host name or domain to allow or deny access.

Attributes:

<ip-access ... >

This subelement of <access-mask> specifies an IP address and subnet mask to allow or deny access.

Attributes:

<cluster-config ... >

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:

<servlet-chaining ... >

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:

<request-tracker ... >

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:

<servlet-filter ... >

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:

For general information about servlet filters, see "Servlet Filters".

Note:

The functionality of the <servlet-filter> element is equivalent to that of the standard <filter> subelement of the web.xml <web-app> element. You can use either mechanism, but remember that web.xml settings override global-web-application.xml settings, and settings to orion-web.xml through Enterprise Manager (or directly to the file in the application deployment directory, for OC4J standalone) override web.xml settings.

<session-tracking ... >

This element specifies the session-tracking settings for this application. Session tracking is accomplished through cookies, assuming a cookie-enabled browser.

Note:

If cookies are disabled, session tracking can be achieved only if your servlet explicitly calls the encodeURL() method of the response object, or the encodeRedirectURL() method for redirects.

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:

<session-tracker ... >

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:

<resource-ref-mapping ... >

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:

<lookup-context ... >

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:

<context-attribute ... >

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:

<env-entry-mapping ... >deploymentValue</env-entry-mapping>

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:

<security-role-mapping ... >

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:

<group ... >

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:

<user ... >

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:

<ejb-ref-mapping ... >

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:

<expiration-setting ... >

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:

<web-app-class-loader ... >

Use this element for class loading instructions.

Attributes:

<web-app ... >

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.

Note:

In a global-web-application.xml or orion-web.xml file, filter settings within the <web-app> element are not supported, because that would conflict with the <servlet-filter> subelement under the <orion-web-app> element.

Default global-web-application.xml File

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>

The default-web-site.xml, http-web-site.xml, and Other Web Site XML Files

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.)

Overview of Web Site XML Files

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:

Note:

The default-web-site.xml file, for an Oracle9iAS production environment, sets up a default Web site that accesses OC4J through the Oracle HTTP Server and AJP (Apache JServ protocol).

The http-web-site.xml file, for an OC4J standalone development environment, sets up a default Web site that accesses the OC4J listener directly, using a protocol setting of http instead of ajp13.

Element Descriptions for Web Site XML Files

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.

<web-site ... >

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:

<description>This is the description.</description>

You can use the body of this element for a brief description of the Web site.

<frontend ... >

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:

<web-app ... >

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:

<default-web-app ... >

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:

<user-web-apps ... >

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:

<access-log ... >

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:

Default default-web-site.xml File

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>

Web Module Configuration in Oracle Enterprise Manager

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.

Enterprise Manager OC4J Home Page

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.

Figure 3-2 Enterprise Manager OC4J Home Page (1 of 2)

Text description of oemoc4j1.gif follows.

Text description of the illustration oemoc4j1.gif

Figure 3-3 Enterprise Manager OC4J Home Page (2 of 2)

Text description of oemoc4j2.gif follows.

Text description of the illustration oemoc4j2.gif

The OC4J Home Page enables you to access instance properties. In particular, relating to topics covered in this manual, note the following:

Enterprise Manager Deploy Web Application Page

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.

Figure 3-4 Enterprise Manager Deploy Web Application Page

Text description of oemdepwa.gif follows.

Text description of the illustration oemdepwa.gif

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.

Enterprise Manager Website Properties Page

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.

Figure 3-5 Enterprise Manager Website Properties Page

Text description of oemwebpr.gif follows.

Text description of the illustration oemwebpr.gif

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.

Enterprise Manager Web Module Page

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.

Figure 3-6 Enterprise Manager Web Module Page

Text description of oemwebmo.gif follows.

Text description of the illustration oemwebmo.gif

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:

Enterprise Manager Web Module Properties 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.

Figure 3-7 Enterprise Manager Web Module Properties Page (1 of 2)

Text description of oemgenl1.gif follows.

Text description of the illustration oemgenl1.gif

Figure 3-8 Enterprise Manager Web Module Properties Page (2 of 2)

Text description of oemgenl2.gif follows.

Text description of the illustration oemgenl2.gif

Correspondence of these settings to orion-web.xml elements is as follows.

In the General section:

In the Session Configuration section:

In the Class Paths section:

In the Session Trackers section:

In the Virtual Directories section:

In the Tag Libraries section:

Enterprise Manager Web Module Mappings Page

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.

Figure 3-9 Enterprise Manager Web Module Mappings Page (1 of 2)

Text description of oemmaps1.gif follows.

Text description of the illustration oemmaps1.gif

Figure 3-10 Enterprise Manager Web Module Mappings Page (2 of 2)

Text description of oemmaps2.gif follows.

Text description of the illustration oemmaps2.gif

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:

In the MIME Mappings section:

In the Welcome Files section:

In the Error Pages section:

Enterprise Manager Web Module Filtering and Chaining Page

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.

Figure 3-11 Enterprise Manager Web Module Filtering and Chaining Page

Text description of oemfilt.gif follows.

Text description of the illustration oemfilt.gif

Correspondence of these settings to orion-web.xml elements is as follows.

In the Servlet Filtering section:

In the Servlet Chaining section:

Enterprise Manager Web Module Environment Page

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.

Figure 3-12 Enterprise Manager Web Module Environment Page

Text description of oemenv.gif follows.

Text description of the illustration oemenv.gif

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:

In the Environment Entries section:

In the Resource References section:

Enterprise Manager Web Module Advanced Properties Page

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.)

Figure 3-13 Enterprise Manager Web Module Advanced Properties Page

Text description of oemadv.gif follows.

Text description of the illustration oemadv.gif

Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.
All Rights Reserved.
Go To Core Documentation
Core		 Go To Platform Documentation
Platform		 Go To Table Of Contents
Contents		 Go To Index
Index