Skip Headers
Oracle® Application Server Containers for J2EE Servlet Developer's Guide
10g Release 2 (10.1.2)
B14017-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

5 Deployment and Configuration Overview

This chapter provides an overview of OC4J configuration, packaging, and deployment for servlet developers, primarily in an OC4J standalone environment. It includes the following sections:

General Overview of OC4J Deployment and Configuration

Because this is a developer's guide, much of it is intended for use in an OC4J standalone environment, which is convenient for application development stages. OC4J standalone comprises a single OC4J instance outside the Oracle Application Server environment. Most of this chapter is specific to configuration and deployment in a standalone environment, where you are developing on the same system you are deploying to.

When your application is ready for enterprise use, you can deploy it to the Oracle Application Server environment. This chapter gives an overview of deployment and configuration in Oracle Application Server, and Chapter 7, "Configuration with Enterprise Manager", offers additional information . Your primary information source for using OC4J in an Oracle Application Server environment, however, should be the Oracle Application Server Containers for J2EE User's Guide.

The following sections provide some overview:

Overview: OC4J Standalone Versus the Oracle Application Server Environment

Many OC4J features discussed in this manual, particularly in this chapter, are for use in OC4J standalone only, during development. In Oracle Application Server, which offers enterprise management features for large-scale production environments, it is critical to maintain controls to prevent actions that may compromise the server during operation. Because this is not such a concern while you are developing in a standalone environment, there are fewer restrictions on what you can or should do in OC4J standalone.

OC4J standalone provides the admin.jar command-line utility for deploying, configuring, and managing applications. It is also possible, especially for early testing, to manually deploy files and manually update configuration files. In particular, for initial testing, you can use the OC4J default Web application for individual servlet files, JSP pages, and dependency classes.


Note:

Key admin.jar commands are discussed under "Deployment Scenarios to OC4J Standalone".

For initial considerations when using OC4J standalone for development, including use of the OC4J development flag to trigger automatic recompilation and reloading of modified servlets, see "OC4J Standalone for Development".

In an enterprise production environment, OC4J is contained within Oracle Application Server, which takes over management of the J2EE enterprise systems. Oracle Application Server can oversee multiple clustered OC4J processes and is managed through the Oracle Enterprise Manager 10g. 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 manually updating configuration files, because this will conflict with the management provided by Enterprise Manager.

Table 5-1 summarizes OC4J deployment and configuration features, comparing OC4J standalone to OC4J in Oracle Application Server.

Table 5-1 OC4J in Standalone Versus Oracle Application Server: Deployment

Feature OC4J Standalone OC4J in Oracle Application Server

Deployment vehicle

Use admin.jar or manually place files.

Use Enterprise Manager or dcmctl.

Configuration vehicle

Use admin.jar or manually update files.

Use Enterprise Manager or dcmctl. Do not manually update files.

Deployment packaging

Use an EAR file, a WAR file, loose files in a J2EE application directory structure, or loose files in a Web application directory structure.

Use an EAR file or a WAR file.

Default J2EE application or J2EE application wrapper

The OC4J default J2EE application is available to contain independent WAR files. You do not have to create an EAR file for simple Web applications.

When you deploy an independent WAR file, OC4J automatically creates a J2EE application and an EAR file to wrap it.

Default Web application

The OC4J default Web application allows deployment of servlets through placement of files under the default root directory. No configuration is required.

Not applicable.

Automatic reloading of application or Web application

Modify application.xml, web.xml, servlet code under /WEB-INF/classes, or JAR file under /WEB-INF/lib.

Not applicable/appropriate.

Automatic recompilation and reloading

Use development="true" (or set JSP main_mode to "recompile" for JSP pages).

Not applicable/appropriate.


Table 5-2 summarizes OC4J features and practices relating to Web sites, again comparing OC4J standalone to OC4J in Oracle Application Server.

Table 5-2 OC4J in Standalone Versus Oracle Application Server: Web Sites

Feature OC4J Standalone OC4J in Oracle Application Server

Web server

OC4J

Oracle HTTP Server

Protocol

HTTP / HTTPS

AJP / secure AJP

Default port to invoke Web applications

8888

7777 (for Oracle HTTP Server and Oracle Application Server Web Cache)

Web site XML file

http-web-site.xml

default-web-site.xml



Note:

In Oracle Application Server, use Enterprise Manager or dcmctl, but do not attempt to use both simultaneously to target the same OC4J instance or instances, or do not use both for different parts of the same deployment.

Overview of OC4J Deployment Scenarios

OC4J supports the standard J2EE application structure and deployment vehicles. This includes the use of an EAR file to deploy a complete J2EE application, which may include Web modules, EJB modules, application client modules, and resource adapter modules (used for connector factories). There can be zero or more of each type of module. It is also possible to use an independent WAR file to deploy an independent Web application. (For a complete application that includes a Web module, the WAR file is included inside the EAR file.) For more information about these features, refer to the J2EE specification and servlet specification, available at the following Web sites:

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

http://jcp.org/aboutJava/communityprocess/first/jsr053/index.html

Before deploying a J2EE application, you must complete the following steps:

  1. Create all components of the application, such as static HTML files, servlets, JSP pages, and EJBs.

  2. Create J2EE descriptors, such as application.xml and web.xml, and, as desired, create OC4J descriptors, such as orion-application.xml and orion-web.xml. If you do not create the OC4J descriptors, they will be generated automatically during deployment of a J2EE application, which is sufficient if you do not need anything beyond default settings.

  3. Package the application components and descriptors according to the J2EE application structure. If you provide orion-application.xml, place it with application.xml. If you provide orion-web.xml, place it with web.xml. Although it is possible to deploy loose files into the appropriate directory structure, it is more typical to deploy applications in EAR or WAR files. See "Application Packaging".


    Note:

    In Oracle Application Server, deployment and configuration through Enterprise Manager results in the appropriate OC4J configuration files being created or updated automatically.

After you have packaged your application, there are several scenarios for deployment, as discussed later in this chapter.

In an OC4J standalone environment, your options include the following:

In an Oracle Application Server environment, use Enterprise Manager to deploy and configure your applications. See "Overview of OC4J Deployment and Configuration in Oracle Application Server".


Note:

You can also use an IDE, such as Oracle JDeveloper, for developing, packaging, deploying, and configuring your application. See "Oracle JDeveloper Support for Servlet Development" for an introduction and overview.

Using Oracle Deployment Tools Versus Expert Modes

This discussion considers two modes of operation when deploying and configuring applications for OC4J. One can be called supported client mode, using tools provided by Oracle for either OC4J standalone or Oracle Application Server. The other, used during development and testing phases and in OC4J standalone only, can be called expert mode. In expert mode, you are manipulating files directly—manually placing EAR files, WAR files, or loose files on the system, and manually updating configuration descriptors. These modes are summarized in Table 5-3.

Table 5-3 Tools or Vehicles for Supported Client Mode and Expert Mode

Mode Tool or Vehicle for OC4J Standalone Tool or Vehicle for OC4J in Oracle Application Server

Supported client mode

admin.jar

Enterprise Manager or dcmctl

Expert mode

Direct manipulation of server files

Not applicable/appropriate


In expert mode, you are operating outside the safeguards and constraints of the OC4J and Oracle Application Server tools.

In OC4J standalone, Oracle generally assumes that you will either deploy with admin.jar and not manually update files, or you will manually update files and not deploy with admin.jar. Crossing between these scenarios may cause unpredictable results.

In Oracle Application Server, do not try to directly manipulate server files. The Oracle Application Server Distributed Configuration Management subsystem (DCM) maintains a repository of configuration information. This repository—not configuration files on the file system—contains the true configuration settings. Enterprise Manager and the dcmctl command-line tool work in concert with DCM so that the configuration repository is properly updated when you use either of these tools.

Overview of Configuration Files

There are several categories and levels of configuration files—both OC4J-specific and J2EE-standard, and both at the global level and the application level—for configuring OC4J and an OC4J application.

While developing and testing your application in an OC4J standalone environment, you can manipulate these configuration files either manually or through the admin.jar utility, which OC4J provides. For example, the admin.jar -deploy command automatically updates server.xml to add the specified J2EE application to OC4J, and the admin.jar -bindWebApp command automatically updates the specified Web site XML file to bind the specified Web module to the Web site.


Important:

In an Oracle Application Server environment, nearly all configuration is accomplished through Oracle Enterprise Manager 10g. Do not directly manipulate the configuration files discussed here. Doing so would undermine enterprise management and cause undesirable results.

Key admin.jar commands are discussed later in this chapter, where applicable. See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for further details about the admin.jar utility.

The following sections introduce OC4J and application configuration files:

Refer to the following for additional information:

Introduction to OC4J and J2EE Configuration Files

You can divide the OC4J and J2EE configuration files into five categories:

  • Server configuration (OC4J-specific), with the overall top-level OC4J configuration file and server-level configuration files for security, data sources, RMI, JMS, and load balancing

  • Global configuration (OC4J-specific), with a global application descriptor, a global Web descriptor, and a global descriptor for resource adapters

  • Web site configuration (OC4J-specific)

  • J2EE application-level configuration, with standard J2EE application, Web, EJB, application-client, and resource adapter (connector factory) descriptors

  • OC4J-specific application-level configuration, with OC4J application, Web, EJB, application-client, and resource adapter (connector factory) descriptors

