Skip Headers

Oracle Application Server Containers for J2EE Servlet Developer's Guide 10g (9.0.4) Part Number B10321-01 |
Home | Contents | Index

# 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

- Overview of Configuration Files

- Application Packaging

- Deployment Scenarios to OC4J Standalone

- OC4J Deployment in Oracle Application Server

## 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 consists of 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 provides an overview of deployment and configuration in Oracle Application Server, and Chapter 7, "Configuration with Enterprise Manager", provides 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

- Overview of OC4J Deployment Scenarios

- Using Oracle Deployment Tools Versus Expert Modes

### 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 might 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, there is an OC4J default Web application that you can use for individual servlet files, JSP pages, and dependency classes.

Note: Key `admin.jar` commands are discussed where applicable 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. 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 would 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` (for automatic configuration resulting from deployment) 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 might 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 Sun Microsystems Java 2 Platform Enterprise Edition Specification and the Java Servlet Specification. These are 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:

- Deploy an EAR file. See "Deploying an EAR File to OC4J Standalone".

- Manually deploy files for a complete J2EE application into an application directory structure. See "Deploying Files into a J2EE Application Structure on OC4J Standalone".

- Deploy an independent WAR file. See "Deploying an Independent WAR File to OC4J Standalone".

- Manually deploy files for an independent Web application into a Web application directory structure. See "Deploying Files into a Web Application Directory Structure on OC4J Standalone". This includes the option of conveniently deploying servlets or JSP pages into the OC4J default Web application during initial testing. (See "OC4J Default Application and Default Web Application".)

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 the following table.

| OC4J Standalone | 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 might 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 global and 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. 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:

- Introduction to OC4J and J2EE Configuration Files

- OC4J Top-Level Server Configuration File: server.xml

- OC4J and J2EE Application Descriptors

- OC4J and J2EE Web Descriptors

- OC4J Web Site Descriptors

- Example: Mappings to and from Web Site Descriptors

Refer to the following for additional information:

- For the use of Enterprise Manager to configure OC4J in an Oracle Application Server environment, see the Oracle Application Server Containers for J2EE User's Guide.

- For the use of Enterprise Manager to configure servlets and Web modules in particular, see Chapter 7, "Configuration with Enterprise Manager", later in this manual.

- To configure OC4J standalone, see the Oracle Application Server Containers for J2EE Stand Alone User's Guide, available with the OC4J download from the Oracle Technology Network.

### 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, and `server.xml` in turn specifies the locations of the other server-level and global files (by default, the same directory). In OC4J standalone, the configuration file directory is configurable 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" below.

- `jazn.xml`: This configuration file for Oracle Application Server Java Authentication and Authorization Service (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 is the OC4J-specific global Web descriptor. See "OC4J and J2EE Web Descriptors".

- `oc4j-connectors.xml`: This 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. In Oracle Application Server, there is just one Web site. In OC4J standalone, there is typically one Web site, but you might use a second Web site for "shared" applications, for example, where 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 is the default Web site descriptor in an Oracle Application Server environment.

- `http-web-site.xml`: This 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 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:

- Oracle Application Server Containers for J2EE User's Guide for information about `server.xml` and load balancing

- Oracle Application Server Containers for J2EE Services Guide for information about data sources, RMI, JMS, and resource adapters in OC4J, and related descriptors

- Oracle Application Server Containers for J2EE Security Guide for information about security and JAAS in OC4J, and related descriptors

- Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for information about EJB development and the J2EE and OC4J EJB 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, added with the OC4J 9.0.4 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, as opposed to intact EAR files.

#### Figure 5-1 Mappings from the server.xml File

Text description of the illustration svrxmlmp.gif

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

There are three categories of application descriptors to consider in using OC4J. The following sections discuss each of them, then summarize their relationships to each other:

- Standard J2EE Application Descriptors

- OC4J Global Application Descriptor

- OC4J-Specific Application Descriptors

- Summary of Relationships Between Application Descriptors

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 Sun Microsystems Java 2 Platform Enterprise Edition 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

There is also an OC4J-specific global application descriptor, 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. There is no standard `application.xml` file that is 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 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 might make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value might 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 might 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 might 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.

There are three categories of Web descriptors to consider in using OC4J. The following sections discuss each of them and summarize the relationships between them:

- Standard J2EE Web Descriptors

- OC4J Global Web Application Descriptor

- OC4J-Specific Web Descriptors

- Summary of Relationships Between Web Descriptors

#### Standard J2EE Web Descriptors

The J2EE 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 might call.

See the Sun Microsystems Java 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: Generally 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 might 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 might make changes to the file but these changes are transparent. For example, an attribute setting that specifies the default value might 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 might use a second Web site for "shared" applications, for example, 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>

Note the following:

- 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

- EAR File and WAR File Structures

### 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
See "OC4J and J2EE Application Descriptors" for an overview of `application.xml` and `orion-application.xml`. See "OC4J and J2EE Web Descriptors" for an overview of `web.xml` and `orion-web.xml`. See the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for information about `ejb-jar.xml` and `orion-ejb-jar.xml`. See the Oracle Application Server Containers for J2EE User's Guide for information about `application-client.xml` and `orion-application-client.xml`.

### 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 might 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

- Starting and Stopping OC4J Standalone

- OC4J Default Application and Default Web Application

- Deploying an EAR File to OC4J Standalone

- Deploying Files into a J2EE Application Structure on OC4J Standalone

- Deploying an Independent WAR File to OC4J Standalone

- Deploying Files into a Web Application Directory Structure on OC4J Standalone

- Application Undeployment or Redeployment in OC4J Standalone

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

- Configuration of the Default Application and Default Web Application

Note: Use of the default application and default Web application for deployment during testing is a useful OC4J convenience feature, but is considered to be an expert mode because you are manually placing application files and sometimes manually updating configuration files. See "Using Oracle Deployment Tools Versus Expert Modes".

#### 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 will occur 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.

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

##### 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: The target directories are configurable. 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, or null, which is converted to "`/`", is not allowed by the `admin.jar` utility when binding a Web application to the Web site.

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

##### application.xml

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.

##### web.xml

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>

##### orion-application.xml

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

##### orion-web.xml

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, as follows.

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

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

- Using a Web Application Directory Structure in an Alternative Web Application

#### Using a Web Application Directory Structure in the Default Web Application

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

To verify the configuration, look 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" />

Next, 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" />

Finally, look in the Web site XML file that is 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" />

Given this configuration, you can deploy your files as in the following example. No further action is necessary before you invoke the servlet.

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

#### 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. This section describes the steps to define a Web application, `myDefaultWebApp`, within the default application.

First, add a `<web-module>` element to the OC4J global `application.xml` file, as in the following example. 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" />

Next, add a `<web-app>` element to the Web site XML file, `http-web-site.xml`, as in the following example. 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" />

Given this configuration, you can deploy your files as in the following example. 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

- Using admin.jar to Redeploy an Application

- Manually Redeploying a WAR File

- Triggering Application Redeployment after File Manipulation

#### 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 takes care of effectively undeploying 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, 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`, the servlet and its dependency classes are reloaded, and the Web application is redeployed, upon the next request. This is 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 where 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". For all intents and purposes, redeployment does not 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 of 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. Also, 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

- OC4J Default Web Application in Oracle Application Server

- Application Undeployment and Redeployment in Oracle Application Server

### 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 Deploy Application (EAR) Page" and "Application Server Control 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, issues of 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 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.

There are a number of Enterprise Manager pages, also described in Chapter 7, 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, 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, DCM, and the `dcmctl` tool are documented in the Oracle Application Server 10g Administrator's Guide. This guide and Oracle Enterprise Manager Concepts provide further information about Enterprise Manager as well.

### 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 Deploy Application (EAR) Page" and "Application Server Control 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, 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 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 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 OC4J Applications Page in Enterprise Manager. Select the application from the applications list (using the corresponding radio button) and click the Undeploy button. This removes all directories and files that were created and copied, and updates the server configuration appropriately.

See "Application Server Control 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 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 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, 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.

| Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index