Oracle® Application Server Containers for J2EE Standalone User's Guide
10g Release 2 (10.1.2) Part No. B14361-02 |
|
Previous |
Next |
This chapter provides information for administering OC4J in standalone mode for development purposes. Chapter 1, "Configuration and Deployment", discusses the easiest method for configuring, developing, and deploying a J2EE application. However, if you want to use other services, such as JMS, you must know how to manipulate the XML configuration files.
This chapter discusses the following topics:
This section contains the following topics:
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
Note: Each deployed application uses anapplication.xml as the standard J2EE application descriptor file. That XML file is local to the application and separate from the application.xml that exists in the j2ee/home/config directory. The j2ee/home/config/application.xml file configures options that are applied to all applications deployed in this OC4J server instance.
|
Table 2-1 describes the role and function for each XML file that was displayed in the preceding figure.
Table 2-1 OC4J Features and Components
XML Configuration File | Features/Components |
---|---|
|
OC4J overall server configuration. Configures the server and points to the XML files that add to this file, such as |
|
OC4J security configuration for the type of security required for accessing the server. |
|
OC4J data source configuration for all databases used by applications within OC4J. |
|
OC4J RMI port configuration and RMI tunneling over HTTP. |
|
OC4J JMS configuration for |
*-web-site.xml |
OC4J Web site definition. Each Web site is defined within its own XML file. It is a good practice to name each XML file based on the root element name, |
|
J2EE application standard J2EE application descriptor file and configuration files.
|
|
J2EE Web application configuration files.
The |
|
J2EE EJB application configuration files. The |
|
J2EE client application configuration files. |
|
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 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
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
Other elements for server.xml
are described in "Elements in the server.xml File".
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.
When you are in a development environment, it is easier to modify XML files than to use the admin.jar command for each iteration of development. The following sections help you understand how to modify your XML configuration files:
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" >
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. |
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 Development Application Directory Structure, 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 2-4 displays the necessary directory structure.
Figure 2-4 Development Application Directory Structure
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 2-4 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 2-4 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 2-4, 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 2-4, 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 2-4, 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 2-4 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 an EAR file. During execution, the entire EAR file is loaded into memory and indexed. This is faster than reading in each class from the development directory when necessary. |
OC4J automatically deploys an application if the timestamp on an EAR file has changed. Restarting OC4J to deploy or redeploy applications is not necessary. Automatic deployment is not enabled in all cases, but deployment occurs in the following cases:
changes to EAR files are checked
If you change the EAR file, OC4J automatically detects the change. OC4J detects the timestamp change and redeploys the application.
change in timestamp of certain XML files in the exploded directory format (The appname
directory) that is discussed in "Building and Deploying Within a Directory". For automatic deployment of exploded directory applications, you must do the following:
Modify the classes in the <module>
and touch its J2EE deployment descriptor to change the timestamp on the XML file. For example, if you modify servlet classes, you must touch its web.xml
file. This notifies OC4J that changes occurred in this <module>
.
Touch the application.xml
of this application. Changing the timestamp of the application.xml
starts the automatic deployment. Once started, OC4J checks which modules to redeploy by noticing which module deployment descriptors have timestamp changes.
When OC4J does not check for updates, redeploy by either using the admin.jar
command-line tool or restarting the OC4J server manually. See "Options for the OC4J Administration Management JAR" for a description of the -deploy
option.
Whenever you deploy an application, OC4J automatically generates the OC4J-specific XML files with the default elements. If you want to change these files or add to the existing XML files, you must copy the XML files to where your original development directory for the application and change it in this location. If you change the XML file within the deployed location, OC4J simply overwrites these changes when the application is deployed again. The changes only stay constant when changed in the development directories.
For all OC4J-specific XML files, you can add these files within the recommended development structure as shown in Figure 2-5.
Figure 2-5 Development Application Directory Structure
A child application can see the namespace of its parent application. Thus, setting up an application as a parent is used to share services among children. The default parent is the global application.
To set up an application as a parent of another, you can do one of the following:
Use the -parent
option of the admin.jar
command when deploying the originating application. This option allows you to designate what application will be the parent of the deploying application.
Specify the parent in the application definition line in the server.xml
file. Each application is defined by an <application>
element in the server.xml
file. In this element, a parent
attribute designates the parent application.
<application ... parent="applicationWithCommonClasses" .../>
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 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
.
Example 2-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" />
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 "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.
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.
Table 2-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 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" ...>
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 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.
Table 2-3 List of Log Files Generated for OC4J
Default Log File Name | Description | Scope | Configuration File |
---|---|---|---|
|
All events, errors, and exceptions for a deployed application. |
One log file for each application deployed. |
|
|
All common events, errors, and exceptions related to applications. |
All applications, including the default application. |
|
|
All JMS events and errors. |
JMS sub-system |
|
|
All RMI events and errors. |
RMI sub-system |
|
|
All events not associated with a particular sub-system or an application. This logs history of server startup, shutdown internal server errors. |
server-wide |
|
|
Logs all accesses to the Web site. |
Each Web site |
|
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.
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 XML files in Table 2-3. Text messaging is enabled in the <file>
subelement the <log>
element of the XML files, except the http-web-site.xml
file. For the http-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 2-4, but you can specify the location and filename within the path attribute of the <log>
or <access-log>
elements.
Table 2-4 shows the default location for the log files for a standalone OC4J. You can modify the location and names of these files by modifying the configuration files described in Table 2-3.
Table 2-4 OC4J Standalone Log File Locations
Log File | Default Location |
---|---|
|
install_dir/j2ee/home/application-deployments/<application-name> |
|
install_dir/j2ee/home/log |
|
install_dir/j2ee/home/log |
|
install_dir/j2ee/home/log |
|
install_dir/j2ee/home/log |
|
The location is configurable from *-web-site.xml with the <access-log> element, as follows: <access-log path="../log/http-web-access.log" /> |
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>
The ODL log entries are each written out in XML format in its respective log file. Each XML message can be read 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 log
N
.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 log
N
.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 2-3, you enable ODL logging by uncommenting the ODL configuration line, as follows:
Uncomment the <odl>
element within the <log>
element in all XML files listed in Table 2-3, except for the http-web-site.xml
file.
Add the <odl-access-log>
element in the http-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 <install-dir>/j2ee/home/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 <install-dir>/j2ee/home/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 http-web-site.xml
file. For the http-web-site.xml
file, turn off the text logging by commenting out the <access-log>
element.
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.
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.
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. |
The following table provides useful debug options 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 System Properties".
Table 2-5 HTTP Debugging Options
HTTP Debugging | Description of Option |
---|---|
|
Provides information about HTTP session events |
Provides information about each HTTP request |
|
|
Prints all HTTP errors |
Default: false. If true, turns on the |
Table 2-6 JDBC Debugging Options
JDBC Debugging | Description of Option |
---|---|
|
Provides verbose information on creation of data source and connections using Data Sources and connections released to the pool, and so on, |
|
Provides very verbose information when JDBC calls are made |
Table 2-7 RMI Debugging Options
RMI Debugging | Description of Options |
---|---|
|
Prints RMI debug information |
|
Provides very verbose information on RMI calls |
Table 2-8 OracleAS Web Services Debugging Options
OracleAS Web Services Debugging | Description of Options |
---|---|
Turns on Web Services debugging |
For example, if you want to generate debug information on HTTP session events then you start OC4J, as follows:
java -Dhttp.session.debug=true -jar oc4j.jar
After OC4J is started with a specific debug option, debug information is generated and routed to standard output. In the above example, you would see HTTP session information on your OC4J console, as follows:
Oracle Application Server Containers for J2EE initialized Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon Apr 15 12:24:20 PDT 2002, secure-only: false Created session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:36:06 PDT 2002, secure-only: false Invalidating session with id '36c04d8a1cd64ef2b6a9ba6e2ac6637e' at Mon APR 15 12:44:32 PDT 2002 (created at Mon APR 15 12:24:23 PDT 2002) due to timeout
If you want to save this debug information, then you can redirect your standard output to a file using the -out
or -err
command-line options, as follows:
java -Dhttp.session.debug=true -jar oc4j.jar -out oc4j.out -err oc4j.err
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 OC4J command-line options. The following examples show the output with and without verbosity:
Example 2-3 Error Messages Displayed Without Veribosity
D:\oc4j903\j2ee\home>java -jar oc4j.jar Oracle Application Server Containers for J2EE initialized
Example 2-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.
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)