3
Deployment and Configuration

This chapter describes how to deploy and configure a Web application in OC4J. It covers the following topics:

• Introduction to Web Application Deployment and Configuration

• Application Assembly

• Application Deployment

• Configuration File Descriptions

Introduction to Web Application Deployment and Configuration

This section provides an overview of OC4J Web applications, deployment, and configuration, covering the following topics:

• Web Application Modules

• Overview of OC4J Deployment

• Overview of Web Configuration Files

  Note: For users of Oracle9iAS release 1.0.2.2, see Migrating from Oracle9i Application Server 1.x for information about issues in migrating to Oracle9iAS 9.0.2.

Web Application Modules

An OC4J application can consist of one or more J2EE-compliant modules. These include:

• Web application modules consist of JSP pages, servlet class files, HTML pages, and other resources that the application might require (such as data files, images, and sound files).

• EJB modules contain classes that implement Enterprise JavaBeans.

• A client module consists of Java class files that form a client application. The client application runs on a system that may or may not be the same as the server host, but normally is not the same.

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

Overview of OC4J Deployment

For production, use Oracle Enterprise Manager (OEM) for deployment. OEM is recommended for managing OC4J and other components of Oracle9iAS in a production environment. Refer to the Oracle9i Application Server Administrator's Guide and Oracle Enterprise Manager Administrator's Guide for information.

OC4J also supports the admin.jar tool for deployment, typically in a development environment. This modifies server.xml and other configuration files for you, based on settings you specify to the tool. Or you can modify the configuration files manually (not generally recommended). Note that in Oracle9iAS 9.0.2, if you modify configuration files without going through OEM, you must use the dcmctl tool 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.) See "Use of admin.jar for Deployment" regarding dcmctl.

For general OC4J deployment and configuration information and discussion of the admin.jar tool, see the Oracle9iAS Containers for J2EE User'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.

For more information about standard J2EE deployment, refer to the J2EE specification, which is available at the following location:

http://java.sun.com/j2ee/docs.html

Overview of Web Configuration Files

Figure 3-1 shows the XML configuration files that OC4J supports. OC4J uses the server configuration files to configure the server on start up. The server configuration files are located in the j2ee/home/config directory. The files shown at the bottom of the figure are application-specific configuration files. The files at the bottom-left are the J2EE-standard files: web.xml, ejb-jar.xml, application.xml, and application-client.xml. At the bottom-right are the corresponding OC4J-specific files to add application-specific and deployment-specific information.

Figure 3-1 OC4J Configuration Files

Text description of the illustration conffile.gif

Note that one of the server configuration files is a global application.xml file, which is for overall defaults that apply to any application. In addition, each application has its own application.xml file, which applies to the particular application only.

Changes to the global application.xml, global-web-application.xml, server.xml, and web.xml are picked up automatically by OC4J.

Deploying a Web application on OC4J involves at least the following configuration files:

• server.xml

• default-web-site.xml, or appropriate Web site XML file for a separate Web site

• global-web-application.xml

• web.xml

• optionally orion-web.xml

The server.xml file (as well as other configuration files from Figure 3-1) is discussed in the Oracle9iAS Containers for J2EE User's Guide. The other files are discussed in this chapter. See "The global-web-application.xml and orion-web.xml Files" and "The default-web-site.xml File and Other Web Site XML Files". Also be aware that web.xml is defined in the Java(TM) Servlet Specification, Version 2.2 (and higher); you can refer to that document from Sun Microsystems at the following location:

http://java.sun.com/j2ee/docs.html

Application Assembly

How you assemble and build your application is up to you. Nevertheless, 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 discusses the standard directory structure, as well as application build mechanisms.

Application Directory Structure

Figure 3-2, 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 or other Web site XML file. (See "The default-web-site.xml File and Other Web Site XML Files".)

Figure 3-2 Application Directory Structure

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:

• Put HTML files, JSP pages, and other resource files in the application root directory. The root directory is defined through the root attribute of the <web-app> element of default-web-site.xml or the Web site XML file for a particular Web site.