The global files can affect anything running on the OC4J server and can establish defaults for both J2EE and OC4J-specific features at the application level and the Web-site level. The J2EE files can override any defaults for standard J2EE features and establish additional J2EE-standard settings. The OC4J-specific application-level files can override defaults in the corresponding global files, override settings in the corresponding J2EE files, and add OC4J-specific features and settings.

Of particular interest to servlet developers are the top-level OC4J server configuration file (server.xml), the application descriptors (OC4J global, J2EE application-level, and OC4J application-level), the Web descriptors (OC4J global, J2EE application-level, and OC4J application-level), and the OC4J Web site descriptors. Each of these topics is discussed in more detail shortly.

Server-level and global configuration files are located in the j2ee/home/config directory by default. OC4J looks there for the server.xml file. The server.xml file specifies the locations of the other server-level and global files (by default, the same directory). In OC4J standalone, you can specify the configuration file directory through the java -config command-line option.

The following discussion summarizes the preceding five configuration file categories.

Summary of Server, Global, and Web Site Configuration Files

The server.xml file is located in the j2ee/home/config directory and specifies locations of the other server configuration files and the Web site configuration files, which are also in j2ee/home/config by default.

Server Configuration

The files in this category are OC4J-specific, configuring different aspects of the OC4J server.

  • server.xml: This parent file for all OC4J configuration includes elements pointing to other server-level and global configuration files, all Web sites on the server, and all applications on the server (including the OC4J default application). See "OC4J Top-Level Server Configuration File: server.xml".

  • jazn.xml: This configuration file for Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider (OracleAS JAAS Provider) specifies the directory path to the server-level jazn-data.xml file.

  • jazn-data.xml: This server-level JAAS file contains user name and role information for the XML-based provider. There is also an application-level version. This file is not used if OracleAS JAAS Provider uses the LDAP-based provider instead.

  • data-sources.xml: This file contains data source definitions for database connections.

  • rmi.xml: This file contains configuration features for remote method invocation.

  • jms.xml: This file contains configuration features for the Java Message Service.

OC4J Global Configuration

Files in this category are OC4J-specific, defining settings for OC4J global features such as the default application and determining default settings for corresponding application-level configuration files.

  • application.xml: This file is the OC4J-specific global application descriptor. See "OC4J and J2EE Application Descriptors".


    Note:

    Do not confuse the OC4J global application descriptor with the J2EE-standard application-level descriptor application.xml. They are both used to define Web modules and have other similar features, but the OC4J global application descriptor uses an OC4J-specific DTD.

  • global-web-application.xml: This file is the OC4J-specific global Web descriptor. See "OC4J and J2EE Web Descriptors".

  • oc4j-connectors.xml: This file is the OC4J-specific global descriptor for resource adapters (for connector factories).

Web Site Configuration

Each Web site that is recognized by the server has a Web site XML file to configure it. There is just one Web site in Oracle Application Server. There is typically one Web site in OC4J standalone, but you can use a second Web site for "shared" applications, such as those in which some communication is through HTTP and some through HTTPS. It is also possible for there to be no Web sites, if the OC4J instance is not used for Web modules. See "OC4J Web Site Descriptors".

  • default-web-site.xml: This file is the default Web site descriptor in an Oracle Application Server environment.

  • http-web-site.xml: This file is the default Web site descriptor in an OC4J standalone environment.

  • Additional Web site XML files: Create a separate Web site XML file, named as desired, for any additional Web site.

Summary of Application-Level Configuration Files

J2EE configuration files are included within the standard application structure. If you include OC4J application-level configuration files in your EAR or WAR file, they also go within the application structure. See "J2EE Application Structure". Upon deployment of a J2EE application, the OC4J files are either copied (if you included them) or generated (if you did not include them) in the deployment directory, typically under j2ee/home/application-deployments.

J2EE Application-Level Configuration

Files in this category are all application-level and are defined by the J2EE specification.

  • application.xml: This file is the J2EE-standard application descriptor. See "OC4J and J2EE Application Descriptors".


    Note:

    Do not confuse the J2EE application descriptor with the OC4J global application descriptor application.xml. They are both used to define Web modules and have other similar features, but have separate and distinct DTDs.

  • web.xml: This file is the J2EE-standard Web descriptor. See "OC4J and J2EE Web Descriptors".

  • ejb-jar.xml: This file is the J2EE-standard EJB descriptor.

  • application-client.xml: This file is the J2EE-standard descriptor for application clients.

  • ra.xml: This file is the J2EE-standard descriptor for resource adapters (for connector factories).

OC4J Application-Level Configuration

Files in this category are OC4J-specific at the application level. They configure OC4J-specific functionality to complement standard functionality from the corresponding J2EE descriptor, and override default settings from the corresponding server-level or global descriptor.

  • orion-application.xml: This file is the OC4J-specific application descriptor. See "OC4J and J2EE Application Descriptors".

  • orion-web.xml: This file is the OC4J-specific Web descriptor. See "OC4J and J2EE Web Descriptors".

  • orion-ejb-jar.xml: This file is the OC4J-specific EJB descriptor.

  • jazn-data.xml: This application-level JAAS file contains user name and role information for the XML-based provider. There is also a server-level version. This file is not used if OracleAS JAAS Provider uses the LDAP-based provider instead.

  • orion-application-client.xml: This file is the OC4J-specific descriptor for application clients.

  • oc4j-ra.xml: This file is the OC4J-specific descriptor for resource adapters (for connector factories).

Additional Information

See the following documents for more information about the preceding descriptors:

OC4J Top-Level Server Configuration File: server.xml

The OC4J server.xml file, located in the OC4J j2ee/home/config directory by default, is the starting point for configuration of the OC4J server and all J2EE applications, Web applications, and Web sites for the server. In particular, note the following:

  • The attributes of the top-level <application-server> element specify, among other things, the target directory for deployed EAR files and where they are unpacked (determined by the application-directory setting), and the target directory for copied or generated OC4J descriptors (determined by the deployment-directory setting).


    Note:

    A key <application-server> attribute in the OC4J 10.1.2 implementation is check-for-updates, to automatically check OC4J XML configuration files for updates. See "Key OC4J Flags for Development".

  • The <global-application> element specifies the OC4J global application, otherwise known as the default application, which, by default, is the parent of all other applications. The name attribute defines its name; the path attribute specifies what to use as the OC4J global application descriptor. See "OC4J Default Application and Default Web Application" for a discussion of the OC4J default application.

  • The <global-web-app-config> element, through its path attribute, specifies what to use as the OC4J global Web application descriptor.

  • There is a <web-site> element for each Web site recognized by the server, with the path attribute specifying what to use as the corresponding Web site XML file. OC4J comes with one such element already configured.

  • There is an <application> element for each J2EE application deployed to the server. The name attribute specifies the desired J2EE application name. The path attribute reflects where the EAR file is deployed and unpacked, or where application files exist that have already been unpacked (or were manually placed). In either case, the name attribute is typically the same as the EAR file name without the .ear extension. In the first case, the path attribute specifies the full path to the EAR file, including the EAR file name. In the second case, the path attribute specifies the top-level directory of the extracted files.

  • The <rmi-config> element, through its path attribute, specifies what to use as the OC4J RMI descriptor.

  • The <jms-config> element, through its path attribute, specifies what to use as the OC4J JMS descriptor.


    Note:

    In Oracle Application Server, port settings in the RMI descriptor (rmi.xml by default) and JMS descriptor (jms.xml by default) are overridden.

The server.xml file is discussed in detail in the Oracle Application Server Containers for J2EE User's Guide, but an example is also provided here:

<?xml version="1.0"?>
<!DOCTYPE application-server PUBLIC "-//Evermind//DTD Orion
 Application-server//EN"
 "http://xmlns.oracle.com/ias/dtds/application-server.dtd">

<application-server application-directory="../applications"
                    deployment-directory="../application-deployments"
                    connector-directory="../connectors"
>
   <rmi-config path="./rmi.xml" />
   <jms-config path="./jms.xml" />
   <log>
      <file path="../log/server.log" />
   </log>
   <transaction-config timeout="250000" />
   <global-application name="default" path="application.xml" /> 
   <application name="petstore" path="../applications/petstore.ear" ... />
   <global-web-app-config path="global-web-application.xml" />
   <web-site default="true" path="./default-web-site.xml" />
   <web-site path="../myconfig/my-web-site.xml" />
   <cluster id="-1406559522" />
</application-server>

Figure 5-1, which follows, illustrates the mappings between the server.xml file, other XML files including Web site XML files, and J2EE EAR files. Note that in this figure, the <application> elements in server.xml point to top-level directories of extracted EAR files instead of pointing to intact EAR files.

Figure 5-1 Mappings from the server.xml File

Description of Figure 5-1  follows
Description of "Figure 5-1 Mappings from the server.xml File"

OC4J and J2EE Application Descriptors

An application descriptor specifies the components of a J2EE application, such as EJB and Web modules, and can specify additional configuration for the application as well.

OC4J uses three categories of application descriptors. The following sections discuss each of them, then summarize their relationships to each other:

