Skip Headers

Oracle9iAS Containers for J2EE User's Guide
Release 2 (9.0.2)

Part Number A95880-01
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index

Go to previous page Go to next page

Advanced Configuration, Development, and Deployment

Chapter 2, "Configuration and Deployment", discusses basic configuration, development, and deployment of a J2EE application. This chapter discusses both global J2EE service configuration and advanced J2EE application configuration.

In the original OC4J product, all configuration was stored in XML files. With this release, OC4J is integrated with Enterprise Manager. This causes the entire configuration to be split into two segments:

This chapter discusses the following topics:

Configuring OC4J Using Enterprise Manager

You can configure J2EE services, J2EE applications, and Oracle9iAS clusters with Enterprise Manager. Some aspects are configured at the OC4J instance level; thus, they provide a global configuration for all deployed applications in the instance. Other aspects are configured at the application level; thus, this type of configuration is local and applicable only to the application.

The following sections provide you with an overview of advanced configuration within Enterprise Manager for OC4J:

OC4J Instance Level Configuration

There exists one OC4J Home Page for each OC4J instance configured. Generally, on the OC4J Home Page, you configure global services and deploy applications to this instance.

Specifically, from the OC4J Home Page, you can do the following:

Deploy Applications

You can deploy, redeploy, or undeploy a J2EE application that exists in an EAR or WAR file archival format. To deploy an application, click the Deploy EAR File or Deploy WAR File buttons to deploy in the Deployed Applications section on the OC4J Home Page.

This starts the deployment wizard that is covered in "Deploying Applications". If you deploy an EAR file, it must contain an application.xml that describes the application modules; if you deploy a WAR file, the application.xml file is created for you automatically.

To undeploy, click the Select radio button for the application and then click the Undeploy button.

To redeploy, click the Select radio button for the application and then click the Redeploy button.


You can also deploy, undeploy, or redeploy simple applications with the DCM command. See Appendix A, "DCM Command-Line Utility (dcmctl)" for directions.

Configuring Server Properties

To configure OC4J properties, scroll down to the Administration section of the OC4J Home Page. Select Server Properties in the Instance Properties column. The General section of this page contains the following fields:

Text description of advanc10.gif follows

Text description of the illustration advanc10.gif

In this section, you can modify OC4J server defaults. These are listed below:

The next section, Multiple VM Configuration, is dedicated as part of the cluster configuration. The following details what each field means; however, the context of how to configure clusters using this section is discussed fully in Chapter 9, "Oracle9iAS Clustering".

Text description of cluster1.gif follows.

Text description of the illustration cluster1.gif

Configure Web Site

To configure your Web site, scroll down to the Administration section of the OC4J Home Page. Select Website Properties in the Instance Properties column.

The Web site page has two sections. In the first section, you can see what is the default Web application and its parent. In the second section--URL Mappings for Web Modules--you can specify whether each Web application is to be loaded upon startup. These parameters are discussed in more detail in the Oracle9iAS Containers for J2EE Servlet Developer's Guide and are stored in the default-web-site.xml file.

Text description of advance9.gif follows

Text description of the illustration advance9.gif

Configure Global JSP Container Parameters

You can configure global JSP Container parameters. These apply to all JSPs deployed in this OC4J instance. To configure JSP Container parameters, scroll down to the Administration section of the OC4J Home Page. Select JSP Container Properties in the Instance Properties column. This brings you to the following page:

Text description of advance8.gif follows

Text description of the illustration advance8.gif

Most of the properties indicated here are described in Chapter 3 of the Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference. These properties can be included within the global-web-application.xml file within the <servlet> element.

Configure Global Web Application Parameters

To configure Web parameters that apply to all deployed Web applications, scroll down to the Administration section of the OC4J Home Page. Select Global Web Module in the Application Defaults column. This brings you to the following page:

Text description of advanc11.gif follows

Text description of the illustration advanc11.gif

The type of parameters that you can define for Web modules concern mappings, filtering, chaining, environment, security, and client access. Drill down into each of the provided links under the Properties and Security columns to modify these parameters. Each of these parameters are discussed in detail in the Oracle9iAS Containers for J2EE Servlet Developer's Guide. These parameters are stored in the global-web-application.xml and orion-web.xml files. This guide discusses the elements in these files.

Configure RMI and JMS

RMI and JMS can only be defined within an XML definition. To edit the XML files for either of these services, scroll down to the Advanced Properties section under the Instance Properties column on the OC4J Home Page. In this section, you can choose rmi.xml or jms.xml to modify the straight XML files for these services. See the Oracle9iAS Containers for J2EE Services Guide on how to modify these XML files.