• Put servlet classes under the <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
  
  

• Put library files, such as JARs, that are required for the application in <app_name>/<web-app-name>/WEB-INF/lib.

Application Build Mechanisms

To build an application you have several options:

• Preferred--Create a 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 so is 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.

• Alternative--Create a makefile to automate the compilation and assembly process and use a standard UNIX make utility or the open-source gmake utility to execute it.

• Typically Not Advised--Compile each Java source file manually, using a Java 1.3.x-compatible compiler. You will probably do this only at the very early stages of developing an application, if at all. It is a potentially error-prone mechanism.

A build.xml file or makefile might include steps to create EAR, WAR, and JAR file as appropriate for deployment, or you can create them manually. See "Application Deployment" for information about these files.

Application Deployment

For J2EE-compatible deployment, each module requires a deployment descriptor. The descriptor is either a JAR file for EJB and client modules, or a WAR (Web ARchive) file for Web modules such as servlets and JSP pages.

The deployment descriptor for the entire application is the EAR (Enterprise ARchive) file, which wraps any WAR and JAR files.

You can create each of these deployment descriptors using the standard Java JAR utility. Specific examples appear below.

To deploy the application, follow these steps:

1. Create 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, then create an ejb-jar.xml file for each of these. 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.

7. Deploy the application. In a production environment, use OEM.

Use of admin.jar for Deployment

To deploy a Web application using the admin.jar command-line tool, typically in a development environment, go to the j2ee/home directory and issue the following commands in the application root directory.

% java -jar admin.jar ormi://localhost <admin_user> <admin_pw> \
       -deploy -file ./lib/<application_name>.ear  \
       -deploymentName <application_name>

This command adds the following entry to the server.xml file:

<application name="<app_name>"
             path="<your_path_to>/lib/.ear"
             auto-start="true"
/>

Then bind the Web access location into the default-web-site.xml file:

% java -jar admin.jar ormi://<hostname> <admin_user> <admin_pw> \
       -bindWebApp <app_name> <app_name>-web default-web-site \
            /<app_name>

This adds the following entry to the default-web-site.xml file:

<web-app
    application="<app_name>"
    name="<app_name>-web" 
    root="/<app_name>"
/>

Note that in Oracle9iAS 9.0.2, if you modify configuration files without going through OEM, you must run the dcmctl tool, using its updateConfig command, to inform Oracle9iAS Distributed Configuration Management (DCM) of the updates. (This does not apply in an OC4J standalone mode, where OC4J is being run apart from Oracle9iAS.) Here is the dcmctl command:

dcmctl updateConfig -ct oc4j

The dcmctl tool is documented in the Oracle9i Application Server Administrator's Guide.

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 global-web-application.xml and orion-web.xml Files

• The default-web-site.xml File and Other Web Site XML Files

Syntax Notes for Element Documentation

The elements described here do not use body values unless specifically noted, and do not have subelements unless noted. If there is neither, the syntax is as follows (with "..." where attribute settings would appear):

<elementname ... />

If there are subelements, the syntax is as follows:

<elementname ... >
   ...subelements...
</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

• Standard Descriptor Configurations

• OC4J Descriptor Configurations

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

• Default global-web-application.xml File

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