The server.xml file points to the application descriptor of each application on OC4J, either directly or indirectly. In the case of a typical J2EE application, server.xml points to the EAR file (or extracted EAR top-level directory) and, therefore, to the application.xml file that the EAR file contains. In the case of the OC4J global application, the server.xml file points directly to the OC4J global application descriptor.

See the Oracle Application Server Containers for J2EE User's Guide for more information about application descriptors in OC4J.

Standard J2EE Application Descriptors

The J2EE standard defines the concept and DTD of an application descriptor, called application.xml, that you must include in the /META-INF directory of the EAR file of a J2EE application. The application descriptor acts as a manifest of the modules contained in the application, possibly with additional configuration information as well, and in some development environments can be created automatically for you. See the J2EE specification for more information.

Here is an example for an application with an EJB module, a Web module, and a client module:

<?xml version="1.0" ?> 
<!DOCTYPE application (View Source for full doctype...)> 
<application>
  <display-name>stateful, application:</display-name> 
  <description>
    A sample J2EE application that uses a remote stateful session
    bean to call a local entity bean.
  </description> 
  <module>
    <ejb>stateful-ejb.jar</ejb> 
  </module>
  <module>
    <web>
      <web-uri>stateful-web.war</web-uri> 
      <context-root>/stateful</context-root> 
    </web>
  </module>
  <module>
    <java>stateful-client.jar</java>
  </module>
</application>

OC4J Global Application Descriptor

The OC4J-specific global application descriptor is defined by an OC4J-specific DTD, orion-application.dtd. This is the descriptor for the OC4J global application, as specified by the <global-application> element in the server.xml file. This element specifies the global application name, default by default, and the global application descriptor name, application.xml by default and usually located in the same directory as server.xml.

The OC4J global application is usually referred to as the "default application" and, by default, is the parent application of all other applications in the OC4J instance.


Note:

The standard J2EE application descriptor and the OC4J global application descriptor are both named application.xml, despite being defined by different DTDs. Do not confuse the two. The standard application.xml file is not applicable to the OC4J default application.

Following is an abbreviated sample application.xml file for the OC4J default application. Note that it specifies the name of a Web application, defaultWebApp, which by convention is bound to one or more Web sites as the default Web application.

Do not confuse the OC4J default J2EE application with the default Web application that it contains. See "OC4J Default Application and Default Web Application" for related information.

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime
 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

<!-- The global application config that is the parent of all the other
  applications in this server. -->

<orion-application autocreate-tables="true"
                   default-data-source="jdbc/OracleDS">
  <web-module id="defaultWebApp" path="../../home/default-web-app" />
  <connectors path="./oc4j-connectors.xml"/>

  <!-- Path to the libraries that are installed on this server.
  These will accesible for the servlets, EJBs etc -->
  <library path="../../home/lib" />
  <!-- Path to the taglib directory that is shared
        among different applications. -->
  <library path="../../home/jsp/lib/taglib" />

  <log>
    <file path="../log/global-application.log" />
  </log>

  <data-sources path="data-sources.xml" />
  <namespace-access>
    <read-access>
      <namespace-resource root="">
        <security-role-mapping>
          <group name="administrators" />
        </security-role-mapping>
      </namespace-resource>
    </read-access>
    <write-access>
      <namespace-resource root="">
        <security-role-mapping>
          <group name="administrators" />
        </security-role-mapping>
      </namespace-resource>
    </write-access>
  </namespace-access>
</orion-application>

OC4J-Specific Application Descriptors

In addition to the standard application descriptor, application.xml, there is an OC4J-specific application-level application descriptor, orion-application.xml. This descriptor is defined by the same DTD as the OC4J global application descriptor. You can provide an orion-application.xml file as well as an application.xml file, also in the /META-INF directory of your EAR file. The orion-application.xml file can add OC4J-specific configuration.

Including an orion-application.xml file in your EAR file is optional. If you include it, OC4J copies it into the deployment directory during deployment (under j2ee/home/application-deployments by default). Otherwise, OC4J generates one for you in the deployment directory, using default settings from the OC4J global application descriptor (assuming the OC4J default application is the parent application, as is the case by default) and the application.xml file in the EAR file. See "J2EE Application Structure" for information about where orion-application.xml fits in the application structure.


Note:

When OC4J copies orion-application.xml, it may make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value may be ignored or removed.

In most circumstances, you should use orion-application.xml only to define OC4J-specific configuration such as security role mappings. Also note that if OC4J generates the file, it creates <web-module> elements to reflect the modules specified in the J2EE application.xml file.

The following example shows some OC4J-specific configuration and defines the same EJB, Web, and client modules as defined in the example of the standard application.xml file in "Standard J2EE Application Descriptors":

<?xml version="1.0"?>
<!DOCTYPE orion-application PUBLIC "-//Evermind//DTD J2EE Application runtime
 1.2//EN" "http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

<orion-application default-data-source="jdbc/OracleDS">
  <ejb-module remote="false" path="stateful-ejb.jar" />
  <web-module id="stateful-web" path="stateful-web.war" />
  <client-module path="stateful-client.jar" auto-start="false" />
  <persistence path="persistence" />
  <log>
    <file path="application.log" />
  </log>
  <namespace-access>
    <read-access>
      <namespace-resource root="">
        <security-role-mapping name="&lt;jndi-user-role&gt;">
          <group name="users" />
        </security-role-mapping>
      </namespace-resource>
    </read-access>
    <write-access>
      <namespace-resource root="">
        <security-role-mapping name="&lt;jndi-user-role&gt;">
          <group name="users" />
        </security-role-mapping>
      </namespace-resource>
    </write-access>
  </namespace-access>
</orion-application>

Summary of Relationships Between Application Descriptors

To summarize the relationship between J2EE application descriptors, the OC4J global application descriptor, and OC4J application-level application descriptors:

  • For a typical J2EE application, the key application descriptor is the standard J2EE application descriptor, application.xml. This file acts as a manifest for the modules of a J2EE application and must be placed in the /META-INF directory of the J2EE application EAR file.

  • If you want to deploy a standalone WAR file (rather than a WAR file within an EAR file), you can use the OC4J default application, or global application, as the containing application. (See "OC4J Default Application and Default Web Application".) In this case, the OC4J global application descriptor, also called application.xml but defined by an OC4J-specific DTD, becomes relevant because no J2EE standard application.xml file is associated with a standalone WAR file.

  • You can optionally include an orion-application.xml descriptor for additional OC4J configuration, such as for security role mappings. The orion-application.xml file may also specify additional modules, beyond those specified in the J2EE application.xml file, and can even override modules specified in application.xml (though this is not advisable). The orion-application.xml file would also be in the /META-INF directory of the EAR file. If you do not include this file, it is created automatically during deployment, using defaults from the OC4J global application descriptor (assuming the default application is the parent of your application, which is true by default). The orion-application.xml descriptors are defined according to the same DTD as the OC4J global application descriptor.

OC4J and J2EE Web Descriptors

A Web descriptor specifies and configures a set of J2EE Web components: static pages, servlets, and JSP pages. The Web components may together form an independent Web application and be deployed in a standalone WAR file. More typically, however, they will form just part of an overall J2EE application, being deployed in a WAR file within the EAR file of the J2EE application.

OC4J uses three categories of Web descriptors. The following sections discuss each of them and summarize the relationships between them:

Standard J2EE Web Descriptors

The servlet specification defines the concept and DTD of a Web descriptor, called web.xml, that you must include in the /WEB-INF directory of the associated WAR file. The web.xml file specifies and configures the Web components of the WAR file, as well as other components, such as EJBs, that the Web components may call. See the servlet specification for more information.

Here is a sample web.xml file specifying, among other things, a servlet, the servlet mapping, and a local EJB lookup:

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
   <display-name>stateful, web-app:</display-name>
   <description>no description</description> 
   <welcome-file-list>
      <welcome-file>index.html</welcome-file>
   </welcome-file-list>

   <ejb-local-ref>
      <ejb-ref-name>CartBean</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <local-home>cart.CartHome</local-home>
      <local>cart.Cart</local>
   </ejb-local-ref>

   <servlet>
      <servlet-name>cart</servlet-name>
      <servlet-class>cart.CartServlet</servlet-class>
      <init-param>
         <param-name>param1</param-name>
         <param-value>1</param-value>
      </init-param>
   </servlet>
   <servlet-mapping>
      <servlet-name>cart</servlet-name>
      <url-pattern>/cart</url-pattern>
   </servlet-mapping>
   <security-role>
      <role-name>users</role-name>
   </security-role>
</web-app>

OC4J Global Web Application Descriptor

The server.xml file, through its <global-web-app-config> element, specifies the OC4J global Web application descriptor. It is typically global-web-application.xml, in the same directory as server.xml. This descriptor defines default behavior for Web applications in OC4J.

The global Web application descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the application-level OC4J-specific Web descriptor, orion-web.xml, described in the next section, "OC4J-Specific Web Descriptors".

The orion-web.dtd is a superset of the standard DTD for web.xml. There is a <web-app> subelement of the <orion-web-app> top-level element in orion-web.dtd, which has the same specification as the top-level <web-app> element of web.xml. There are also many other subelements of <orion-web-app> for specifying and configuring OC4J-specific features.

For any default settings you specify within the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through <web-app> settings in web.xml. You can then add to or, optionally, override the resulting settings through <web-app> settings in orion-web.xml.


Note:

Avoid using the <web-app> element in global-web-application.xml or orion-web.xml. Because it is customary to look in web.xml for any <web-app> entries, having such entries elsewhere could be confusing and may cause difficulty during troubleshooting.

For any default settings you specify outside the <web-app> element in global-web-application.xml, you can add to or, optionally, override these settings through parallel settings in orion-web.xml.

For detailed information about the elements and attributes of the OC4J global Web application descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".

See "Sample global-web-application.xml Settings" for an abbreviated sample global-web-application.xml file.

OC4J-Specific Web Descriptors

In addition to the standard Web descriptor, web.xml, and the OC4J global Web application descriptor, global-web-application.xml (which establishes default behavior), there is an OC4J-specific application-level Web descriptor, orion-web.xml.

The orion-web.xml descriptor is defined by the DTD orion-web.dtd. This is the same DTD as for the global Web application descriptor that was described in the previous section, "OC4J Global Web Application Descriptor".

You can provide an orion-web.xml file as well as the web.xml file, also in the /WEB-INF directory of your WAR file. Use orion-web.xml to add to or, optionally, override any default settings in global-web-application.xml, as well as to add to or override any settings in web.xml.

Including an orion-web.xml file in your WAR file (inside the EAR file) is optional. If you include it, OC4J copies it into the deployment directory during deployment (under the j2ee/home/application-deployments directory by default). Otherwise, OC4J generates orion-web.xml for you in the deployment directory, using default settings from global-web-application.xml. Additionally, some web.xml settings will influence the generation of orion-web.xml. For example, <resource-ref> entries in web.xml will result in corresponding <resource-ref-mapping> entries in orion-web.xml. See "J2EE Application Structure" for information about where orion-web.xml fits in the application structure.


Note:

When OC4J copies orion-web.xml, it may make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value may be ignored or removed.

For detailed information about the elements and attributes of the OC4J-specific Web descriptor, including the DTD and a hierarchical representation, see "Configuration for global-web-application.xml and orion-web.xml".

A sample orion-web.xml file follows:

<?xml version="1.0" ?> 
<!DOCTYPE orion-web-app (View Source for full doctype...)> 
<orion-web-app jsp-cache-directory="./persistence" temporary-directory="./temp"
              servlet-webdir="/servlet/" default-buffer-size="2048"
              development="false" directory-browsing="deny"
              file-modification-check-interval="1000" jsp-timeout="0 (never)">
  <ejb-ref-mapping name="EmployeeBean" /> 
  <security-role-mapping name="users">
     <group name="users" /> 
  </security-role-mapping>
  <!-- 
  <web-app>
      There are no <web-app> entries in this sample. 
  </web-app>
  -->
</orion-web-app>

Summary of Relationships Between Web Descriptors

You can think of the relationship between global-web-application.xml, web.xml, and orion-web.xml as follows:

  1. The global-web-application.xml file establishes defaults for any Web application in OC4J.

  2. The web.xml file overlays anything defined in the <web-app> element of global-web-application.xml, adding to and possibly overriding any Web components and other settings defined there.

  3. The orion-web.xml file overlays everything, adding to and possibly overriding any settings from global-web-application.xml and web.xml.

OC4J Web Site Descriptors

Each Web site in OC4J is defined and configured through a Web site XML file. The key functions of a Web site XML file are the following:

  • It binds specified Web modules to the Web site, identifying each Web module to bind, the J2EE application it belongs to, and the context path portion of the URL to use in accessing it.

  • It defines key settings for the Web site, such as the host name, port number, and protocol. The protocol setting should indicate AJP (Apache JServ Protocol) in an Oracle Application Server environment, and HTTP in a standalone environment.

The server.xml file indicates the number of Web sites that OC4J recognizes, by including a <web-site> element for each site. Each of these elements specifies the path and file name for the corresponding Web site XML file, as in the following sample server.xml entries:

...
<web-site path="./default-web-site.xml" /> 
<web-site path="mydir/my-web-site.xml" />
...

In Oracle Application Server, there is just one Web site. In OC4J standalone, there is typically one Web site, but you can use a second Web site for "shared" applications, such as where some communication is through HTTP and some through HTTPS. (For information about shared applications, see the description of the <web-app> element shared attribute in "Element Descriptions for Web Site XML Files".)

A Web site XML file contains a <web-app> element for each Web module to bind to the Web site. At a minimum, each <web-app> element has the following:

  • An application attribute to specify the name of the J2EE application to which the Web module belongs (the same as the EAR file name without the .ear extension)

  • A name attribute to specify the name of the Web module (the same as the WAR file name without the .war extension)

  • A root attribute to specify the context path on this Web site to which the Web module is to be bound

There is also a <default-web-app> element for the default Web application. The default Web application is useful in OC4J standalone during development, as discussed in "OC4J Default Application and Default Web Application". In Oracle Application Server, it is used for some system-level functionality but is not otherwise meaningful. See "OC4J Default Web Application in Oracle Application Server".


Important:

  • The root setting overrides the setting of the <context-root> element for this Web module in the application.xml descriptor for the containing J2EE application. The <context-root> element is required in application.xml, but is not used by OC4J. See "Example: Mappings to and from Web Site Descriptors", which follows.

  • A root setting of "/" overrides the OC4J default Web application. This setting (or a null setting, which is converted to "/") is not allowed by the admin.jar utility when binding a Web application to the Web site.


By default, OC4J comes configured with one Web site XML file: http-web-site.xml in OC4J standalone, or default-web-site.xml in Oracle Application Server.

See "Configuration for Web Site XML Files" for detailed information about the elements and attributes of Web site XML files, including the DTD and a hierarchical representation.

See "Sample default-web-site.xml File" for an example, in this case a sample default-web-site.xml file for an Oracle Application Server environment.

Example: Mappings to and from Web Site Descriptors

This example shows how an entry in server.xml points to a Web site descriptor (Web site XML file), and how a <web-app> element in the Web site XML file points to a Web module. The <web-app> element binds the Web module to the Web site. The Web module is defined in the application.xml file (also shown) of the containing J2EE application.

The server.xml file includes an <application> element for the relevant J2EE application (which contains the desired Web module) and includes a <web-site> element specifying the Web site XML file for the desired Web site:

<application-server ... >
   ...
   <application name="myear" path="../myapps/myear.ear" />
   ...
   <web-site path="my-web-site.xml" />
   ...
</application-server>

The Web site XML file, my-web-site.xml, configures the Web site and has a <web-app> element that specifies the J2EE application that contains the Web module, the name of the Web module itself, and the root context path for accessing the Web module:

...
<web-site protocol="http" port="8888" display-name="My Web Site" 
          host="[ALL]" log-request-info="false" secure="false">
  ...
  <web-app application="myear" name="mywebmod1" root="/someUrl"
           load-on-startup="false" max-inactivity-time="no shutdown"
           shared="false" /> 
  ...
</web-site>

See "Element Descriptions for Web Site XML Files" for information about the <web-site> and <web-app> attributes shown here.


Note:

For a Web application (WAR file) that is deployed to the OC4J default application instead of being deployed within an EAR file, the <web-app> element application attribute indicates the name of the OC4J default application (default by default) instead of indicating an EAR file name.

See "OC4J Default Application and Default Web Application" for general information about the default application.


The J2EE application.xml file in myear.ear specifies the Web module:

<application ... >
  ...
  <module>
    <web>
      <web-uri>mywebmod1.war</web-uri>
      <context-root>/someUrl</context-root>
    </web>
  </module>
  ...
</application>

Notes:

  • The value of the root attribute of the <web-app> element in my-web-site.xml overrides the value of the <context-root> element in application.xml. As a convention, though, use the same setting in both places.

  • A Web application deployed to the OC4J default application is defined in the OC4J global application descriptor.

  • In an Oracle Application Server environment, the default-web-site.xml file, by default, sets up a Web site that accesses OC4J through the Oracle HTTP Server and AJP (Apache JServ protocol), using a protocol setting of "ajp13" and a port setting of "0". However, OPMN, the Oracle Process Management and Notification system, overrides this port setting.

  • In an OC4J standalone environment, the http-web-site.xml file, by default, sets up a Web site that accesses the OC4J listener directly, using a protocol setting of "http" and a port setting of "8888".


Application Packaging

OC4J supports standard J2EE archive files for deployment, including WAR files for Web modules and EAR files for overall J2EE applications. The following sections review the structure of these files:

J2EE Application Structure

This section reviews the standard J2EE application structure, which you can use as your development structure as appropriate. This discussion also shows the relative locations of optional OC4J-specific descriptors. If you do not include the OC4J-specific descriptors in your deployment, OC4J generates them for you when you deploy a J2EE application, using values from corresponding OC4J global descriptors and J2EE descriptors as defaults.

J2EEAppName/

   META-INF/
      application.xml
      orion-application.xml (optional)

   EJBModuleName/
      (EJB classes, according to package)
      META-INF/
         ejb-jar.xml
         orion-ejb-jar.xml (optional)

   WebModuleName/
      (static files, such as index.html)
      (JSP pages)
      WEB-INF/
         web.xml
         orion-web.xml (optional)
         classes/
            (servlet classes, according to package)
         lib/
            (JAR files for dependency classes)

   ClientModuleName/
      (client classes, according to package)
      META-INF/
         application-client.xml
         orion-application-client.xml

   ResourceAdapterModuleName/
      META-INF/
         ra.xml
      (JAR files for required classes)
      (required static files or other files)

