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

• All OC4J server configuration should be managed through Enterprise Manager.

• J2EE application deployment descriptors and the application.xml file must still be constructed by hand within XML files.

This chapter discusses the following topics:

• Configuring OC4J Using Enterprise Manager

• Overview of OC4J and J2EE XML Files

• What Happens When You Deploy?

• Understanding and Configuring OC4J Listeners

• Configuring Oracle HTTP Server With Another Web Context

• Building and Deploying Within a Directory

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

• Application Level Configuration

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

• Configure Web Site

• Configure Global JSP Container Parameters

• Configure Global Web Application Parameters

• Configure RMI and JMS

• Configure Data Sources

• Configure Security

• Configure UDDI Registry

• Manipulating XML Files

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.

Note: 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 the illustration advanc10.gif

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

• Default application--The default application is what most deployed applications used as its parent. Thus, these deployed applications can see the classes within the default application.

• Default application path--There exists a file named application.xml, which is separate from the application.xml included with each EAR file. This application.xml file is known as the global application.xml file. It defines properties that are used across all deployed applications within this OC4J instance. Some of the properties exist in the rest of this page. If you want to change the name and the content of this global application.xml file, modify this field to contain the new XML filename. However, this file must conform to the DTD that Oracle specifies. The directory is relative to j2ee/home/config.

• Default Web module properties--These are specified in an XML file called global-web-application.xml. If you want it to refer to another XML file, you can change the pointer to this file here. However, this file must conform to the DTD that Oracle specifies. The directory is relative to j2ee/home/config.

  If you want to actually modify elements contained within this file, update entries in either the Web Site Properties or Advanced Properties section. These are discussed more in "Configure Web Site" and "Manipulating XML Files".

• Application and deployment directories--The default directory to place the "master" EAR file of the deployed application is the /applications directory. The default directory is where OC4J places modified module deployment descriptors with added defaults. Currently, this location is in the /application-deployments directory. You can change the locations of the default directories in these fields. The directory is relative to j2ee/home/config. See "What Happens When You Deploy?" for more information on the usage of these directories.

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 the illustration cluster1.gif

• Islands--Designate the number of islands within the cluster. Each island is created when you click on the Add Another Row button. You can supply a name for each island within the Island ID field. You can designate how many OC4J processes should be started within each island by the number configured in the Number of Processes field.

• Ports--This section enables you to configure what the port ranges should be for RMI, JMS, and AJP.

• Command Line Options--This section enables you to configure the following:
  • the Java executable command that should be used, such as javac

  • any OC4J options to include when starting a new OC4J process

  • any Java options to include when executing 'java'

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

• Data Sources under the Application Defaults column--This page allows you to add data source definitions one field at a time. See "Data Source Field Page" for a description of this page.

• Advanced Properties under the Instance Properties column--Select data-sources.xml on this page. This allows you to add data sources using the XML definitions. This is useful if you have been provided the XML. You can just copy in the already configured data sources.

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 the illustration advanc12.gif

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

• Name--A user-defined name to identify the data source.

• Description--A user-defined description of the data source.

• Data Source Class--This is the class, such as com.evermind.sql.ConnectionDataSource, that the data source is instantiated as.

• Schema--This is an optional parameter. Input the file name that contains the Java to database mappings for a particular database.

• Username/Password--The username and password used to authenticate to the database that this data source represents.

• JDBC URL--The URL to the database represented by this data source. For example, if using an Oracle Thin driver, the URL could be the following: jdbc:oracle:thin:@my-lap:1521:SID.

• JDBC Driver--The JDBC driver to use. One example of a JDBC driver is oracle.jdbc.driver.OracleDriver.

Figure 3-2 shows the JNDI Locations section.

Figure 3-2 JNDI Locations

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

• OC4J Server XML files: These include the XML files that configure the server and its services. The files that are in this group are server.xml, global-web-application.xml, rmi.xml, jms.xml, http-web-site.xml, and default-web-site.xml. Modify any of these XML files in the Advanced Properties page off of the OC4J Home Page.

• Global application XML files: These include XML files that apply to all applications deployed in the OC4J instance. These include the global application.xml, data-sources.xml, jazn-data.xml and oc4j-connectors.xml. To modify these XML files, choose default under Default Application on the OC4J Home Page. On the default application page, scroll down to the Administration section and choose Advanced Properties.

• Local application XML files. You can modify XML files that configure the overall application. These include local data sources, local security, and OC4J-specific application configuration. These XML files include data-sources.xml, jazn-data.xml, and orion-application.xml. To modify these files, drill down to the specific application. On the application screen, scroll down to the Administration section and choose Advanced Properties.

• Application module XML files: When the EAR or WAR file is deployed, you provided module deployment descriptors, such as web.xml, orion-web.xml, ejb-jar.xml, and orion-ejb-jar.xml. You can modify parameters only in the OC4J-specific (orion-xxx.xml) XML files. You cannot modify the J2EE XML files, such as web.xml or ejb-jar.xml. For more information on modifying these XML files, see "Modifying XML Files Included in the Deployed Application EAR File".

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

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

• Configuring Local J2EE Services

• Modifying XML Files Included in the Deployed Application EAR File

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:

• persistence path

• data sources path

• library paths

• EJB properties
  • automatically create database tables for CMP beans

  • automatically delete old database tables for CMP beans

• default data source (JNDI name)

• User Manager configuration

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

• XML File Interrelationships

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.

• OC4J server: All XML files within this box are used to set up this instance of the OC4J server. These files configure things such as listening ports, administration passwords, security, and other basic J2EE services.

  These files configure the OC4J server and point to other key configuration files. The settings in the OC4J configuration files are not related to the deployed J2EE applications directly, but to the server itself.