The file j2ee/home/config/global-web-application.xml is the descriptor for the OC4J global Web application, which is the parent of all Web applications on OC4J. 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 (and originally the Servlet 2.2 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, OEM or the admin.jar tool 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. In this case you will not have to override orion-web.xml after deployment.

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. For desired settings specific to an application, use the <web-app> element and subelements in the web.xml file. When deploying an application, use the <web-app> element and subelements in orion-web.xml if you want to override 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>. Use this element and its subelements in orion-web.xml to 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:

• names and classes of servlets in the Web module

• names of JSP pages

• servlet context initialization parameters

• location of any application-specific JSP tag libraries

• mappings of servlet names to URL patterns

• EJB references, including the JNDI names for looking up EJB home and remote interfaces

  (Only the Home interface JNDI name is provided, because only the Home interface is looked up through JNDI.)

• security constraints and security roles

• error code and error page mappings

• session timeout

• names of any filters in the Web application

• filter mappings--URL patterns that cause servlet filters to be triggered

  (Filter settings are outside the <web-app> element.)

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:

• additional servlet filtering and "servlet chaining"

• buffering

• character sets

• directory browsing

• document root

• locales

• classpath

• MIME mappings

• virtual directories

• access mask (to limit access to the servlet)

• clustering

• request and session tracking

• JNDI mappings

• security role mappings

• EJB mappings

• resource expiration settings

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. Use global-web-application.xml to configure the global application and set defaults, and orion-web.xml to 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.

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>

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

• 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 running a servlet by name--anything appearing after this in a URL is assumed to be a class name. This is typically for use during development and testing. For deployment, you should instead use standard web.xml mechanisms for defining the context path and servlet path. The default is "/servlet".

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

  Note: The File object can be retrieved by the following code in a servlet or JSP page, according to the Servlet 2.2 specification: File file = (File)application.getAttribute( "javax.servlet.context.tempdir");

<classpath ... >

This specifies a codebase where classes used by this application can be found (servlet 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.

<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. Specify the new value in the tag body.

Attribute:

• name: This is the name of the context-param setting to override.

<mime-mappings ... >

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.

<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:

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

<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:

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

<host-access ... >

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

<ip-access ... >

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

<cluster-config ... >

Define this tag if the application is to be clustered. 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 Oracle9iAS 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".

<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), which is specified in the Servlet 2.3 specification and covered in Chapter 4, "Servlet Filters".

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.

<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 purposes, for example.

Attribute:

• servlet-name: This is the servlet to call as the request tracker.

<servlet-filter ... >

This element specifies a servlet to use as a filter. Filters are invoked for every request, and can be used to either pre-process 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.

• url-pattern: This is an optional URL pattern to use as a qualifier for requests that are passed through the filter. For example: "/the/*.pattern".

<session-tracking ... >

This element specifies the session-tracking settings for this application. Session tracking is accomplished through cookies, assuming a cookie-enabled browser. Session tracking through URL rewriting, also known as auto-encoding, is not currently supported.

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 login to the application. Supported values are "true" and "false" (default).

• 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 afterwards.

• cookies: Specifies whether to send session cookies. Supported values are "enabled" (default) and "disabled".

<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 purposes, for example.

Attribute:

servlet-name: This is the servlet to call.

<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:

• location: This is the JNDI location from which to look up the resource. Example: "jdbc/TheDS".

• name: This is the resource reference name, which matches the name of a resource-ref element in the web.xml file. Example: "jdbc/TheDSVar".

<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:

• location: This is the name to look for in the foreign (such as third-party) context when retrieving the resource.

<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:

• name: Specifies the name of the attribute.

• value: Specifies the value of the attribute.

<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. Specify the new value in the tag body.

Attribute:

• name: This is the name of the env-entry setting to override.

<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. Use either the impliesAll attribute or an appropriate combination of subelements--<group>, or <user>, or both.

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.

<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:

• name: This is the name of the group.

<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:

• name: This is the name of the user.

<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:

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

<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:

• expires: This is the time, in seconds, before expiration, or "never" for no expiration.

• url-pattern: This is the URL pattern that the expiration applies to, such as "*.gif", for example.

<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, you can establish defaults for <web-app> settings. In web.xml, you can specify application-specific <web-app> settings to override the defaults. In orion-web.xml, you can specify deployment-specific <web-app> settings to 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 File 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. The documentation includes descriptions of the elements and attributes of these files.

Overview of default-web-site.xml and Web Site XML Files

A Web site XML file contains the configurations for an OC4J Web site. The file j2ee/home/config/default-web-site.xml configures the default OC4J Web site, also defining default configurations for any additional Web site XML files.

The names of any additional Web site XML files are defined in the server.xml file, in the path attributes 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:

• host name/IP as well as virtual host settings for this site

• port to listen on and whether the site is secure (using SSL)

• default web application for this site

• additional Web applications for this site

• access-log format

• settings for user Web applications (for /~user/ sites)

• SSL configuration

  Note: To use HTTP protocol to access OC4J directly, instead of going through the Oracle HTTP Server and AJP protocol, use a Web site XML file that specifies a port setting and protocol="http" (instead of ajp13). These are attributes of the <web-site> element. This is not recommended for a production environment, however.

Element Descriptions for default-web-site.xml and Web Site XML Files

The element descriptions in this section apply to default-web-site.xml and the Web site XML files for any additional OC4J Web sites. Use default-web-site.xml to configure the default Web site and set overall defaults, and additional Web site XML files to override these defaults for particular OC4J Web sites, as appropriate.

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>
<ssl-config>

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. 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 Oracle9iAS 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). Supported values are "true" and "false" (default). If you enable this, use the <ssl-config> element for SSL configuration settings.