The Web portion is marked in bold type. This portion reflects the structure of WAR files used to deploy Web modules. At the top level are static pages (such as index.html), JSP pages, and the /WEB-INF directory.


Notes:

  • This structure is defined in the J2EE specification and related specifications. The J2EE specification is at the following location:

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


EAR File and WAR File Structures

In J2EE, a WAR file is typically contained within an EAR file. In the example in the preceding section, the EAR file, J2EEAppName.ear, would have its /META-INF directory at the top level, along with Web module WAR files, EJB module JAR files, client application JAR files, and resource adapter RAR files (zero or more of each, as applicable):

META-INF/
   application.xml
   orion-application.xml (optional)
EJBModuleName.jar
WebModuleName.war
ClientModuleName.jar
ResourceAdapterModuleName.rar

Sample EAR and WAR File

This example shows the structure of the archive files for a simple Web application. The EAR file contains a WAR file, which contains a single servlet.

Following are the contents of utility.ear. If there were EJB, client application, or resource adapter modules, the associated JAR files would be at the same level as the WAR file. Optionally, you could also include an orion-application.xml file in the /META-INF directory. Instead, in this example, one would be generated by OC4J during deployment.

META-INF/MANIFEST.MF
META-INF/application.xml
utility_web.war

Here are the contents of utility_web.war. Optionally, you could also include an orion-web.xml file in the /WEB-INF directory. Instead, in this example, one would be generated by OC4J during deployment.

META-INF/MANIFEST.MF
WEB-INF/classes/TestStatusServlet.class
WEB-INF/web.xml
index.html

Notes:

  • This document assumes you have some J2EE development experience and a means of creating EAR and WAR files, either by using the JAR utility directly, or through an IDE such as Oracle JDeveloper, or by using the ant utility and a build.xml file. See the following site for information about ant:

http://ant.apache.org

  • The MANIFEST.MF files are created automatically by the JAR utility.


Deployment Scenarios to OC4J Standalone

This section reviews some preliminary considerations and then discusses several scenarios for deployment to OC4J standalone. The primary deployment scenario is to use the admin.jar utility after you package your application in an EAR file. The EAR file optionally contains Web module WAR files, EJB module JAR files, client application JAR files, and resource adapter RAR files (zero or more of each). See "Application Packaging" for more information about structure and packaging.

The use of EAR files for OC4J deployment, and features of the admin.jar utility, are covered extensively in the Oracle Application Server Containers for J2EE Stand Alone User's Guide. Key features are discussed here.

In addition, this section considers alternative deployment scenarios that you may find useful during development, such as manually creating and populating a J2EE application structure or deploying an independent WAR file into the OC4J default application.


Note:

In these alternative deployment scenarios, in which you manually place and update files, you are considered to be in "expert mode". You are operating outside the safeguards and constraints of the OC4J and Oracle Application Server tools. See "Using Oracle Deployment Tools Versus Expert Modes".

This section includes the following subjects:

Setting Up an Administrative User and Password

Before using the admin.jar utility to deploy an application in OC4J standalone, you must have a user with administrative privileges.

The j2ee/home/config/jazn-data.xml file determines security privileges for user accounts. By default, there is a user admin with administrative privileges, as specified in the following sample jazn-data.xml entry:

<role>
   <name>administrators</name>
   <display-name>Realm Admin Role</display-name>
   <description>Administrative role for this realm.</description>
   <members>
      <member>
         <type>user</type>
         <name>admin</name>
      </member>
   </members>
</role>

For the default administrative user admin, the default password is welcome, as in the following sample jazn-data.xml entry:

<users>
...
   <user>
      <name>admin</name>
      <display-name>OC4J Administrator</display-name>
      <description>OC4J Administrator</description>
      <credentials>!welcome</credentials>
   </user>
...
</users>

(The file is automatically rewritten later to obfuscate the specified password.) See the Oracle Application Server Containers for J2EE Security Guide for more information about the jazn-data.xml file, especially regarding the <credentials> element.


Important:

You cannot use the admin.jar utility in an Oracle Application Server environment. It is for use in OC4J standalone only.


Note:

If you are still using the deprecated principals.xml file for security, the administrative account password is determined through the OC4J -install command:
% java -jar oc4j.jar -install

(Assume % is the system prompt and j2ee/home is your current directory.) You will be prompted for the desired password.


Starting and Stopping OC4J Standalone

This section provides a quick review of how to start and stop OC4J standalone. Assume % is the system prompt and j2ee/home is your current directory.

Issue the following command to start OC4J:

% java -jar oc4j.jar [options]

See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for a discussion of OC4J command-line options.

Issue the following command to stop OC4J:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port
       adminuser adminpassword -shutdown

For the admin.jar -shutdown command, note the following:

  • In OC4J standalone, you can get the OC4J ORMI port number from the j2ee/home/config/rmi.xml file, where there will be an entry such as the following:

    <rmi-server port="23791" host="[ALL]">
    
    
  • See the previous section, "Setting Up an Administrative User and Password", for information about adminuser and adminpassword.

OC4J Default Application and Default Web Application

The following sections discuss features and configuration of the OC4J default application and default Web application. Some of the OC4J standalone deployment scenarios described later will use these features.

Use of the Default Application and Default Web Application

OC4J is installed with a default configuration that includes a default application (also known as the global application). The default application is, by default, the parent of all other J2EE applications in OC4J.

In OC4J, a Web application must be contained within a parent J2EE application. Usually, a WAR file is deployed within an EAR file that defines the parent J2EE application. If you want to deploy an independent WAR file, you can deploy to the OC4J default application instead. By default, the OC4J server.xml file specifies the location and name of the global application descriptor that defines the default application.

In a typical OC4J installation, the default application contains a default Web application. The name and root directory path of the default Web application are specified in the global application descriptor, and the default Web application is bound to a Web site through the http-web-site.xml file for OC4J standalone (default-web-site.xml in Oracle Application Server). In OC4J standalone, the default context path for the default Web application is "/".

Also by default in OC4J standalone, the root directory of the default Web application is j2ee/home/default-web-app. To deploy to the default Web application, place your JSP pages and class files under this directory in the standard Web application directory structure: static pages and JSP pages at the top level, servlet classes under j2ee/home/default-web-app/WEB-INF/classes, and library JAR files in j2ee/home/default-web-app/WEB-INF/lib. Also see "Using a Web Application Directory Structure in the Default Web Application".


Note:

The default Web application, in addition to being invoked by use of the context path "/", is invoked if the context path mapping of any requested URL fails. This occurs if a requested URL has no matching context path in any <web-app> element root attribute in the Web site XML file.

Configuration of the Default Application and Default Web Application

This section details the default configurations for the OC4J default application and default Web application.

The server.xml Configuration for Default Application

In server.xml, the <global-application> element specifies the OC4J default application. The name attribute specifies its name, and the path attribute specifies what to use as the OC4J global application descriptor:

<application-server ... >
   ...
   <global-application name="default" path="application.xml" />
   ...
</application-server>
The application.xml Configuration for Default Web Application

The specified descriptor for the default application (or global application), application.xml, specifies the name and root directory path of the default Web application, which is contained in the default application:

<orion-application ... >
  ...
  <web-module id="defaultWebApp" path="../../home/default-web-app" />
  ...
</orion-application>

To deploy to the default Web application, place your files under this directory according to the standard Web application structure.

Binding of Default Web Application in Web Site XML File

By default, the default Web application is bound to a Web site in the http-web-site.xml file for OC4J standalone (default-web-site.xml in Oracle Application Server).

Although most OC4J Web applications are bound to a Web site through <web-app> subelements of a <web-site> element in the Web site XML file, the default Web application is instead configured through the <default-web-app> subelement of <web-site>.

In OC4J standalone, the default context path of the default Web application is "/", without a root attribute being required. Here is an example:

<web-site ... >
...
   <default-web-app application="default" name="defaultWebApp"
                    load-on-startup="true" shared="false" />
...
</web-site>

See "Configuration for Web Site XML Files" for detailed information about elements and attributes of Web site XML files.


Note:

The <default-web-app> element is required in any Web site XML file.

Deploying an EAR File to OC4J Standalone

The following sections describe the process of deploying an EAR file in OC4J standalone using the admin.jar utility.

This discussion assumes that if you modify your code, you would then repackage it and redeploy it.

Using admin.jar to Deploy the EAR File

After you have packaged your application into an EAR file, you can use the OC4J admin.jar utility to deploy it, using the following syntax:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -deploy -file path/filename.ear
                      -deploymentName appname

This command uses RMI to communicate with OC4J. Note the following:

  • See "Starting and Stopping OC4J Standalone" for information about the ORMI port.

  • See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

  • For -file, specify the path to the EAR file, including the file name.

  • For -deploymentName, specify the desired application name, by convention the same as the EAR file name without the .ear extension.


    Note:

    During development, assuming you develop and run on the same system, you will deploy locally. However, admin.jar is also capable of deploying remotely.