Configure Data Sources

You can configure global or local data sources. A global data source is available to all deployed applications in this OC4J instance. A local data source is configured within the deployed application and can only be used by that application.

See Oracle9iAS Containers for J2EE Services Guide for a full explanation of how to configure a data source and the elements within the data-sources.xml file.

To configure global data sources, select one of the following off of the OC4J Home Page:

To configure local data sources, you perform the same selection off of the application page. You must drill down to the particular application that this data source will be local to. On the application page, choose Data Source under the Resources column. It displays the same data source field page that is discussed in "Data Source Field Page".

Data Source Field Page

When you choose Data Source under the Application Defaults column, you see the Data Sources that are currently configured.

To configure a new Data Source, click Add Data Source. This brings you to a page where you can enter all configuration details about the data source. This page is divided up into four sections.

Figure 3-1 shows the General section.

Figure 3-1 General Section of Data Source Definition

Text description of advanc12.gif follows

Text description of the illustration advanc12.gif

The General section enables you to define the following aspects about a data source:

Figure 3-2 shows the JNDI Locations section.

Figure 3-2 JNDI Locations

Text description of add_ds2.gif follows.

Text description of the illustration add_ds2.gif

The JNDI Locations section enables you to define the JNDI location string that the data source is bound with. The JNDI location is used within JNDI lookup for retrieving this data source.

Figure 3-3 shows the Connection Attributes section.

Figure 3-3 Connection Attributes

Text description of add_ds3.gif follows.

Text description of the illustration add_ds3.gif

This section enables you to modify connection tuning parameters, including the retry interval, pooling parameters, timeout parameters, and maximum attempt parameter.

Figure 3-4 shows the Properties section for the data source.

Figure 3-4 Properties

Text description of add_ds4.gif follows.

Text description of the illustration add_ds4.gif

If your data source is a third party data source, you may need to set certain properties. These properties would be defined in the third-party documentation. In addition, properties must be set for JTA transactions for the two-phase commit coordinator.

Configure Security

The type of security you use is designated by the User Manager configured. The default User Manager for all applications is the JAZN User Manager. Within the User Manager type, you configure groups, users, and roles.

Each application can be assigned its own User Manager if you do not want to use the default JAZN User Manager. You chose the User Manager that you will use for the application on the deployment wizard. See Chapter 8, "Security" for more information on User Managers.

To configure groups, users, or roles in the default JAZN User Manager, do the following:

  1. On the OC4J Home Page, scroll down to the Administration section.

  2. Choose Security under the Application Defaults column, as shown in Figure 3-5.

Figure 3-5 OC4J Home Page Administration Properties

Text description of home_adm.gif follows.

Text description of the illustration home_adm.gif

Choosing Security allows you to manage groups, users, and roles for the default JAZN User Manager, as shown in Figure 3-6. These groups, users, and roles can be used in all applications deployed in this OC4J instance.

Figure 3-6 Security Page

Text description of prin_xml.gif follows.

Text description of the illustration prin_xml.gif

The default User Manager is the JAZN User Manager. However, you can also assign a separate User Manager for each application.

See Chapter 8, "Security" and Oracle9iAS Containers for J2EE Services Guide for a discussion of how to configure your security.

Configure UDDI Registry

To configure the UDDI Registry, scroll down to the Administration section of the OC4J Home Page. Select the UDDI Registry in the Related Links column.

Manipulating XML Files

In OC4J version, you configured the OC4J server and all deployed application parameters through XML files. Since the OC4J server existed on a single node and did not need high availability and clustering management, this worked well. However, with the integration of OC4J with Oracle9iAS, increased enterprise management abilities with clustering and high availability options, all configuration must be accomplished through Enterprise Manager.

For those developers who are used to working with the OC4J XML files and wish to continue to do so, the Advanced Properties section allows you to continue this ability.

There are four groups of XML files located within Enterprise Manager:

As an example, the server.xml page is shown. Notice that you can hand edit the XML elements.

Text description of advanc13.gif follows

Text description of the illustration advanc13.gif

If you do not understand the OC4J XML files, see "Overview of OC4J and J2EE XML Files" for a discussion of these files and their relation to each other. Other books in the OC4J documentation set describe the elements within each of these files.

Application Level Configuration

