Basic Operation | Oracle Application Server 10g: J2EE Deployment and Administration

Once the OC4J Standalone server has been installed, it can be managed entirely from the command line using two executable Java archive (JAR) files. In this section, we'll cover starting, stopping, and restarting the server, both manually and as an automatic service. Generally , it's also useful to capture these commands and any preferred options in reusable batch or shell scripts.

Starting the Server

Although later we'll use Oracle Enterprise Manager to start a full Oracle Application Server 10g installation, the standalone version can be started by executing oc4j.jar directly, within the J2EE_HOME directory, as follows :

 C:\java\oc4j\j2ee\home>java -jar oc4j.jar

Once the server has been initialized , it should print a brief message, and start accepting connections.

Tip	To start OC4J from any directory, create a system environment variable called J2EE_HOME that points to the j2ee/home directory within your OC4J installation.

Though oc4j.jar is frequently executed without any command-line options, there are a few useful ones available, as described in Table 3-3.

Table 3-3: OC4J Startup Options
Option	Description
-install	Completes all necessary installation tasks , including the activation of the admin account and the rewriting of configuration files with the appropriate line endings for the host platform.
-out <filename>	Redirects standard output to the specified file.
-err <filename>	Redirects standard error to the specified file.
-quiet	Suppresses standard output.
-validateXML	Validates all XML configuration files as they are loaded.
-userThreads	Allows context lookups from user -created threads.
-monitorResourceThreads	Additional thread-debugging output.
-version	Prints the OC4J version number.
-help	Prints usage information, including a list of these options.

Several other options are listed in the usage information, but aren't fully functional in this release. Later in this chapter, we'll cover additional Java Virtual Machine (JVM) options that may be used to improve performance.

Tip	Use the -validateXML option with care; the OC4J document type declarations (DTDs) often have errors, so validation may reject legitimate configuration files.

Stopping the Server

Before we move on to discuss how to shut down and restart the server, please note that the shutdown and restart options described in the these sections should only be used on a standalone server that has been launched by executing oc4j.jar , as described in the previous section. Please see Chapter 15 for details about starting and stopping full Oracle Application Server 10g instances.

OC4J should be stopped using admin.jar . This utility takes a host, an RMI port, a username, a password, and a command, as shown here:

 java -jar admin.jar ormi://host.domain.com<:port>       <username> <password> <command> [command-options]

The host should be the machine on which the server is running. The RMI port can be found in the rmi.xml configuration file, and defaults to 23791. The username is normally admin , and the password should be whatever you set it to during installation. Most admin.jar commands deal with configuration and deployment and will be discussed later in this book.

To stop the server, use the following shutdown command, which accepts two options:

 -shutdown [forceordinary] [reason]

The first option controls whether the server will be allowed to terminate normally, or will be forced to shut down immediately. It defaults to ordinary .

The second option indicates a reason for the shutdown. If specified, this reason will be recorded in the server log.

For example, to stop the server normally, allowing time for all threads to shut down, you might execute this:

 C:\java\oc4j\j2ee\home>java -jar admin.jar ormi://localhost:23791       admin mypassword -shutdown "Testing the shutdown process"

To force a shutdown, you might execute the following:

 C:\java\oc4j\j2ee\home>java -jar admin.jar ormi://localhost:23791       admin mypassword -shutdown force

If all else fails, you can manually kill the process through the operating system, usually by either hitting Ctrl-C in the terminal, or by finding and terminating the process if it's running in the background.

Restarting the Server

Often, it's necessary to restart the server to apply configuration changes. Rather than stopping and starting the server in two steps, you can use the -restart command defined in admin.jar . Like -shutdown , this command accepts an optional reason for the log:

  -restart [reason]

Here's an example:

 C:\java\oc4j\j2ee\home>java -jar admin.jar ormi://localhost:23791       admin mypassword -restart "Restarting to add data source"

Tip	When it receives the restart command, OC4J only prints a single "Restarting" message. By default, it doesn't print a message to indicate that the restart was successful.

Sample Scripts

This section includes sample scripts to start and stop OC4J. These should be placed in and run from the j2ee/home directory, though you can modify them to run from other directories. Note that the UNIX scripts must be marked as executable (using a command such as chmod u+rx ).

UNIX Start Script (start.sh)

 #! /bin/sh  java -Xms128m -Xmx512m -jar oc4j.jar

UNIX Stop Script (stop.sh)

 #! /bin/sh java -jar admin.jar ormi://localhost admin (password) -shutdown force

Windows Start Script (start.bat)

 java -Xms128m -Xmx512m -jar oc4j.jar

Windows Stop Script (stop.bat)

 java -jar admin.jar ormi://localhost admin (password) -shutdown force

Running as a Windows Service

The OC4J Standalone distribution doesn't support installation as a Windows service. However, on many Windows versions, it's possible to manually configure it as a user-defined service using additional tools.

Tip	For a free package that installs Java programs such as OC4J as Windows services, see http://wrapper.tanukisoftware.org/doc/english/ .

The full Oracle Application Server 10g package includes built-in support for execution as a Windows service. See Chapter 15 for more details.

Running as a UNIX Service

OC4J Standalone doesn't include built-in support for execution as a UNIX service, but it can be configured as one in the typical way. For example, on a UNIX system using System V Init scripts, you might do the following:

Create scripts to start, restart, and shut down the server as described earlier in this chapter (making sure that the start script starts the server as a background process and redirects stderr and stdout to appropriate log files).
Create a script in the init.d directory (often /etc/init.d, /etc/rc.d/init.d , or /sbin/init.d ), following the usual conventions. These scripts generally accept start, stop , and restart arguments and in this case, should invoke the appropriate scripts from step 1.
Create appropriate links in the rc#.d directories, where # is the runlevel . Some operating systems have a utility to manage this, such as chkconfig on Red Hat Linux and UnitedLinux.

Once you've configured these scripts, the server will be started and stopped according to the runlevel configuration, and you can start and stop it manually by invoking the main script under /etc/init.d with the start, stop , and restart arguments.

Tip	For a free package that installs Java programs such as OC4J as UNIX services, see http://wrapper.tanukisoftware.org/doc/english/ . Of course, copying and customizing an existing init.d script would work just as well.