By default, a deployment results in the following:

  • The EAR file is copied to the j2ee/home/applications directory. This directory is set as the default through the application-directory attribute of the <application-server> element in the server.xml file.

  • The EAR file is unpacked beneath the j2ee/home/applications directory.

  • The OC4J-specific descriptors—at a minimum, orion-application.xml and orion-web.xml for a Web application in an EAR file—are copied or generated under the j2ee/home/application-deployments directory. This directory is set as the default through the deployment-directory attribute of the <application-server> element in the server.xml file. These descriptors are copied from the EAR file if they exist there; otherwise, OC4J generates them.

  • An <application> element is added to the server.xml file. This element specifies the application name, according to the -deploymentName setting in admin.jar, and specifies the path to where the EAR file was deployed, j2ee/home/applications by default.

See "Sample Deployment" for an example.


Note:

You can specify the target directories through your configuration. See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for additional information about admin.jar, including the -targetPath and -deploymentDirectory options.

Using admin.jar to Bind the Web Application

After you have deployed your application, you can use the OC4J admin.jar utility to bind the associated Web application to a Web site:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -bindWebApp appname webappname websitename contextpath

As with the -deploy command, the -bindWebApp command uses RMI to communicate with OC4J. Note the following:

  • See "Starting and Stopping OC4J Standalone" for information about the ORMI port.

  • See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

  • The appname is the application name, according to the -deploymentName setting when you deployed it.

  • The webappname is the name of the Web application. This is the WAR file name without the .war extension.

  • The websitename is indicated by the Web site XML file name for the desired site, without the .xml extension (for example, http-web-site in OC4J standalone).

  • Specify the desired context path portion of the URL for invoking the Web application.


    Note:

    A context path setting of "/", which overrides the OC4J default Web application, is disallowed by the admin.jar utility when binding a Web application to the Web site. A setting of null, which is converted to "/", is also disallowed.

As a result of this command, a <web-app> element is added to the specified Web site XML file, indicating the application name, the Web application name, and the context path.

See the next section, "Sample Deployment", for an example.

Sample Deployment

This example illustrates the result of deploying the utility.ear file shown in "EAR File and WAR File Structures", then binding its Web application. Here are the admin.jar commands, assuming % is the system prompt, j2ee/home is the current directory, and the EAR file is in j2ee/home/demo:

% java -jar admin.jar ormi://myhost:23791 admin welcome
  -deploy -file demo/utility.ear -deploymentName utility

% java -jar admin.jar ormi://myhost:23791 admin welcome
  -bindWebApp utility utility_web http-web-site /utilroot

Note the following:

  • The OC4J host name in this example is myhost; the port setting is 23791 in j2ee/home/config/rmi.xml.

  • In this example, the administrative account name is admin and the password is welcome.

  • The Web application name within utility.ear is utility_web, based on the WAR file name, utility_web.war.

  • The -bindWebApp command is to bind utility_web to the Web site defined by j2ee/home/config/http-web-site.xml. This assumes the following entry is in the server.xml file, as is the case by default:

    <web-site path="http-web-site.xml" />
    
    
  • The desired context path portion of the URL to invoke the Web application is "/utilroot".

The -deploy command results in the following entry in server.xml, as a subelement of the top-level <application-server> element:

<application name="utility" path="../applications/utility.ear"
             auto-start="true" />

The auto-start attribute specifies whether this application should be automatically restarted each time OC4J is restarted.

The -bindWebApp command results in the following entry in http-web-site.xml, as a subelement of the top-level <web-site> element:

<web-app application="utility" name="utility_web" root="/utilroot"
 load-on-startup="false" max-inactivity-time="no shutdown" shared="false" />

(See "Element Descriptions for Web Site XML Files" for information about the load-on-startup, max-inactivity-time, and shared attributes.)


Notes:

  • Remember that the value of the root attribute of the <web-app> element in http-web-site.xml overrides the value of the <context-root> element in application.xml. As a convention, though, use the same value in both places.

  • Information about the resulting server.xml and http-web-site.xml entries is provided as informative background. You should not have any reason to update these files manually when you use admin.jar.


After the deployment of utility.ear, the directory structure for key files is as follows, assuming default settings for the target directories:

j2ee/home/
   application-deployments/
      utility/
         orion-application.xml
         utility_web/
            orion-web.xml
   applications/
      utility.ear
      utility/
         utility_web.war
         META-INF/
            application.xml
         utility_web/
            index.html
            META-INF/
            WEB-INF/
               web.xml
               classes/
                  TestStatusServlet.class

The server.xml and http-web-site.xml files are in the j2ee/home/config directory.

If orion-application.xml and orion-web.xml exist in the EAR file, they are copied from there into the directories shown above. Otherwise, OC4J generates them into the directories shown above, using default settings from the corresponding OC4J global descriptors and J2EE descriptors.

Descriptors for Sample Deployment

The deployment in the preceding section uses the following descriptors. Passages of particular interest to servlet developers are marked in bold type.

The application.xml File

The standard application.xml descriptor is supplied by the developer. Some IDEs, such as Oracle JDeveloper, will create this for you.

<?xml version="1.0" ?> 
<!DOCTYPE application (View Source for full doctype...)> 
<application>
  <display-name>Web Services Demo</display-name> 
  <module>
    <web>
      <web-uri>utility_web.war</web-uri> 
      <context-root>/j2ee/utility</context-root> 
    </web>
  </module>
</application>

Remember that the <context-root> element here is overridden by the root attribute of the <web-app> element in the Web site XML file.

The web.xml File

The standard web.xml descriptor is supplied by the developer.

<?xml version="1.0" ?> 
<!DOCTYPE web-app (View Source for full doctype...)> 
<web-app>
  <display-name>Web Services Example</display-name> 
  <description>A few examples of web service publication</description> 
  <welcome-file-list>
    <welcome-file>index.html</welcome-file> 
  </welcome-file-list>
  <servlet>
    <servlet-name>TestStatus</servlet-name> 
    <servlet-class>TestStatusServlet</servlet-class> 
  </servlet>
  <servlet-mapping>
    <servlet-name>TestStatus</servlet-name> 
    <url-pattern>/TestStatusServlet</url-pattern> 
  </servlet-mapping>
</web-app>
The orion-application.xml File

Because the orion-application.xml descriptor is not included in the EAR file in this example, it is generated by OC4J. Most of the file is omitted here, but note that the <web-module> element mirrors the entry in the application.xml file.

<?xml version="1.0" ?> 
<!DOCTYPE orion-application (View Source for full doctype...)> 
<orion-application deployment-version="10.1.2.0.0"
                   default-data-source="jdbc/OracleDS" 
                   treat-zero-as-null="true" autocreate-tables="true" 
                   autodelete-tables="false">
  ...
  <web-module id="utility_web" path="utility_web.war" /> 
  ...
</orion-application>
The orion-web.xml File

Because the orion-web.xml descriptor is not included in the WAR file (within the EAR file) in this example, it is generated by OC4J. It is not shown here because there are no entries specific to the example.

Invoking the Sample Application

Given the information for the sample deployment in the preceding sections, in which /utilroot is specified as the context path in the admin.jar -bindWebApp command and /TestStatusServlet is specified as the servlet path in web.xml, you invoke the application as follows:

http://host:port/utilroot/TestStatusServlet

Deploying Files into a J2EE Application Structure on OC4J Standalone

Instead of deploying an EAR file, you can manually deploy the file structure and then update the server.xml and Web site XML files. This is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".)

Look again at "Sample Deployment", but assume that you manually create the j2ee/home/applications/utility directory and manually populate the application directory structure underneath:

j2ee/home/applications/utility/
   META-INF/
      application.xml
   utility_web/
      index.html
      META-INF/
      WEB-INF/
         web.xml
         classes/
            TestStatusServlet.class

Further assume that you update the server.xml file as follows:

<application name="utility" path="../applications/utility"
             auto-start="true" />

And you update the http-web-site.xml file as follows:

<web-app application="utility" name="utility_web" root="/utilroot"
 load-on-startup="false" max-inactivity-time="no shutdown" shared="false" />

Note that the path attribute in the <application> element in server.xml is "../applications/utility" instead of "../applications/utility.ear". This is because there is no EAR file, just the directory structure under the utility directory.

By default in OC4J standalone, when you update server.xml, OC4J detects the change, deploys the application, and copies or generates the orion-web.xml file and orion-application.xml file under the application-deployments directory as follows:

j2ee/home/
   application-deployments/
      utility/
         orion-application.xml
         utility_web/
            orion-web.xml

However, if OC4J update-checking is disabled, you must manually inform OC4J of your configuration updates, using the admin.jar -updateConfig option. Checking is enabled through the server.xml check-for-updates flag. See "Key OC4J Flags for Development".

Deploying an Independent WAR File to OC4J Standalone

"Deploying an EAR File to OC4J Standalone" discusses using the admin.jar utility to deploy an EAR file, including a WAR file within an EAR file for a Web module. For convenience during testing, it is also possible to manually deploy an independent WAR file, using the OC4J default application as the containing application. (A Web application must always be part of a parent J2EE application in OC4J.) This is an expert mode. See "Using Oracle Deployment Tools Versus Expert Modes".

See "OC4J Default Application and Default Web Application" for background information.

Use the following steps to deploy an independent WAR file to the OC4J default application:

  1. Place your WAR file in the desired directory.

  2. Update the OC4J global application.xml file to add a <web-module> element to specify the Web application name and the location of the WAR file.

  3. Update the appropriate Web site XML file, typically http-web-site.xml in OC4J standalone, to add a <web-app> element to bind the Web application to the Web site.