• Oracle HTTP Server: These files are configuration files within the Oracle HTTP Server. However, they are included in this diagram because you may need to modify these to change how requests are handed off to the OC4J server.

• Web site: These XML files configure listening ports, protocols, and Web contexts for the OC4J Web site.

• Application XML files: Each J2EE application type (EJB, servlet, JSP, connector) requires its own configuration (deployment) files. Each application type has one J2EE deployment descriptor and one OC4J-specific deployment descriptor, which is denoted with an "orion-" prefix. In addition, the following are global configuration files for all components in the application:
  • The application.xml as the global application configuration file that contains common settings for all applications in this OC4J instance.

  • The orion-application.xml file contains OC4J-specific global application information for all applications in this OC4J instance.

  • The global-web-application.xml file contains OC4J-specific global Web application configuration information that contains common settings for all Web modules in this OC4J instance.

  • The oc4j-connectors.xml file contains global connector configuration information.

Figure 3-7 OC4J and J2EE Application Files

Text description of the illustration advancea.gif

Note: 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
server.xml	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.
jazn.xml jazn-data.xml	OC4J security configuration for JAZN security required for accessing the server.
data-sources.xml	OC4J data source configuration for all databases used by applications within OC4J.
rmi.xml	OC4J RMI port configuration and RMI tunneling over HTTP.
jms.xml	OC4J JMS configuration for Destination topics and queues that are used by JMS and MDBs in OC4J.
default-web-site.xml	OC4J Web site definition.
mod_oc4j.conf	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.
application.xml orion-application.xml	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.
global-web-application.xml web.xml orion-web.xml	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.
ejb-jar.xml orion-ejb-jar.xml	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.
application-client.xml orion-application-client.xml	J2EE client application configuration files.
oc4j-connectors.xml ra.xml oc4j-ra.xml	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:

• server.xml--contains references to the following:
  • All web-site.xml files for each Web site for this OC4J server

  • The location of each of the other OC4J server configuration files, except jazn-data.xml and data-sources.xml which are defined in the global application.xml, shown in Figure 3-7

  • The location of each application.xml file for each J2EE application that has been deployed in OC4J

• web-site.xml--references applications by name, as defined in the server.xml file. And this file references an application-specific EAR file.

• application.xml--contains references to the jazn-data.xml and data-sources.xml 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 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.

• The <rmi-config> tag denotes the name and location of the rmi.xml file.

• The <jms-config> tag denotes the name and location of the jms.xml file.

• The <global-application> tag denotes the name and location of the global application.xml file.

• The <global-web-app-config> tag denotes the name and location of the global-web-application.xml file.

• The <web-site> tag denotes the name and location of one *-web-site.xml file. Since you can have multiple Web sites, you can have multiple <web-site> entries.

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 the illustration advance3.gif

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

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

• Configuration Verification of J2EE Applications

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.

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

• In server.xml, each existing application contains a line with an
  <application name=... path=... auto-start="true" /> entry. The auto-start attribute designates that you want this application automatically started when OC4J starts.

• In web-site.xml, a <web-app...> entry exists for each Web application that is bound to the Web site upon OC4J startup. Because the name attribute is the WAR filename (without the .WAR extension), there is one line for each WAR file included in your J2EE application.

  For each Web application binding included in a WAR file, the following line has been added:

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

  • The application attribute is the name provided in the server.xml as the application name.

  • The name attribute is the name of the WAR file, without the .WAR extension.

  • The root attribute defines the root context for the application off of the Web site. For example, if you defined your Web site as "http://<ohs_host>:7777/j2ee", then to initiate the application, point your browser at "http://<ohs_host>:7777/j2ee/myapp".

    Note: Wait for automatic startup to complete before trying to access the client. The client fails on lookup if it tries to access before the completion of these processes.

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:

• default-web-site.xml--This is the AJP protocol listener and the default for most HTTP requests that use Oracle9iAS. After installation, the Oracle HTTP Server front-end forwards incoming HTTP requests over the AJP port. The OC4J Web server configuration file (default-web-site.xml) indicates the AJP listener port. The default-web-site.xml file defines the default AJP port as zero. This enables OC4J and the Oracle HTTP Server to negotiate a port upon startup. The range of port values that the AJP port can be is configured in the OPMN configuration. See the High Availability chapter in the Oracle9i Application Server Administrator's Guide for more information on OPMN.

  The following shows the entry in the default-web-site.xml for the default AJP listener:

  <web-site host="oc4j_host" port="0" protocol="ajp13"
  
      display-name="Default OC4J WebSite">
  

  You can configure the AJP default Web site protocol in two places: Website Properties or Advanced Properties off of the OC4J Home Page.

• http-web-site.xml--This is the HTTP protocol listener. If you want to bypass OHS and go directly to OC4J, you use the port number defined in this file. However, you must be careful. The AJP port is chosen at random every time OC4J is started. If it chooses the same port number that is hard-coded in this XML file, there will be a conflict. If you use this method for incoming requests, verify that the port number you choose is outside of the range for AJP port numbers, which is defined in the OPMN configuration.

  The default HTTP port is 7777. The following shows the entry in the http-web-site.xml for an HTTP listener with a port number of 7777:

  <web-site host="oc4j_host" port="7777" protocol="http"
  
      display-name="HTTP OC4J WebSite">
  

  Note: In a UNIX environment, the port number should be greater than 1024, unless the process has administrative privileges.

  You access the http-web-site.xml file only in the Advanced Properties on the OC4J Home Page.

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
   

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

       <application_name="myapp"
           path="/private/j2ee/home/applications/myapp"  
           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:

     <module>
       <web>
         <web-uri>myapp-web</web-uri>
       </web>
     </module>
     

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

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