Once you have deployed your application, you can modify most of the parameters for this application. To configure application-specific parameters, do the following:

  1. On the OC4J Home Page, scroll down to the Application section.

  2. Select the application where you want to change the configuration using one of the following methods:

    1. Click the Select radio button for the application and click the Edit button.

    2. Select the application name in the Name column in the applications box.

This page is the initiating point for changing general application configuration as well as configuration specific to a certain part of your deployed application, such as a WAR file.

The following sections provide a brief overview of these configuration options:

Configuring Application General Parameters

If you scroll down to the Administration section and select the General link, you can configure a multitude of application details, as follows:

Configuring Local J2EE Services

As described in "Configure Data Sources" and "Configure Security", you can configure data sources and security either for all deployed applications (global) or only for a specific application (local). See these sections for directions on how to configure your J2EE services for your application.

Modifying XML Files Included in the Deployed Application EAR File

You can modify only the OC4J-specific XML files of your application after deployment. This includes orion-ejb-jar.xml, orion-web.xml, and orion-application-client.xml. You cannot modify the J2EE XML files, such as web.xml, ejb-jar.xml, and application-client.xml.

In order to modify the OC4J-specific XML files, do the following:

  1. From the application screen, select the JAR or WAR file whose configuration you are interested in modifying. The application screen is shown.

  2. You can modify parameters for the application in one of the following manners:

    • Follow links in the Administration section for modifying parameters.

    • Select the bean or servlet in the section that details the beans, servlets, or JSPs deployed. This drills down to another level of configuration.

    • The Administration section contains either a Properties or Advanced Properties section that allows you to modify XML directly for the OC4J-specific deployment descriptors--orion-ejb-jar.xml, orion-web.xml, and orion-application-client.xml.

Overview of OC4J and J2EE XML Files

This section contains the following topics:

XML Configuration File Overview

Each XML file within OC4J exists to satisfy a certain role; thus, if you have need of that role, you will understand which XML file to modify and maintain.

Figure 3-7 illustrates all the OC4J XML files and their respective roles.

Figure 3-7 OC4J and J2EE Application Files

Text description of advancea.gif follows

Text description of the illustration advancea.gif


Each deployed application uses an application.xml as its manifest file. That XML file is local to the application and separate from the global application.xml, which configures options that are applied to all applications deployed in this OC4J server instance.

Table 3-1 describes the role and function for each XML file that was displayed in the preceding figure.

Table 3-1 OC4J Features and Components  
XML Configuration File Features/Components


OC4J overall server configuration. Configures the server and points to the XML files that add to this file, such as jms.xml for JMS support. The listing of other XML files enables the services to be configured in separate files, but the server.xml file denotes that they be used for the OC4J configuration.



OC4J security configuration for JAZN security required for accessing the server.


OC4J data source configuration for all databases used by applications within OC4J.


OC4J RMI port configuration and RMI tunneling over HTTP.


OC4J JMS configuration for Destination topics and queues that are used by JMS and MDBs in OC4J.


OC4J Web site definition.


The mod_oc4j module is an Oracle HTTP Server module that forwards OC4J requests. This file configures the mount point that denotes what contexts to be directed to OC4J.


J2EE application manifest file and configuration files.

  • The global application.xml file exists in the j2ee/home/config directory and contains common settings for all applications in this OC4J instance. This file defines the location of the security XML definition file--jazn-data.xml and the datasource XML definition file--data-sources.xml. This is a different XML file than the local application.xml files.

  • The local application.xml file defines the J2EE EAR file, which contains the J2EE application modules. This file exists within the J2EE application EAR file.

  • The orion-application.xml file is the OC4J-specific definitions for all applications.


J2EE Web application configuration files.

  • global-web-application.xml is an OC4J-specific file for configuring servlets that are bound to all Web sites.

  • web.xml and orion-web.xml for each Web application.

The web.xml files are used to define the Web application deployment parameters and are included in the WAR file. In addition, you can specify the URL pattern for servlets and JSPs in this file. For example, servlet is defined in the <servlet> element, and its URL pattern is defined in the <servlet-mapping> element.


J2EE EJB application configuration files. The ejb-jar.xml files are used to define the EJB deployment descriptors and are included in the EJB JAR file.


J2EE client application configuration files.


Connector configuration files.

  • The oc4j-connectors.xml file contains global OC4J-specific configuration for connectors.

  • The ra.xml file contains J2EE configuration.

  • The oc4j-ra.xml file contains OC4J-specific configuration.

XML File Interrelationships

Some of these XML files are interrelated. That is, some of these XML files reference other XML files--both OC4J configuration and J2EE application (see Figure 3-9).