The following example illustrates deployment of a WAR file to the default application.


Note:

In Oracle Application Server, all applications are deployed in EAR files. If you use the Application Server Control Console Deploy Web Application Page in Enterprise Manager, which prompts you for a WAR file, then an EAR file is transparently created to contain the WAR file.

Example: Web Application Name in OC4J Default Application

This example shows entries in server.xml, the Web site XML file, and the OC4J global application.xml file for a Web application, mywebmod1, within the OC4J default application. Note the following:

  • The path attribute of the <web-site> element in server.xml specifies the path and name of the Web site XML file, http-web-site.xml in this example.

  • The name attribute of the <global-application> element in server.xml specifies the name of the OC4J default application and corresponds to the application attribute of the <web-app> element in http-web-site.xml.

  • The path attribute of the <global-application> element in server.xml points to the OC4J global application.xml file.

  • The name attribute of the <web-app> element in http-web-site.xml indicates a Web application, mywebmod1, within the OC4J default application and corresponds to the id attribute of a <web-module> element in the OC4J global application.xml file. Both of these attributes typically correspond to the WAR file name without the .war extension.

  • The global application.xml file must specify the name and location of the WAR file, through the path attribute of the <web-module> element, because there is no containing EAR file.

The following entries are in the server.xml file (no changes required):

<application-server ... >
   ...
   <global-application name="default" path="application.xml" />
   ...
   <web-site path="http-web-site.xml" />
   ...
</application-server>

Place the bold entry into the Web site XML file, http-web-site.xml:

<web-site protocol="http" port="8888" display-name="HTTP Web Site" 
          host="[ALL]" log-request-info="false" secure="false">
  ...
  <web-app application="default" name="mywebmod1" root="/someUrl"
           load-on-startup="false" max-inactivity-time="no shutdown"
           shared="false" /> 
  ...
</web-site>

(See "Element Descriptions for Web Site XML Files" for information about the <web-site> and <web-app> attributes shown here.)

Place the bold entry into the OC4J global application.xml file:

<orion-application ... >
  ...
  <web-module id="mywebmod1" path="../myhome/mywebmod1.war" /> 
  ...
</orion-application>


Note:

By default in OC4J standalone, editing the global application.xml file automatically results in the WAR file being unpacked beneath the directory in which you placed it. The orion-web.xml file, if you included one, is copied from the WAR file to the deployment directory (under j2ee/home/application-deployments by default). If you did not include orion-web.xml, one is generated for you in the deployment directory.

However, automatic detection of configuration changes depends on the server.xml check-for-updates flag, which is set to "true" by default. If this flag is disabled, you can trigger a one-time check through the admin.jar -updateConfig option. See "Key OC4J Flags for Development".


Deploying Files into a Web Application Directory Structure on OC4J Standalone

The previous section discusses how to deploy an independent WAR file to the OC4J default application. Alternatively, you can manually set up the J2EE Web application directory structure instead of using a WAR file. Again, this involves the OC4J default application. The simplest way to do this is to also use the OC4J default Web application, but you can optionally define a new Web application under the default application. See "OC4J Default Application and Default Web Application" for background information.

Each of these scenarios is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".) The following sections discuss them in detail:

Using a Web Application Directory Structure in the Default Web Application

By default, OC4J is configured with a default application and with a default Web application contained in the default application. To use the default Web application for your test files, put them in the standard Web application directory structure under the j2ee/home/default-web-app directory (the default directory for the default Web application).

Perform the following steps:

  1. Check relevant configuration in the server.xml file. First, you should see the following entry to define the name and specify the application descriptor for the default application:

    <global-application name="default" path="application.xml" />
    
    

    You should also see the following entry to specify the Web site XML file:

    <web-site path="./http-web-site.xml" />
    
    
  2. Look in the OC4J global application.xml descriptor. You should see the following entry to define the default Web application name and specify its root directory:

    <web-module id="defaultWebApp" path="../../home/default-web-app" />
    
    
  3. Look in the Web site XML file indicated in server.xml (http-web-site.xml, by default, in OC4J standalone). You should see the following entry to define defaultWebApp as the default Web application for the Web site. (As noted earlier, "/" is the context path for the default Web application in OC4J standalone, without the necessity of a root attribute in the <default-web-app> element.)

    <default-web-app application="default" name="defaultWebApp" />
    
    
  4. Given this configuration, deploy your files as follows:

    j2ee/home/default-web-app/
       index.html
       WEB-INF/
          web.xml
          classes/
             TestServlet.class
    
    

    No further action is necessary before you invoke the servlet.

Using a Web Application Directory Structure in an Alternative Web Application

In the previous section, the OC4J default Web application, defaultWebApp, is used to deploy a Web application directory structure. Alternatively, you can define some other Web application that will also be contained in the OC4J default application. This is useful if you want functionality similar to that of the default Web application, but deploying to a clean directory.

Here are the steps to define a Web application, myDefaultWebApp, within the default application:

  1. Add a <web-module> element to the OC4J global application.xml file. This defines the name and specifies the root directory of a new OC4J Web application. The entry for the OC4J default Web application is also shown for comparison:

    <web-module id="defaultWebApp" path="../../home/default-web-app" />
    <web-module id="myDefaultWebApp" path="../../home/my-default-web-app" />
    
    
  2. Add a <web-app> element to the Web site XML file, http-web-site.xml. This ties the Web application to a context path. The <default-web-app> element for the OC4J default Web application is also shown for comparison:

    <default-web-app application="default" name="defaultWebApp" />
    <web-app application="default" name="myDefaultWebApp" root="/mydefroot" />
    
    
  3. Given this configuration, deploy your files as follows. No further action is necessary before you invoke the servlet.

    j2ee/home/my-default-web-app/
       index.html
       WEB-INF/
          web.xml
          classes/
             TestServlet.class
    

Application Undeployment or Redeployment in OC4J Standalone

During testing, you will presumably have to modify and redeploy your application. The following sections describe undeployment and redeployment features for OC4J standalone:

Using admin.jar to Undeploy an Application

If you are finished using an application, you can use admin.jar to undeploy it as follows:

% java -jar admin.jar ormi://oc4j_host:oc4j_ormi_port 
                      adminuser adminpassword
                      -undeploy appname

This removes associated entries in server.xml and the Web site XML file, as well as removing all directories and files that were created and copied. See "Starting and Stopping OC4J Standalone" for information about the ORMI port. See "Setting Up an Administrative User and Password" for information about adminuser and adminpassword.

To undeploy the utility.ear application shown in "Sample Deployment", for example:

% java -jar admin.jar ormi://myhost:23791 admin welcome -undeploy utility


Note:

There is no need to undeploy an application before redeploying it. The admin.jar -undeploy option is for permanent removal.

Using admin.jar to Redeploy an Application

As when you initially deploy an application to OC4J standalone, use the admin.jar -deploy command to redeploy it. There is no difference to the user. The utility automatically effectively undeploys it first so that you will have a clean start. See "Deploying an EAR File to OC4J Standalone" for information about the -deploy command.

Before redeploying, you must repackage your EAR file to pick up any updated files. If you updated OC4J descriptors on the server, such as orion-web.xml and orion-application.xml, and want to keep the changes, then you must include these in the EAR file as well. Previously copied or generated OC4J descriptors are lost if there has been any update to the EAR file.

Manually Redeploying a WAR File

Deploying an independent WAR file to the OC4J default application is described in "Deploying an Independent WAR File to OC4J Standalone". If you want to redeploy, you must reverse the steps you took to deploy, repackage the WAR file, and repeat the deployment steps. This is an expert mode. (See "Using Oracle Deployment Tools Versus Expert Modes".)

To summarize:

  1. Comment out your updates to the global application.xml file and the http-web-site.xml file (or other Web site XML file).

  2. Update or repackage the WAR file with your updates. If there is anything in orion-web.xml that you want to save, then include it in the WAR file.

  3. Place the new WAR file back in the original target directory, overwriting the original if it is still there.

  4. Uncomment the updates in application.xml and http-web-site.xml. Updating application.xml causes OC4J to unpack the WAR file and copy or generate the orion-web.xml file as during the initial deployment.

Triggering Application Redeployment after File Manipulation

