Working with Configuration Files

OC4J Standalone is configured through a collection of files in the OC4J_HOME/j2ee/home/config directory. The root of these files is server.xml , which contains pointers to many of the other files as well as a number of server-level options (logging, transaction, timeout, deployment directories, and so on). Later in this chapter, we'll review each of these settings individually.

Configuring Application-level Resources

Some settings and resources can be configured both globally and on a per-application basis. OC4J handles this by arranging all of your applications in a hierarchy in which children inherit configuration details from parents. At the top of this tree is the global application, configured in j2ee/home/config/application.xml . This doesn't represent a real application (unless you go out of your way to configure it like one). It's just a convenient place to configure shared resources and default values. For example, if you would like all of your applications to have access to a shared Java library, you can configure a <library> entry inside application.xml .

Tip 

Don't confuse this global application.xml file with the application.xml deployment descriptor defined by the J2EE specification. The first is a global configuration file inside j2ee/home/config that contains OC4J-specific settings. The latter is found within the META-INF directory of each deployed application and it contains only standard J2EE elements.

Any settings or resources configured in j2ee/home/config/application.xml will be inherited by all other deployed applications. An individual application can override or add to these settings by including an orion-application.xml file within its META-INF directory. This file uses the same document type declaration (DTD) as j2ee/home/config/application.xml .

Chapter 9 will walk you through each of the settings available in these two files and will provide useful tips for organizing your application hierarchy.

Editing Configuration Files

All server configuration files can be edited directly in your favorite text or XML editor. However, changes will not take effect until OC4J is restarted. This is a good reason to define commonly changed elements at the application level instead of within the global application.xml file. For example, if you define your database settings in your application's orion-application.xml file, then you can change them by simply redeploying the application. However, if you define them at the global level (in j2ee/home/config/application.xml ), then any changes you make will necessitate a server restart.

Tip 

Once you've configured OC4J for the first time, check all modified configuration files into a version control system like Concurrent Versions Systems (CVS). This makes it easy to keep track of changes over time and revert to a known working configuration if problems occur. It also helps when following up on bug reports that may have already been fixed by configuration changes (since it helps you reconstruct the original setup).

Managing Multiple Configurations

In many cases, it can be useful to maintain several different server configurations, particularly when staging releases or testing against different databases. Unlike the full Oracle Application Server stack, OC4J Standalone doesn't explicitly support multiple instances. However, there are many ways you can manage this on your own.

Tip 

If you want to be able to run two server instances simultaneously , you'll need to change the default ports so that they don't conflict. See the "Configuring Ports" section later in this chapter.

Multiple OC4J Directory Trees

The easiest and most straightforward way is to duplicate the entire OC4J directory structure for each configuration. This makes sense in staging environments where you need to be able to test a configuration on its own and then take it live without changing any file references or startup scripts. However, it requires that you maintain separate copies of every configuration file and library, which is usually overkill if you just want to try out a few new settings or switch back and forth between databases.

Single OC4J Tree with Multiple Configuration Directories

Another option is to share one OC4J installation, but keep the configuration files in different directories. In this case, you must start OC4J with a special command-line parameter that tells it where to find the appropriate server.xml file. Since all configuration files are loaded relative to the main server configuration file (usually server.xml ), it's not necessary for everything to be kept in the default config directory. Instead, you can create several different configuration directories and just pass the appropriate server.xml file path to oc4j.jar using the -config option.

For example, a typical setup might include the following directories shown in Table 4-1.

Table 4-1: Example Setup with Multiple Configuration Directories

File/Directory	Description
j2ee/home/devConfig	A directory that contains a complete set of configuration files, with the main application data source pointing to the development database, with transaction timeouts set high, and with other special development-friendly settings
j2ee/home/testConfig	A directory that contains a complete set of configuration files with the main application data source pointing to the test database, with transaction timeouts set normally, with custom log settings, and so on
startDev.sh	A shell script that starts the server using the server.xml file in the development configuration directory with a line like this: java -jar oc4j.jar -config devConfig/server.xml
startTest.sh	A shell script that starts the server using the server.xml file in the test configuration directory, like this: java -jar oc4j.jar -config testConfig/server.xml

This option simplifies maintenance since you don't have to worry about your OC4J versions getting out of sync. Furthermore, you can use all the default filenames, which make it easy to copy files from one configuration to another once you've tested them. This is convenient for staging environments. However, it can be a hassle if you just want to tweak a few settings here and there, while letting changes to the rest affect both configurations.

Multiple Versions of Configuration Files in a Single Directory

When you just want to try out a few new settings or allow easy switching between databases and security schemes, the easiest option is to create one or more duplicate server configuration files (in other words, renamed copies of server.xml ) within the same config directory.

These will start out referring to all the same default configuration files ( application.xml, data-sources.xml , and so on) and then you can just customize the parts that should be different.

For example, you might have the following directories shown in Table 4-2.

Table 4-2: Example Setup with Multiple Configuration Files in One Directory

File/Directory	Description
j2ee/home/config/dev-server.xml	A server configuration file that sets up development-friendly server settings and points to a special dev-application.xml file containing your development database settings
j2ee/home/config/test-server.xml	A server configuration file that sets up test-friendly server settings and points to a special test-application.xml containing your test database settings
startDev.sh	A shell script that starts the server using the development version of server.xml with a line like this: java -jar oc4j.jar -config config/dev-server.xml
startTest.sh	A shell script that starts the server using the test version of server.xml with a line like this: java -jar oc4j.jar -config config/test-server.xml