Here are the interrelated files:

The server.xml file is the keystone that contains references to most of the files used within the OC4J server. Figure 3-8 shows the XML files that can be referenced in the server.xml file:

Figure 3-8 XML Files Referenced Within server.xml

Text description of advance4.gif follows

Text description of the illustration advance4.gif

Figure 3-9 demonstrates how the server.xml points to other XML configuration files. For each XML file, the location can be the full path or a path relative to the location of where the server.xml file exists. In addition, the name of the XML file can be any name, as long as the contents of the file conform to the appropriate DTD.

In addition to pointing to the OC4J server configuration files, the server.xml file describes the applications that have been deployed to this OC4J server. Each deployed application is denoted by the <application> tag.

Figure 3-9 Server.xml File and Related XML Files

Text description of advance3.gif follows

Text description of the illustration advance3.gif

Other tags for server.xml are described in "Elements in the server.xml File".


If you understand the OC4J XML files from previous releases of OC4J, you can simply change most of the OC4J server XML configuration files by drilling to the OC4J Home Page, scroll down to Administration, and click on Advanced Properties. From here, you can modify the XML files using an Enterprise Manager editor.

What Happens When You Deploy?

When you become more proficient with OC4J and deploying applications, you should acquaint yourself with what OC4J does for you. The following sections help you understand these tasks:

OC4J Tasks During Deployment

When you deploy your application, the following occurs:

OC4J opens the EAR file and reads the descriptors.

  1. OC4J opens, parses the application.xml that exists in the EAR file. The application.xml file lists all of the modules contained within the EAR file. OC4J notes these modules and initializes the EAR environment.

  2. OC4J reads the module deployment descriptors for each module type: Web module, EJB module, connector module, or client module. The J2EE descriptors are read into memory. If OC4J-specific descriptors are included, these are also read into memory. The JAR and WAR file environments are initialized.

  3. OC4J notes any unconfigured items that have defaults and writes these defaults in the appropriate OC4J-specific deployment descriptor. Thus, if you did not provide an OC4J-specific deployment descriptor, you will notice that OC4J provides one written with certain defaults. If you did provide an OC4J-specific deployment descriptor, you may notice that OC4J added elements.

  4. OC4J reacts to the configuration details contained in both the J2EE deployment descriptors and any OC4J-specific deployment descriptors. OC4J notes any J2EE component configurations that require action on OC4J's part, such as wrapping beans with their interfaces.

  5. After defaults have been added and necessary actions have been taken, OC4J writes out the new module deployment descriptors to the application-deployments/ directory. These are the descriptors that OC4J uses when starting and restarting your application. But do not modify these descriptors. Always change your deployment descriptors in the "master" location.

  6. OC4J copies the EAR file to the "master" directory. This defaults to the applications/ directory. You can change the "master" directory in the Server Properties page off of the OC4J Home Page. In the General section, modify the Application Directory field to the new location of the "master" directory. The location of the directory is relative to /j2ee/home/config.


    Each time you deploy this EAR file without removing the EAR file from the applications/ directory, the new deployment renames the EAR file prepended with an underscore. It does not copy over the EAR file. Instead, you can copy over the EAR file. OC4J notices the change in the timestamp and redeploys.

  7. Finally, OC4J updates the server.xml file with the notation that this application has been deployed.

Configuration Verification of J2EE Applications

After deployment, you can see your application configuration in the server.xml and web-site.xml files, as follows:

Understanding and Configuring OC4J Listeners

Incoming client requests use one of three protocols: AJP, HTTP, or RMI. AJP and HTTP are used for HTTP requests. AJP is used between the OHS and OC4J components. HTTP is used for HTTP requests directed past OHS to OC4J. RMI is used for incoming EJB requests.

HTTP Requests

All HTTP requests, whether through OHS or directly to OC4J, must have a listener configured in an OC4J Web site. You can have two Web sites for each OC4J instance: one for each protocol type. That is, one Web site is only for AJP requests and the other is for HTTP requests. You cannot have one Web site listen for both types of protocols. Thus, OC4J provides two Web site configuration files:

RMI Requests

RMI protocol listener is set up in the RMI configuration--rmi.xml. It is separate from the Web site configuration. EJB clients and the OC4J tools access the OC4J server through a configured RMI port. The default RMI port is 23791. The following shows the default RMI port number configured in the rmi.xml file:

<rmi-server port="23791" >

You can modify the rmi.xml file only in the Advanced Properties on the OC4J Home Page.

Configuring Oracle HTTP Server With Another Web Context