Depending on OC4J polling, which is enabled by default in OC4J standalone, there are several ways to trigger a redeployment of your application when you modify files in place on the server. (This is an expert mode. See "Using Oracle Deployment Tools Versus Expert Modes".)

  • Modify servlet class files under /WEB-INF/classes.

    If you update a servlet .class file under /WEB-INF/classes, then upon the next request, the servlet and its dependency classes are reloaded and the Web application is redeployed, regardless of whether OC4J polling is enabled.


    Notes:

    • A servlet and its dependency classes are reloaded immediately, instead of upon next request, if the servlet is set to be preloaded. This is according to load-on-startup settings. See "Servlet Preloading".

    • Changing a servlet class file in a directory location specified in a <classpath> element in global-web-application.xml or orion-web.xml has the same effect as changing a servlet class file in /WEB-INF/classes. However, changing a JAR file or a dependency class (such as a JavaBean) in a <classpath> location has no effect. See the description of the <classpath> element in "Element Descriptions for global-web-application.xml and orion-web.xml".


  • Modify standard descriptors (anything that changes the timestamp).

    If you modify web.xml while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs, which by default is once each second. Servlets and dependency classes in the Web application are reloaded upon the next request.

    If you modify application.xml while polling is enabled, the J2EE application is redeployed. Servlets and dependency classes in the Web application are reloaded upon the next request.

  • Modify library JAR files under /WEB-INF/lib.

    If you modify a JAR file in /WEB-INF/lib while polling is enabled, the Web application is redeployed the next time the OC4J task manager runs. Servlets and dependency classes in the Web application are reloaded upon the next request.

  • Set the OC4J development flag to "true".

    The development flag is an attribute of the <orion-web-app> element in global-web-application.xml and orion-web.xml. If development is set to "true", then the OC4J server checks a particular directory (the application /WEB-INF/classes directory by default) for updates to servlet source files. If a source file has changed since the last request, then OC4J will, upon the next request, recompile the servlet, redeploy the Web application, and reload the servlet and any dependency classes. See the description of development under "Element Descriptions for global-web-application.xml and orion-web.xml" for further information.

  • For JSP applications, set the JSP main_mode flag to "recompile".

    See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information.

  • Stop and restart OC4J.

    See "Starting and Stopping OC4J Standalone".

In OC4J standalone, polling is controlled through the server.xml check-for-updates flag, which is set to "true" by default. Alternatively, you can use the admin.jar -updateConfig option to trigger one-time polling. See "Key OC4J Flags for Development".


Notes:

Be aware of a few points in any of the preceding scenarios:
  • In this discussion, "redeployment" of a Web application refers to the process in which OC4J removes the Web application from its execution space, removes the classloader that was associated with execution of the Web application, reparses web.xml and orion-web.xml, and reinitializes servlet listeners, filters, and mappings.

  • To ensure a clean start, shut down and restart OC4J after the redeployment. See "Starting and Stopping OC4J Standalone".

  • Redeployment does not significantly affect OC4J descriptors such as orion-application.xml and orion-web.xml in the server deployment directory. After you trigger reloading, the previously copied or generated files will keep any nondefault settings that you have specified.


OC4J Deployment in Oracle Application Server

This section considers deployment and redeployment scenarios to OC4J in an Oracle Application Server environment.

In Oracle Application Server, you must use either Enterprise Manager or parallel commands in the dcmctl command-line utility for starting, stopping, configuring, and deploying applications. Both these tools are coordinated with the Oracle Application Server Distributed Configuration Management subsystem (DCM). You cannot use the OC4J standalone utility admin.jar for managing OC4J instances in an Oracle Application Server instance. In addition, do not manually update configuration files in Oracle Application Server. (See "Using Oracle Deployment Tools Versus Expert Modes".)


Note:

In Oracle Application Server, use either Enterprise Manager or dcmctl. Do not attempt to use both simultaneously to target the same OC4J instance or instances, and do not use both for different parts of the same deployment.

The following sections are included here:

Overview of OC4J Deployment and Configuration in Oracle Application Server

The Enterprise Manager pages for deploying and configuring Web modules are discussed in Chapter 7, "Configuration with Enterprise Manager". See the Oracle Application Server Containers for J2EE User's Guide for further information about using Enterprise Manager or the dcmctl command-line utility with OC4J.

The deployment scenarios discussed earlier in this chapter, using admin.jar or a manual deployment of application files, do not apply in an Oracle Application Server environment. Enterprise Manager includes pages for deploying an EAR file or a WAR file, as described in "Application Server Control Console Deploy Application (EAR) Page" and "Application Server Control Console Deploy Web Application (WAR) Page". In Oracle Application Server, do not manually deploy EAR or WAR files, or deploy loose files, as described in some of the scenarios for OC4J standalone.

In Oracle Application Server, copying EAR or WAR files, unpacking these files into a directory structure, and copying or generating the OC4J descriptors (such as orion-web.xml and orion-application.xml) are generally handled automatically and transparently through Enterprise Manager.

Deployment to Oracle Application Server through Enterprise Manager or dcmctl automatically registers Web applications with Oracle HTTP Server and results in a new mount point in the mod_oc4j.conf file. A URL mapping you specify in Enterprise Manager, such as "/mypath/myapp", defines the mount point. Mount points determine which URL requests are routed from Oracle HTTP Server to OC4J for processing. In this case, any URL request starting with "/mypath/myapp" (after the host and port) is handed off to OC4J.


Notes:

  • In Oracle Application Server, all applications are deployed in EAR files. If you use the Application Server Control Console Deploy Web Application Page in Enterprise Manager, which prompts you for a WAR file, an EAR file is transparently created to contain the WAR file.

  • Do not specify a context path of "/" when deploying to OC4J.


Several Enterprise Manager pages, also described in Chapter 7, are available for configuring servlet or Web site parameters. Manipulating settings in these pages results in appropriate configuration updates being made automatically. The configuration files discussed earlier in this chapter are used by OC4J in Oracle Application Server, but this is largely transparent and there are additional logistics to consider:

  • The Oracle Process Management and Notification subsystem (OPMN) dynamically overrides some of the settings in the configuration files, as well as some system properties and environment variables.

  • The DCM subsystem maintains a repository of configuration information. This repository, rather than the configuration files, contains the true configuration settings.

For these reasons, it is imperative that you not attempt to update configuration manually in Oracle Application Server.

If for some reason you must modify configuration files without going through Enterprise Manager, you must run a dcmctl update command to inform DCM of the changes. This will affect all instances of OC4J managed by DCM and should be avoided.

OPMN and DCM basics are covered in the Oracle Application Server Administrator's Guide. The dcmctl tool is documented in the Oracle Application Server Administrator's Guide as well. Also see the Oracle Enterprise Manager Concepts for further information about Enterprise Manager.

OC4J Default Web Application in Oracle Application Server

The default Web application in OC4J standalone is of potential use during development and is discussed in "OC4J Default Application and Default Web Application". OC4J has a default Web application in an Oracle Application Server environment as well, but it is not for developer use.

In Oracle Application Server, there is just one Web site, and the root namespace is owned by Oracle HTTP Server, not OC4J. The concept of an OC4J default Web application in an Oracle Application Server environment is not sensible in the way that it is for OC4J standalone, in which OC4J itself owns any Web sites. Furthermore, in OC4J standalone, the default Web application is used by manipulating files manually, which is not appropriate in Oracle Application Server.

In Oracle Application Server, as noted elsewhere, routing from Oracle HTTP Server to OC4J is accomplished through mount points in the mod_oc4j.conf file. Each time you deploy an application to OC4J in Oracle Application Server (as described in "Application Server Control Console Deploy Application (EAR) Page" and "Application Server Control Console Deploy Web Application (WAR) Page"), the URL that you specify as the context path results in the specification of that URL as another mount point.

One default OC4J mount point and context path, /j2ee, with a default Web application, defaultWebApp, exists for OC4J system use only. For example, if a request has a URL pattern that matches an OC4J mount point and, therefore, results in routing to OC4J, but the specified Web application cannot be found, then OC4J uses this default Web application to print an error message. This context path and default Web application are specified in the <default-web-app> element in default-web-site.xml. This element is required, but is not of direct use to developers.

Application Undeployment and Redeployment in Oracle Application Server

Oracle Enterprise Manager 10g includes features to undeploy or redeploy an application. The following sections introduce these features:

  • Using Enterprise Manager to Undeploy an Application

  • Using Enterprise Manager to Redeploy an Application


    Note:

    Using Enterprise Manager in Oracle Application Server, you can undeploy or redeploy an application through the Application Server Control Console OC4J Applications Page by selecting it from the applications list and then clicking the appropriate button. In either case, if you initially deployed a standalone WAR file, it was automatically wrapped in an EAR file during the deployment process. Therefore, it appears in the applications list.

Using Enterprise Manager to Undeploy an Application

If you are finished using a J2EE application in Oracle Application Server, you can undeploy it through the Application Server Control Console OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Undeploy button. This process removes all directories and files that were created and copied, and updates the server configuration appropriately.

See "Application Server Control Console OC4J Applications Page" to see what the page looks like and for further information.


Note:

There is no need to undeploy an application before redeploying it. The Enterprise Manager Undeploy feature is for permanent removal.

Using Enterprise Manager to Redeploy an Application

You can redeploy a J2EE application in Oracle Application Server through the Application Server Control Console OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Redeploy button. You will be prompted for the path to the EAR file.

See "Application Server Control Console OC4J Applications Page" to see what the page looks like and for further information.

During redeployment, if you have not changed the EAR file since the previous deployment, then server configuration settings are maintained from the previous deployment. This is particularly relevant for settings in the OC4J descriptors, such as orion-application.xml and orion-web.xml, given that standard configuration, such as through application.xml and web.xml, is presumably in your EAR file anyway.

If you have changed the EAR file, however, then the previous server configuration is discarded. It is replaced with information from the EAR file, such as from the OC4J descriptors (if present) and applicable default values. In this scenario, if you have made OC4J-specific configuration changes on the server, then you should make the same changes to the OC4J descriptors in the EAR file, in order to keep those changes.

After redeployment, you can check the OC4J servlet and Web site configuration pages, described in Chapter 7, "Configuration with Enterprise Manager", to verify whether desired configurations settings have been maintained.