|
Oracle® Application Server Containers for J2EE User's Guide
10g Release 2 (10.1.2) Part No. B14011-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE User's Guide
10g Release 2 (10.1.2) Part No. B14011-02 |
|
|
Previous |
Next |
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.
This chapter discusses the following topics:
You can configure J2EE services, J2EE applications, and Oracle Application Server 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:
Off of the OC4J Home page, you can configure global services that apply to all applications by drilling down to the Administration page, which allows you to configure the following:
To configure OC4J properties, scroll down to the Instance Properties section and select Server Properties. The General section of this page contains the following fields:
Figure 3-1 General Section of the Instance Properties Page
The following information about the default server properties is displayed in the upper half of the page.
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. See "Select Application" for more information on parent applications.
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.
In this section, you can modify OC4J server defaults. These are listed below:
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 a Web Site" and "Modifying XML Files Included in the Deployed Application EAR File".
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 4, "OC4J Clustering".
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. For more information on configuring islands for clustering, see "OC4J Cluster Configuration".
Ports—This section enables you to configure what the port ranges should be for RMI, JMS, AJP, and IIOP. For more information on these services, see the Oracle Application Server Containers for J2EE Services Guide.
Figure 3-3 Command-Line Options and Environment Variables
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'
any OC4J system properties
See "OC4J Command-Line Options and System Properties" for a list of command-line options and system properties.
Environment Variables—This section enables you to configure environment variables for OC4J. To add a new environment variable, click Add Environment Variable. A new row is added for you to define the variable name in the left column and the value in the right column.
To configure your Web site, select Website Properties in the Instance Properties column on the Administration page.
The Web site page has two sections. In the first section, you can see what is the default Web application. 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 Oracle Application Server Containers for J2EE Servlet Developer's Guide and are stored in the default-web-site.xml file.
You can configure global JSP Container parameters. These apply to all JSPs deployed in this OC4J instance. To configure JSP Container parameters, select JSP Container Properties in the Instance Properties column on the Administration page. This brings you to the following page:
Figure 3-5 Oracle JSP Container Properties
Most of the properties indicated here are described in Chapter 3 of the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide. These properties can be included within the global-web-application.xml file within the <servlet> element.
For clustering servlet or EJBs, you may need to configure replication parameters. See "OC4J Instance Configuration" for details.
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 Oracle Application Server, increased enterprise management abilities with clustering and high availability options, all configuration must be accomplished through Enterprise Manager.
When you select Advanced Properties off of the Administration page, you can modify the 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, and default-web-site.xml. Modify any of these XML files in the Advanced Properties page off of the OC4J Home Page.
Other XML configuration files can be modified in other areas of the Oracle9iAS Console.
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, the security XML file and oc4j-connectors.xml. To modify these XML files, select Applications off of the OC4J Home Page. On the Applications page, select default. 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, orion-application.xml, and security XML files. To modify these files, drill down to the specific application from the Deployed Applications section on the Applications page. On the specified 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.
For an overview of 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.
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 Oracle Application Server 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 on the Administration page—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.
Off the default application page—You can either modify or add a data source either through a GUI or by directly accessing the data-sources.xml file.
Select Applications off of the OC4J Home Page.
On the Applications page, select default next to the Default Application Name.
On the default application page, scroll down to the Administration section and do one of the following:
Select Data Sources under the Resources column. This allows you to add or modify a data source using a GUI form.
Select Advanced Properties under the 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 drill down to the particular application to which this data source is local. 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".
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-7 shows the General section.
Figure 3-7 General Section of Data Source Definition
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.DriverManagerDataSource, that the data source is instantiated as.
JDBC URL—The URL to the database service 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:<service_name>.
JDBC Driver—The JDBC driver to use. One example of a JDBC driver is oracle.jdbc.driver.OracleDriver.
Schema—This is an optional parameter. Input the file name that contains the Java to database mappings for a particular database.
Figure 3-8 shows the username and password.
Username/Password—The username and password used to authenticate to the database that this data source represents. The password can either be entered as clear text, or you can provide a username for an indirect password. For details, see the Oracle Application Server Containers for J2EE Services Guide.
Figure 3-9 shows the JNDI Locations section.
The JNDI Locations section enables you to define the JNDI location string that the data source is bound with. This JNDI location is used within the JNDI lookup for retrieving this data source.
Figure 3-10 shows the Connection Attributes section.
This section enables you to modify connection tuning parameters, including the retry interval, pooling parameters, timeout parameters, and maximum attempt parameter.
Figure 3-11 shows the Properties section for the data source.
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.
The user manager, employing the user name and password, verifies the user's identity based on information in the user repository. The user manager defines what type of authentication you will be using. It contains your definitions for users, groups, or roles. The default user manager is the JAZNUserManager. You can define a user manager for all applications or for specific applications.
See the Oracle Application Server Containers for J2EE Security Guide for a full description of OC4J security, including user managers.
JMS can be configured either within the JMS section or directly within the jms.xml file.
To add Oracle JMS or third-party JMS providers, select JMS Providers under the Application Defaults column on the Administration page. This brings you to the following page:
Click the Add new JMS Provider button to configure each JMS provider, which brings up the following page:
This page enables you to configure either Oracle JMS or a third-party JMS provider. OracleAS JMS is always provided and preconfigured, except for the topics and queues, with the OC4J installation.
Once you choose the type of JMS provider, you must provide the following:
Oracle JMS: Provide the data source name and JNDI location for the database where Oracle JMS is installed and configured.
Third-party JMS provider: Provide the name, JNDI initial context factory class, and JNDI URL for the third-party provider. To add JNDI properties for this JMS provider, such as java.naming.factory.initial and java.naming.provider.url, click Add a property. A row is added where you can add the name for each JNDI property and its value.
This only configures the providers; it does not configure the Destination objects (topic, queue, and subscription). See the Oracle Application Server Containers for J2EE Services Guide or more information on JMS providers.
To configure a JMS provider that is only for a specific application, select the application from the Applications page, scroll down to the Resources column, and select JMS Providers. The screens that appear are the same as for the default JMS provider.
To add queues and topics for OracleAS JMS, you can edit the jms.xml file directly as follows: select the Advanced Server Properties section under the Instance Properties column on the Administration page. In this section, choose jms.xml to modify the straight XML file. See the Oracle Application Server Containers for J2EE Services Guide or descriptions of the elements in the jms.xml file.
To configure Web parameters that apply to all deployed Web applications, select Global Web Module in the Application Defaults column on the Administration page. This brings you to the following page:
The type of parameters that you can define for Web modules concern mappings, filtering, chaining, environment, and security. 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 Oracle Application Server 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.
RMI can only be defined within an XML definition. To edit the rmi.xml file, select Advanced Properties under the Instance Properties column on the Administration page. In this section, choose rmi.xml to modify the XML file. See the Oracle Application Server Containers for J2EE Services Guide for descriptions of the elements in the rmi.xml file.
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 Applications 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 the Distributed Configuration Management Administrator's Guide for directions. |
Once you have deployed your application, you can modify most of the parameters for this application. To configure application-specific parameters, do the following:
On the OC4J Home Page, select the Applications page.
Select the application where you want to change the configuration using one of the following methods:
Click the Select radio button for the application and click the Edit button.
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:
If you drill down to the application, scroll down to the Properties column 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
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.
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:
From the application screen, select the JAR or WAR file whose configuration you are interested in modifying. The application screen is shown.
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.
This section contains the following topics:
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-15 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-15 OC4J and J2EE Application Files
|
Note: Each deployed application uses anapplication.xml as its standard J2EE application descriptor 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 |
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 |
default-web-site.xml |
OC4J Web site definition. |
mod_oc4j.conf |
The |
application.xml orion-application.xml |
J2EE application standard J2EE application descriptor file and configuration files.
|
global-web-application.xml web.xml orion-web.xml |
J2EE Web application configuration files.
The |
ejb-jar.xml orion-ejb-jar.xml |
J2EE EJB application configuration files. The |
application-client.xml orion-application-client.xml |
J2EE client application configuration files. |
oc4j-connectors.xml ra.xml oc4j-ra.xml |
Connector configuration files.
|
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-17).
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, including the default-web-site.xml file.
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-15
The location of each application.xml file for each J2EE application that has been deployed in OC4J
default-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-16 shows the XML files that can be referenced in the server.xml file:
Figure 3-16 XML Files Referenced Within server.xml
Figure 3-17 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-17 Server.xml File and Related XML Files
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. |
If you have libraries that you want to share among applications, add a <library> element in the global application.xml file, indicating the directory where you are placing the libraries, as follows:
Windows:
<library path="d:\oc4j\j2ee\home\applib\"/>
UNIX:
<library path="/private/oc4j/j2ee/home/applib/"/>
For each directory to be included, use a separate <library> element on a separate line, as follows:
<library path="/private/oc4j/j2ee/home/applib/"/> <library path="/private/oc4j/j2ee/home/mylibrary/"/>
As a default, a <library> element exists in the global application.xml file with the j2ee/home/applib directory. Instead of modifying the <library> element to contain other directories, you could move your libraries into the applib directory. However, note that adding libraries to this directory increases the size of OC4J and effects the performance as all libraries are searched for unknown classes. Use this with discretion.
|
Note: The defaultj2ee/home/applib directory is not created when OC4J is installed. If you want to add shared libraries to this directory, you must first create it before adding your libraries.
|
If you can, you should keep your shared libraries local to the application through the orion-application.xml file deployed with the application. You can add <library> elements in the orion-application.xml file for the application to indicate where the libraries are located, which are used only within the application.
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.
All HTTP requests, whether through OHS or directly to OC4J, must have a listener configured in an OC4J Web site. You can have multiple Web sites for each OC4J instance, one for each protocol type. 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 Oracle Application Server. 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 Oracle 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 - as in an OC4J standalone environment - use the port number defined in this file.
Be aware that 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 8888. The following shows the entry in the http-web-site.xml for an HTTP listener with a port number of 8888:
<web-site host="oc4j_host" port="8888" 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. |
The RMI protocol listener is set up by OPMN 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. OPMN designates a range of ports that the RMI listener could be using. When you use the "opmn:ormi://" string in the lookup, the client retrieves automatically the assigned RMI port. See Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for more.
In the OC4J 10.1.2 implementation, there is new functionality in Web site XML files to disable OC4J access logging (used to log requests to the Web site) on a per-module basis.
In general, text-based access logging is enabled for a Web site through the <access-log> subelement of the <web-site> element in the Web site XML file (such as default-web-site.xml or http-web-site.xml). Alternatively, Oracle Diagnostic Logging ("ODL-based access logging") is enabled for a Web site through the <odl-access-log> subelement of the <web-site> element.
As of the 10.1.2 release, you can disable text-based logging or ODL-based logging (as applicable) for a particular Web application (module) through the new access-log attribute of the <web-app> element for that Web application. The <web-app> element is another subelement of <web-site>. A setting of access-log="false" for a Web application overrides any <access-log> or <odl-access-log> element to disable logging during the operation of that Web application.
The following example disables logging for the dms0 module of the default application, but leaves text-based logging enabled for the admin_web module:
<web-site ... > ... <web-app application="default" name="dms0" root="/dms0" access-log="false" /> <web-app application="default" name="admin_web" root="/adminoc4j" /> <access-log path="../log/http-web-access.log" /> ... </web-site>
|
Notes: The default setting is access-log="true". With this setting, functionality is the same as for previous releases, with logging being determined solely through the presence or absence of an <access-log> or <odl-access-log> element.If there is no <access-log> or <odl-access-log> element in a Web site XML file, then logging is disabled anyway and access-log="false" for an application has no additional effect. |
See the 10.1.2 release of the Oracle Application Server Containers for J2EE Servlet Developer's Guide for related information about access logging.
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.
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 themod_oc4j.conf file to be the OC4J instance.
|
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
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 Administrator's Guide for complete details on the mod_oc4j module configuration.
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-18, changes. This is the directory that server.xml knows as the "master" location.
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-18 displays the necessary directory structure.
Figure 3-18 Development Application Directory Structure
To deploy EJB or complex J2EE applications in an expanded directory format, complete the following steps:
Place the files in any directory. Figure 3-18 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:
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-18 demonstrates these directory names by <ejb_module>/, <web_module>/, <client_module>/, and <connector_module>/.
Place the classes for each module within the appropriate directory structure that maps to their package structure.
Modify the server.xml, application.xml, and *-web-site.xml files. The server.xml and *-web-site.xml files are located in j2ee/home/config directory, while the application.xml is under j2ee/home/applications/<appname>/META-INF directory. Modify these 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-18, 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-18, 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-18, if <appname> is "myapp", then the relative path is as follows:
<application_name="myapp" path="../applications/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-18 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-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. |
Add mount points for the Web application in the mod_oc4j.conf configuration file. Based on the root="/myapp" in this example, the mod_oc4j.conf should be updated to contain the following lines:
Oc4jMount /myapp home Oc4jMount /myapp/* home
You can develop classes that are called after OC4J initializes or before OC4J terminates. Startup classes can start services and perform functions after OC4J initiates; shutdown classes can terminate these services and perform functions before OC4J terminates. The oc4j.jar must be in the Java CLASSPATH when you compile these classes.
OC4J deploys and executes the OC4J startup and shutdown classes based on configuration of these classes in the server.xml file.
Startup classes are executed only once after OC4J initializes. They are not re-executed every time the server.xml file is touched. Your startup class implements the com.evermind.server.OC4JStartup interface that contains two methods—preDeploy and postDeploy—in which you can implement code for starting services or performing other initialization routines.
The preDeploy method executes before any OC4J application initialization.
The postDeploy method executes after all OC4J applications initialize.
Each method requires two arguments—a Hashtable that is populated from the configuration and a JNDI Context to which you can bind to process values contained within the Context. Both methods return a String, which is currently ignored.
Once created, you must configure the startup class within the <startup-classes> element in the server.xml file. You access this file by selecting Advanced Properties on the OC4J home page. Each OC4JStartup class is defined in a single <startup-class> element within the <startup-classes> element. Each <startup-class> defines the following:
The name of the class that implements the com.evermind.server.OC4JStartup interface.
Whether a failure is fatal. If considered fatal, then when an exception is thrown, OC4J logs the exception and exits. If not considered fatal, then OC4J logs the exception and continues. Default is not fatal.
The order of execution where each startup class receives an integer number that designates in what order the classes are executed.
The initialization parameters that contain key-value pairs, of type String, which OC4J takes, which are provided within the input Hashtable argument. The names for the key-value pairs must be unique, as JNDI is used to bind each value to its name.
In the <init-library path="../[xxx]" /> element in the server.xml file, configure the directory where the startup class resides, or the directory and JAR filename where the class is archived. The path attribute can be fully-qualified or relative to j2ee/home/config.
Example 3-1 Startup Class Example
The configuration for the TestStartup class is contained within a <startup-class> element in the server.xml file. The configuration defines the following:
The failure-is-fatal attribute is true, so that an exception causes OC4J to exit.
The execution-order is 0, so that this is the first startup class to execute.
Two initialization key-value pairs defined, of type String, which will be populated in the Hashtable, of the following:
"oracle.test.startup" "true" "startup.oracle.year" "2002"
|
Note: The names of the key-value pairs must be unique in all startup and shutdown classes, as JNDI binds the name to its value. |
Thus, configure the following in the server.xml file to define the TestStartup class:
<startup-classes>
<startup-class classname="TestStartup" failure-is-fatal="true">
<execution-order>0</execution-order>
<init-param>
<param-name>oracle.test.startup</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>startup.oracle.year</param-name>
<param-value>2002</param-value>
</init-param>
</startup-class>
</startup-classes>
The container provides the two initialization kay-value pairs within the input Hashtable parameter to the startup class.
The following example shows TestStartup, which implements the com.evermind.server.OC4JStartup interface. The preDeploy method retrieves the key-value pairs from the Hashtable and prints them out. The postDeploy method is a null method. The oc4j.jar must be in the Java CLASSPATH when you compile TestStartup.
import com.evermind.server.OC4JStartup;
import javax.naming.*;
import java.util.*;
public class TestStartup implements OC4JStartup {
public String preDeploy(Hashtable args, Context context) throws Exception {
// bind each argument using its name
Enumeration keys = args.keys();
while(keys.hasMoreElements()) {
String key = (String)keys.nextElement();
String value = (String)args.get(key);
System.out.println("prop: " + key + " value: " + args.get(key));
context.bind(key, value);
}
return "ok";
}
public String postDeploy(Hashtable args, Context context) throws Exception {
return null;
}
}
Assuming that the TestStartup class is archived in "../app1/startup.jar", modify the <init-library> element in the server.xml file as follows:
<init-library path="../app1/startup.jar" />
When you start OC4J, the preDeploy method is executed before any application is initialized. OC4J populates the JNDI context with the values from the Hashtable. If TestStartup throws an exception, then OC4J exits since the failure-is-fatal attribute was set to TRUE.
Shutdown classes are executed before OC4J terminates. Your shutdown class implements the com.evermind.server.OC4JShutdown interface that contains two methods—preUndeploy and postUndeploy—in which you can implement code for shutting down services or perform other termination routines.
The preUndeploy method executes before any OC4J application terminates.
The postUndeploy method executes after all OC4J applications terminates.
Each method requires two arguments—a Hashtable that is populated from the configuration and a JNDI Context to which you can bind to process values contained within the Context.
The implementation and configuration is identical to the shutdown classes as described in "OC4J Startup Classes" with the exception that the configuration is defined within the <shutdown-classes> and <shutdown-class> elements and there is no failure-is-fatal attribute. Thus, the configuration for a TestShutdown class would be as follows:
<shutdown-classes>
<shutdown-class classname="TestShutdown">
<execution-order>0</execution-order>
<init-param>
<param-name>oracle.test.shutdown</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>shutdown.oracle.year</param-name>
<param-value>2002</param-value>
</init-param>
</shutdown-class>
</shutdown-classes>
Assuming that the TestShutdown class is archived in "../app1/shutdown.jar", add another <init-library> element in the server.xml file as follows:
<init-library path="../app1/shutdown.jar" />
Be aware of the following issues when developing startup/shutdown classes:
You should separate your shutdown class from any archive files (WAR and EAR) that will be undeployed before shutdown.
OC4J creates an instance of your startup class and an instance of your shutdown class. These are separate instances. If you implement the startup and shutdown interfaces in the same class, OC4J creates two instances of that class. In this case, you cannot share non static fields between your startup class and your shutdown class.
Most performance settings are discussed in the Oracle Application Server Performance Guide.
You can manage these performance settings yourself from either the OC4J command-line option or by editing the appropriate XML file element.
Each -D command-line option, except for the dedicated.rmicontext option, defaults to the recommended setting. However, you can modify these options by providing each -D command-line option as an OC4J option. See the"OC4J Command-Line Options and System Properties" for an example.
dedicated.rmicontext=true/false. The default value is false. This replaces the deprecated dedicated.connection setting. When two or more clients in the same process retrieve an InitialContext, OC4J returns a cached context. Thus, each client receives the same InitialContext, which is assigned to the process. Server lookup, which results in server load balancing, happens only if the client retrieves its own InitialContext. If you set dedicated.rmicontext=true, then each client receives its own InitialContext instead of a shared context. When each client has its own InitialContext, then the clients can be load balanced.
This parameter is for the client. You can also set this in the JNDI properties.
oracle.dms.sensors=[none, normal, heavy, all]. You can set the value for Oracle9iAS built-in performance metrics to the following: None (off), normal (medium amount of metrics), heavy (high number of metrics), or all (all possible metrics). The default is normal.This parameter should be set on the OC4J server. The previous method for turning on these performance metrics, oracle.dms.gate=true/false, is replaced by the oracle.dms.sensors variable. However, if you still use oracle.dms.gate, then setting this variable to false is equivalent to setting oracle.dms.sensors=none.
DefineColumnType=true/false. The default is false. Set this to true if you are using an Oracle JDBC driver that is prior to 9.2. For these drivers, setting this variable to true avoids a round-trip when executing a select over the Oracle JDBC driver. This parameter should be set on the OC4J server.
When you change the value of this option and restart OC4J, it is only valid for applications deployed after the change. Any applications deployed before the change are not affected.
When true, the DefineColumnType extension saves a round trip to the database that would otherwise be necessary to describe the table. When the Oracle JDBC driver performs a query, it first uses a round trip to a database to determine the types that it should use for the columns of the result set. Then, when JDBC receives data from the query, it converts the data, as necessary, as it populates the result set. When you specify column types for a query with the DefineColumnType extension set to true, you avoid the first round trip to the Oracle database. The server, which is optimized to do so, performs any necessary type conversions.
Thread pools create and maintain a "queue" of threads for use by an OC4J process. Re-using existing threads rather than creating new threads on demand improves performance and reduces the burden on the JVM and underlying operating system.
By default, a single thread pool is created at OC4J startup. New threads are created and added to the pool on an as-needed basis. As each thread is released, it is returned to the pool to wait until it is needed by a new request.
Threads in the pool are automatically destroyed after 10 minutes of inactivity. There is no limit on the number of threads that can be created in this configuration.
The default configuration should by sufficient for most OC4J usage scenarios. However, you can optionally modify the single thread pool created by default through the min, max, queue, and keepAlive attributes of the <global-thread-pool> element in the server.xml file.
Alternatively, you can create two thread pools using <global-thread-pool>, with different types of threads divided among the pools:
The worker thread pool contains worker threads used in processing RMI, HTTP and AJP requests, as well as MDB listener threads. These threads are process-intensive and use database resources.
The connection thread pool contains threads such as listener threads, JDBC connection threads, RMI server and HTTP server connection threads, and background threads. These threads are typically not process intensive.
To create two pools, you must configure the min, max, queue, and keepAlive attributes for the worker thread pool and the cx-min, cx-max, cx-queue, and cx-keepAlive attributes for the connection thread pool. All of these attributes must be configured if creating pools; otherwise you will see the following error message:
Error initializing server: Invalid Thread Pool parameter: null
See Table 3-2 for descriptions of the attributes of <global-thread-pool>.
The following example initializes two thread pools for the OC4J process. Each contains a minimum of 10 threads and maximum of 100 threads. The number of requests outstanding in each queue can be 200 requests. Also, idle threads are kept alive for 700 seconds. The thread pool information is printed at startup.
<application-server ...> ... <global-thread-pool min="10" max="100" queue="200" keepAlive="700000" cx-min="10" cx-max="100" cx-queue="200" cx-keepAlive="700000" debug="true"/> ... </application-server>
Table 3-2 below describes the attributes of the <global-thread-pool> element. Note that this element is not included in server.xml by default.
Table 3-2 Attributes of <global-thread-pool>
| Attribute | Description |
|---|---|
min |
The minimum number of threads to create in the pool. By default, a minimum number of threads are preallocated and placed in the thread pool when the container starts. If you add the |
max |
The maximum number of threads that can be created in the pool. New threads are spawned if the maximum size is not reached and if there are no idle threads. Idle threads are used first before a new thread is spawned. The default is |
queue |
The maximum number of requests that can be kept in the queue. The default is |
keepAlive |
The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to |
cx-min |
The minimum number of threads to create in the connection thread pool. The minimum value that can be specified is |
cx-max |
The maximum number of threads that can be created in the connection pool. The default is |
cx-queue |
The maximum number of threads that can be kept in the queue in the connection pool. The default is |
cx-keepAlive |
The length of time, in milliseconds, to keep a thread alive (idle) while waiting for a new request. After the timeout is reached, the thread is destroyed. To never destroy threads, set to |
debug |
If |
Additional notes on thread pool configuration:
The queue attributes should be at least twice the size of the maximum number of threads.
The minimum and maximum number of worker threads should be a multiple of the number of CPUs installed on your machine. However, this number should be small; the more threads you have, the more burden you put on the operating system and the garbage collector.
The cx-min and cx-max attributes are relative to the number of the physical connections you have at any point in time. The cx-queue handles bursts in connection traffic.
You can cache database statements, which prevents the overhead of repeated cursor creation and repeated statement parsing and creation. In the DataSource configuration, you enable JDBC statement caching, which caches executable statements that are used repeatedly. A JDBC statement cache is associated with a particular physical connection. See Oracle9i JDBC Developer's Guide and Reference for more information on statement caching.
You can dynamically enable and disable statement caching programmatically through the setStmtCacheSize() method of your connection object or through the stmt-cache-size XML attribute in the DataSource configuration. An integer value is expected with the size of the cache. The cache size you specify is the maximum number of statements in the cache. The user determines how many distinct statements the application issues to the database. Then, the user sets the size of the cache to this number.
If you do not specify this attribute or set it to zero, this cache is disabled.
The task manager is a background process that performs cleanup. However, the task manager can be expensive. You can manage when the task manager performs its duties through the taskmanager-granularity attribute in server.xml. This attribute sets how often the task manager is kicked off for cleanup. Value is in milliseconds. Default is 1000 milliseconds.
<application-server ... taskmanager-granularity="60000" ...>
OC4J logs messages both to standard error, standard out, and several log files for OC4J services and deployed applications.
Viewing OC4J System and Application Log Messages: This section describes the separate log files for OC4J sub-systems and deployed applications. You can manage how large these files can be and where they are located.
Redirecting Standard Out and Standard Error: This section describes how to forward standard out and standard error messages to a log file.
|
Note: Also, OC4J supports Jakartalog4j. See the "Open Source Frameworks and Utilities" appendix in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.
|
Each OC4J process included in the Oracle9iAS environment has a set of log files, as shown in Table 3-3. If there are multiple processes running for an OC4J instance, there is a multiple set of log files.
Table 3-3 List of Log Files Generated for OC4J
| Default Log File Name | Description | Scope | Configuration File |
|---|---|---|---|
application.log |
All events, errors, and exceptions for a deployed application. |
One log file for each application deployed. |
orion-application. xml |
global-application .log |
All common events, errors, and exceptions related to applications. |
All applications, including the default application. |
application.xml |
jms.log |
All JMS events and errors. |
JMS sub-system |
jms.xml |
rmi.log |
All RMI events and errors. |
RMI sub-system |
rmi.xml |
server.log |
All events not associated with a particular sub-system or an application. This logs history of server startup, shutdown internal server errors. |
server-wide |
server.xml |
web-access.log |
Logs all accesses to the Web site. |
Each Web site |
default-web-site.xml |
There are two types of log files:
Oracle Diagnostic Logging (ODL) Log Files: The messages logged in these files use an XML format that is read by the Enterprise Manager GUI. We recommend that you use this format for your logging, even though it is not the default, when you are using OC4J within Oracle9iAS.
Text Log Files: The messages logged in these files are not in XML and are simply for reading within any editor. This is the default. Normally, those who use OC4J standalone would benefit from viewing their log messages in a text format.
The ODL log entries are each written out in XML format in its respective log file. Each XML message can be read through the Enterprise Manager GUI or through your own XML reader. The advantages for ODL logging is that the log files and the directory have a maximum limit. When the limit is reached, the log files are overwritten.
When you enable ODL logging, each new message goes into the current log file, named log.xml. When the log file is full—that is, the log file size maximum is reached—then it is copied to an archival log file, named logN.xml, where N is a number starting at one. When the last log file is full, the following occurs:
The least recent log file is erased to provide space in the directory.
The log.xml file is written to the latest logN.xml file, where N increments by one over the most recent log file.
Thus, your log files are constantly rolling over and do not encroach on your disk space.
Within each XML file listed in Table 3-3, you enable ODL logging by either un-commenting an existing ODL configuration line or adding the ODL configuration line into the XML file, as follows:
Add or un-comment the <odl> element within the <log> element in all XML files listed in Table 3-3, except for the default-web-site.xml file.
Add the <odl-access-log> element in the default-web-site.xml file.
The attributes that you can configure are:
path: Path and folder name of the log folder for this area. You can use an absolute path or a path relative to where the configuration XML file exists, which is normally in the j2ee/home/config directory. This denotes where the log files will reside for the feature that the XML configuration file is concerned with. For example, modifying this element in the server.xml file denotes where the server log files are written.
max-file-size: The maximum size in KB of each individual log file.
max-directory-size: The maximum size of the directory in KB.
New files are created within the directory, until the maximum directory size is reached. Each log file is equal to or less than the maximum specified in the attributes.
Thus, to specify log files of 1000 KB and a maximum of 10,000 KB for the directory in the ORACLE_HOME/j2ee/log/server directory in the server.xml file, configure the following:
<log> <odl path="../log/server/" max-file-size="1000" max-directory-size="10000" /> </log>
When OC4J is executing, all log messages that are server oriented are logged in the ORACLE_HOME/j2ee/log/server directory.
The XML message that is logged is of the following format:
<MESSAGE> <HEADER> <TSTZ_ORIGINATING>2002-11-12T15:02:07.051-08:00</TSTZ_ORIGINATING> <COMPONENT_ID>oc4j</COMPONENT_ID> <MSG_TYPE TYPE="ERROR"></MSG_TYPE> <MSG_LEVEL>1</MSG_LEVEL> <HOST_ID>myhost</HOST_ID> <HOST_NWADDR>001.11.22.33</HOST_NWADDR> <PROCESS_ID>null-Thread[Orion Launcher,5,main]</PROCESS_ID> <USER_ID>dpda</USER_ID> </HEADER> <PAYLOAD> <MSG_TEXT>java.lang.NullPointerException at com.evermind.server.ApplicationServer.setConfig(ApplicationServer.java:1070) at com.evermind.server.ApplicationServerLauncher.run (ApplicationServerLauncher.java:93) at java.lang.Thread.run(Unknown Source) </MSG_TEXT> </PAYLOAD> </MESSAGE/>
You can have both the ODL and text logging turned on. To save on disk space, you should turn off one of these options. If you decide to enable ODL logging, turn off the text logging functionality by commenting out the <file> subelement of the <log> element for all XML files except the default-web-site.xml file. For the default-web-site.xml file, turn off the text logging by commenting out the <access-log> element.
You can view ODL log files by performing the following:
At the bottom of the Oracle Application Server Instance Home page, select Logs.
Select the OC4J Instances for which you want to view the log files.
Select the OC4J Instances in the Available Components column.
Select Move to transfer your select to the Selected Components column.
Select Search to view the log files for these OC4J Instances.
Full text logging is still available in OC4J. Primarily, you should use text logging within OC4J standalone. It is easier to read within any editor, as it is not in XML format.
The text logging facility separates messages out in alignment with the XML files. However, instead of writing to multiple log files of the same size, all messages for that component are written into a single file. The text logging does not have any imposed limits or log rollover. Instead, the log files will continue to grow, unless you stop OC4J, remove the file, and restart OC4J to start the log files over. You can overrun your disk space if you do not monitor your log files. This is only feasible in a standalone, development environment.
Text messaging is the default and is configured in the same XML files as listed for ODL logging in Table 3-3. Text messaging is enabled in the <file> subelement the <log> element of the XML files, except the default-web-site.xml file. For the default-web-site.xml file, the text messaging is enabled with the <access-log> element. To turn off text messaging, eliminate or comment out the <file> or <access-log> element. If you do not remove this line and enable ODL logging, you will have both logging facilities turned on. The location and filename for text messaging does have defaults, as shown in Table 3-4, but you can specify the location and filename within the path attribute of the <log> or <access-log> elements.
The following table shows the default location directory for text messaging log files of an OC4J process.
Table 3-4 OC4J Log File Locations
The location of all of the above log files can be specified, except the web-access.log file, using the <log> element in the respective configuration files. You can specify either absolute paths or paths relative to the j2ee/home/config directory. For example, specify the server log file in the server.xml configuration file, as follows:
<log> <file path="../log/my-server.log" /> </log>
You can also specify an absolute path for the location of the log file, as follows:
<log> <file path="d:\log-files\my-server.log" /> </log>
In an Oracle Application Server environment, the standard output and standard errors for OC4J are routed to the OPMN log for the OC4J instance. For example, if you have an OC4J instance called OC4J_Demos, and it has an island called default_island, and there is only one process in the island, the file that will contain the STDOUT and STDERR streams is $ORACLE_HOME/opmn/logs/OC4J_Demos.default_island.1
Figure 3-20 shows how you specify the -out and -err parameters in the OC4J command-line options for your OC4J instance. When you specify these parameters without specifying a specific directory, the log files are created in the $J2EE_HOME/<OC4JInstanceName>_<IslandName>_<Process#> file. For example, if you have an OC4J instance called OC4J_Demos and it has an island called default_island, then the log file will be created in the $J2EE_HOME/OC4J_Demos_default_island_1.
|
Note: In the preceding examples, it is assumed that there is only one OC4J process for the default island. If there are more processes for an island there are separate log files for each OC4J process. |
In the Application Server Control, select Server Properties on the Administration page, which will bring you to the screen in Figure 3-20.
Figure 3-20 EM Console to Modify Server Properties for an OC4J Instance
OC4J properties are configuration switches that can be set on the command-line. As shown in Figure 3-20, the properties are prefaced with a -D in the Java Options line. OC4J provides several debug properties for generating additional information on the operations performed by the various sub-systems of OC4J. These debug properties can be set for a particular sub-system while starting up OC4J.
|
Note: Turning on excessive debug options can slow down the execution of your applications and use large amounts of disk space with the contents of the log files. |
OC4J is started and managed by OPMN. You have to specify the Java system properties for your OC4J instance using Enterprise Manager as shown in Figure 3-20. The supplied properties are saved in the OPMN configuration file. OPMN starts OC4J with these supplied properties when you shutdown and restart your OC4J Instance. See "OC4J Command-Line Options and System Properties" for OC4J general properties.
By default, the debug information is written to the OPMN log file for the OC4J Instance, which resides in the $ORACLE_HOME/opmn/logs/ directory. For example, you have a OC4J instance named OC4J_DEMOS and there is only one island and the island has only process for this OC4J instance, then the debug information is logged in $ORACLE_HOME/opmn/logs/OC4J_Demos.default_island.1. However, if there is -out and -err command-line options specified with OC4J, then the debug information is redirected to the appropriate files.
The following tables provide useful debug options that available with OC4J. These debug options have two states either true or false. By default these are set to false. For a complete list of debug properties, see "OC4J Command-Line Options and System Properties".
Table 3-5 HTTP Debugging Options
Table 3-6 JDBC Debugging Options
| JDBC Debugging | Description of Option |
|---|---|
datasource.verbose |
Provides verbose information on creation of data source and connections using Data Sources and connections released to the pool, and so on, |
jdbc.debug |
Provides very verbose information when JDBC calls are made |
Table 3-7 EJB Debugging Options
| EJB Debugging | Description of Options |
|---|---|
ejb.cluster.debug |
Turns on EJB clustering debug messages |
Table 3-8 RMI Debugging Options
| RMI Debugging | Description of Options |
|---|---|
rmi.debug |
Prints RMI debug information |
rmi.verbose |
Provides very verbose information on RMI calls |
Table 3-9 Web Services Debugging Options
| Web Services Debugging | Description of Options |
|---|---|
ws.debug |
Turns on Web Services debugging |
In addition to the specific sub-system switches, you can also start OC4J with a supplied verbosity level. The verbosity level is an integer between 1 and 10. The higher the verbosity level, the more information that is printed in the console. You specify the verbosity level with the -verbosity OC4J option in the Enterprise Manager in the OC4J command-line options section. The following examples show the output with and without verbosity:
Example 3-3 Error Messages Displayed Without Verbosity
D:\oc4j903\j2ee\home>java -jar oc4j.jar Oracle Application Server Containers for J2EE initialized
Example 3-4 Error Messages Displayed With Verbosity Level of 10
D:\oc4j903\j2ee\home>java -jar oc4j.jar -verbosity 10 Application default (default) initialized... Binding EJB work.ejb.WorkHours to work.ejb.WorkHours... Application work (work) initialized... Application serv23 (Servlet 2.3 New Features Demo) initialized... Web-App default:defaultWebApp (0.0.0.0/0.0.0.0:8888) started... Oracle Application Server Containers for J2EE initialized
You deployed a Web application to OC4J that is having some problems with servlets. You are losing the client session when you use a pre-configured data source to make database connection. You want to know what OC4J is doing when the servlet is accessing the data source. In order to generate the debug information on HTTP Session and data source usage, you must set two debug options - http.session.debug and datasource.verbose to true.
Perform the following tasks
Logon to Enterprise Manager console as administrator.
Drill down to the OC4J Instance.
Select Server Properties for the OC4J Instance.
Enter Java Options as follows: -Dhttp.session.debug=true -Ddatasource.verbose=true
Restart the OC4J instance.
After the OC4J Instance is restarted, you re-execute your servlet and see the following type of debug information in the standard output for the OC4J Instance:
DataSource logwriter activated... jdbc:oracle:thin:@localhost:1521/DEBU: Started jdbc:oracle:thin:@localhost:1521/DEBU: Started Oracle Application Server Containers for J2EE initialized Created session with id '4fa5eb1b9a564869a426e8544963754f' at Tue APR 23 16:22:56 PDT 2002, secure-only: false Created new physical connection: XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521/DEBU null: Connection XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521/DEBU allocated (Pool size: 0) jdbc:oracle:thin:@localhost:1521/DEBU: Opened connection Created new physical connection: Pooled oracle.jdbc.driver.OracleConnection@5f18 Pooled jdbc:oracle:thin:@localhost:1521/DEBU: Connection Pooled oracle.jdbc.driver.OracleConnection@5f1832 allocated (Pool size: 0) Pooled jdbc:oracle:thin:@localhost:1521/DEBU: Releasing connection Pooled oracle.jdbc.driver.OracleConnection@5f1832 to pool (Pool size: 1) null: Releasing connection XA XA Orion Pooled jdbc:oracle:thin:@localhost:1521/DEBU to pool (Pool size: 1) Orion Pooled jdbc:oracle:thin:@localhost:1521/DEBU: Cache timeout, closing connection (Pool size: 0) com.evermind.sql.OrionCMTDataSource/default/jdbc/OracleDS: Cache timeout, closing connection (Pool size: 0)
You can remotely debug your applications deployed in OC4J using any Java debugging facility that supports the JPDA (Java Platform Debugging Architecture). With OC4J embedded directly inside of the Oracle JDeveloper IDE, debugging both locally deployed and remote J2EE applications is simple. For more details, please see the Oracle JDeveloper documentation or read the "Remote Debugging How-To" document that is posted on OTN.