The mod_oc4j module in the Oracle HTTP Server is configured at install time to direct all j2ee/ context bound applications to the OC4J server. If you want to use a different context, such as pubs/, you can add another mount for this context in the mod_oc4j.conf configuration file.

To modify this file, drill down to the Oracle HTTP Server Page and select mod_oc4j.conf. The file is presented for edits in the right-hand frame.

  1. Find the Oc4jMount directive for the j2ee/ directory. Copy it to another line. The mount directive is as follows:

    Oc4jMount /j2ee/* OC4Jworker


    The OC4Jworker is defined further down in the mod_oc4j.conf file to be the OC4J instance.

  2. Modify the j2ee/ context to your desired context. In our example, you would have another line with a pubs/ mount configuration. Assuming that the OC4J worker name is OC4Jworker, then both lines would be as follows:

    Oc4jMount /j2ee/* OC4Jworker
    Oc4jMount /pubs/* OC4Jworker
  3. Restart the Oracle HTTP Server to pick up the new mount point.

Then all incoming requests for the pubs/ context will be directed to the OC4J server. Note that when you deploy an application using the deployment wizard, the wizard automatically adds a mount point as described here for your URL mapping.

See the Oracle HTTP Server Administration Guide for complete details on the mod_oc4j module configuration.

Building and Deploying Within a Directory

When developing applications, you want to quickly modify, compile, and execute your classes. OC4J can automatically deploy your applications as you are developing them within an expanded directory format. OC4J automatically deploys applications if the timestamp of the top directory, noted by <appname> in Figure 3-10, changes. This is the directory that server.xml knows as the "master" location. Normally, you develop under the j2ee/home/applications directory.

The application must be placed in the "master" directory in the same hierarchical format as necessary for JAR, WAR, and EAR files. For example, if <appname> is the directory where your J2EE application resides, Figure 3-10 displays the necessary directory structure.

Figure 3-10 Development Application Directory Structure

Text description of advance5.gif follows

Text description of the illustration advance5.gif

To deploy EJB or complex J2EE applications in an expanded directory format, complete the following steps:

  1. Place the files in any directory. Figure 3-10 demonstrates an application placed into j2ee/home/applications/<appname>/. The directory structure below <appname> is similar to that used within an EAR file, as follows:

    1. Replace the EJB JAR file name, Web application WAR file name, client JAR file name, and Resource Adapter Archive (RAR) file name with a directory name of your choosing to represent the separate modules. Figure 3-10 demonstrates these directory names by <ejb_module>/, <web_module>/, <client_module>/, and <connector_module>/.

    2. Place the classes for each module within the appropriate directory structure that maps to their package structure.

  2. Modify the server.xml, applications.xml, and *-web-site.xml files as follows:

    • In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> element for each J2EE application. The path points to the "master" application directory. In Figure 3-10, this is j2ee/home/applications/<appname>/.

      You can specify the path in one of two manners:

      • Specifying the full path from root to the parent directory.

        In the example in Figure 3-10, if <appname> is "myapp", then the fully-qualified path is as follows:

            auto-start="true" />
      • Specifying the relative path. The path is relative to where the server.xml file exists to where the parent directory lives.

        In the example in Figure 3-10, if <appname> is "myapp", then the relative path is as follows:

        <application_name="myapp" path="../myapp" auto-start="true" 
    • In application.xml, modify the <module> elements to contain the directory names for each module--not JAR or WAR files. You must modify the <web-uri>, the <ejb>, and the <client> elements in the application.xml file to designate the directories where these modules exist. The path included in these elements should be relative to the "master" directory and the parent of the WEB-INF or META-INF directories in each of these application types.

      For example, if the <web_module>/ directory in Figure 3-10 was "myapp-web/", then the following example designates this as the Web module directory within the <web-uri> element as follows:

    • In the *-web-site.xml file, add a <web-app...> element for each Web application. This is important, because it binds the Web application within the Web site. The application attribute value should be the same value as that provided in the server.xml file. The name attribute should be the directory for the Web application. Note that the directory path given in the name element follows the same rules as for the path in the <web-uri> element in the application.xml file.

      To bind the"myapp" Web application, add the following:

      <web-app application="myapp" name="myapp/myapp-web" root="/myapp" 


      You achieve better performance if you are deploying with a JAR file. During execution, the entire JAR file is loaded into memory and indexed. This is faster than reading in each class from the development directory when necessary.

Go to previous page Go to next page
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Go To Product List
Solution Area
Go To Table Of Contents
Go To Index