• protocol: Specifies the protocol that the Web site is using. Supported values are "http", "https", and "ajp13" (Apache JServ Protocol, or AJP--default). The ajp13 protocol is for use with Oracle HTTP Server and mod_oc4j only, and is highly recommended for production environments. Note that each port must have a corresponding protocol, and vice versa.

• 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 non-zero 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).

• 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 HTTP and HTTPS, 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-separated list of host names tied to this Web site.

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

You can optionally use the body of this element for a brief description of the Web site. The <description> element has no attributes or subelements.

<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:

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

<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:

• 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 startup. Otherwise, it is loaded upon the first request for it. Supported values are "true" and "false" (default).

• 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: Specify the desired Web application name. For example, if the J2EE application name is MyApp, and this is Web site #2 of 4, you might specify a Web application name 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 "/catalog", then it can be accessed as follows:

  http://www.site.com/catalog/CatalogApp
  
  

  It is advisable to use the root value defined in application.xml. This occurs automatically when you use Oracle Enterprise Manager.

• 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. The most common use for this mode is to share a Web application between an HTTP site and an HTTPS 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 may 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.

<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" in default-web-site.xml.

Attributes are the same as for the <web-app> element described immediately above, with the following exceptions:

• There is no need for a root attribute.

• The default setting of load-on-startup is "true".

<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:

• 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/*", where "*" is replaced by the particular user name.

<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:

• 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:

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

<ssl-config ... >

This element specifies SSL configuration settings, if applicable. Use it when you set the secure attribute of the <web-site> element to "true".

If the application uses a third-party SSLServerSocketFactory implementation, you can use <property> subelements of <ssl-config> to send parameters to the factory.

Subelements:

<property>

Attributes:

• factory: If you are not using JSSE (Java Secure Socket Extension), use the factory attribute to specify an implementation of SSLServerSocketFactory. The default setting is:

  "JSSE: com.evermind.ssl.JSSESSLServerSocketFactory"
  
  

• keystore: A relative or absolute path to the keystore database (a binary file) used by this Web site to store certificates and keys for the user base in this installation. A keystore is a java.security.KeyStore instance. The database can be created using standard JavaSoft tools.

• keystore-password: The required password to open the keystore.

• needs-client-auth: Indicates whether the client must submit a certificate for authorization to log in. Supported values are "true" for client-side authorization (client must submit certificate), and "false" (default), for server-side authentication (no certificate required).

• provider: Specify the provider if JSSE is used. By default, OC4J generally uses the Sun Microsystems implementation of SSL (using com.sun.net.ssl.internal.ssl.Provider for provider). However, the Oracle SSL implementation is also used in some cases, such as for SOAP and http_client.

<property ... >

If you are using a third-party SSLServerSocketFactory implementation for SSL, you can use <property> subelements of <ssl-config> to pass parameters to the factory.

Attributes:

• name: The name of a parameter to pass to the factory.

• value: The value of the specified parameter.

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>