2 Advanced Configuration and Development

2.1.1 XML Configuration File Overview

Because OC4J is configured solely through XML files, you must understand the role and method for a set of XML files. Each XML file 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 2-1 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.

  OC4J server configuration files exist under the j2ee/home/config/ directory — 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.

• 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 2-1 OC4J and J2EE Application Files

Description of "Figure 2-1 OC4J and J2EE Application Files"

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

2.1.2 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 2-3).

Here are the interrelated files:

• server.xml—contains references to the following:

  • All *-web-site files for each Web site for this OC4J server, including the default http-web-site.xml file.

  • The location of each of the other OC4J server configuration files, except principals.xml, which is defined in the global application.xml, shown in Figure 2-1

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

• http-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 a reference to the principals.xml file.

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

Figure 2-2 XML Files Referenced Within server.xml

Description of "Figure 2-2 XML Files Referenced Within server.xml"

Figure 2-3 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> element denotes the name and location of the rmi.xml file.

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

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

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

• The <web-site> element 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. You can deploy applications through the admin.jar command using the -deploy option or by modifying the server.xml file directly. Each deployed application is denoted by the <application> element. See "Manually Adding Applications in a Development Environment" for more information on directly editing the server.xml file.

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

Description of "Figure 2-3 Server.xml File and Related XML Files"

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

2.3.1 Configuring a Listener

Each OC4J server is configured to listen on HTTP or RMI protocols for incoming requests. Each OC4J Web server is configured within its own *-web-site.xml file.

• HTTP protocol listener—HTTP clients can access an OC4J HTTP listener directly. This involves configuring an http-web-site.xml file, which indicates the HTTP listener port. 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="Default OC4J WebSite">
  
  

• RMI protocol listener—EJB clients and the OC4J tools, such as admin.jar, access the OC4J server through a configured RMI port. This involves configuring the rmi.xml file. The default RMI port is 23791. The following shows the default RMI port number configured in the rmi.xml file:

  <rmi-server port="23791" >
  

2.3.2 Configuring J2EE Applications

To configure and deploy your J2EE applications, modify the server.xml and http-web-site.xml files with your application information.

• In server.xml, add a new or modify the existing <application name=... path=... auto-start="true" /> entry for each application that you want automatically started when OC4J starts. The path points to either the location of the EAR file to be deployed or the exploded directory where the application has been built. See "Deployment In a Production Environment Using ADMIN.JAR" or "Building and Deploying Within a Directory" for more information.

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

  For Web application binding using a WAR file, add the following:

  <web-app application="myapp" name="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://oc4j_host:8888", then to initiate the application, point your browser at "http://oc4j_host:8888/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.

    
    

2.8.1 OC4J Startup Classes

Startup classes are executed only once after OC4J initializes. They are not re-executed everytime 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. 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.

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

2.8.2 OC4J Shutdown Classes

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

2.9.1 Performance Command-Line Options

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 "Standalone OC4J Command-Line Options and 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 Oracle Application Server 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.

2.9.2 Thread Pool Settings

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. Idle threads In the pool are used first before a new thread is spawned.

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 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 2-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 2-2 below describes the attributes of the <global-thread-pool> element. Note that this element is not included in server.xml by default.

min

max

queue

keepAlive

cx-min 

cx-max

cx-queue

cx-keepAlive

debug

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.

2.9.3 Statement Caching

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.

<data-source>
 ...
 stmt-cache-size="200"
</data-source> 

2.9.4 Task Manager Granularity

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 element sets how often the task manager is kicked off for cleanup. Value is in milliseconds. Default is 1000 milliseconds.

<application-server ...  taskmanager-granularity="60000" ...>

2.10.1 Viewing OC4J System and Application Log Messages

Each OC4J process has a set of log files, as shown in Table 2-3. If there are multiple processes running for an OC4J instance, there is a multiple set of log files.

There are two types of log files:

• Text Log Files: The messages logged in these files are text-based and not in XML format. You can read these messages with any editor. This is the default. Normally, those who use OC4J standalone would benefit from viewing their log messages in a text format.

• Oracle Diagnostic Logging (ODL) Log Files: The messages logged in these files use an XML format that can be read by a GUI tool, such as the Oracle Enterprise Manager 10g GUI. We recommend that you use this format for your logging when you are using OC4J within Oracle Application Server.

<log>
<file path="../log/my-server.log" />
</log>

<log>
<file path="d:\log-files\my-server.log" />
</log>

<log>
<odl path="../log/server/" max-file-size="1000" max-directory-size="10000" />
</log>

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

2.10.2 Redirecting Standard Out and Standard Error

Many developers use the System.out.println() and System.err.println() methods in their applications to generate debug information. Normally, the output from these method calls are printed to the console where the OC4J process is started. However, you can specify command-line options when starting OC4J to direct the STDOUT and STDERR output directly to files. The -out and -err parameters inform OC4J where to direct the error messages. The following startup command includes and example of the -out and -err parameters:

$ java -jar oc4j.jar -out d:\log-files\oc4j.out -err d:\log-files\oc4j.err 

In this case, all information written to STDOUT and STDERR is printed to the files d:\log-files\oc4j.out and d:\log-files\oc4j.err respectively.

2.10.3 Disabling Access Logging for a Web Application

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> 

See the 10.1.2 release of the Oracle Application Server Containers for J2EE Servlet Developer's Guide for related information about access logging.

2.11.1 Servlet Debugging Example

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.

java -Dhttp.session.debug=true -Ddatasource.verbose=true -jar oc4j.jar

Then, re-execute your servlet and see the following type of debug information in the standard output for the OC4J process:

DataSource logwriter activated... jdbc:oracle:thin:@localhost:1521/MYSERVICE:
Started 
jdbc:oracle:thin:@localhost:1521/MYSERVICE: 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 OC4J Pooled
jdbc:oracle:thin:@localhost:1521/MYSERVICE 
null: Connection XA XA OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE
allocated (Pool size: 0) 
jdbc:oracle:thin:@localhost:1521/MYSERVICE: Opened connection 
Created new physical connection: Pooled
oracle.jdbc.driver.OracleConnection@5f18 
Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Connection Pooled
oracle.jdbc.driver.OracleConnection@5f1832 allocated (Pool size: 0) 
Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Releasing connection Pooled 
oracle.jdbc.driver.OracleConnection@5f1832 to pool (Pool size: 1) 
null: Releasing connection XA XA OC4J Pooled
jdbc:oracle:thin:@localhost:1521/MYSERVICE to pool (Pool size: 1) 
OC4J Pooled jdbc:oracle:thin:@localhost:1521/MYSERVICE: Cache timeout, closing
connection (Pool size: 0) 
com.evermind.sql.OrionCMTDataSource/default/jdbc/OracleDS: Cache timeout,
closing connection (Pool size: 0)