2 Developing Startup and Shutdown Classes

This chapter provides guidelines on developing startup and shutdown 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.

Developing Startup Classes
Developing Shutdown Classes

Developing Startup Classes

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

Note:

It is strongly recommended that you give your startup class a public, no-argument constructor. Otherwise, java.lang.IllegalAccessException may be thrown when OC4J attempts to invoke a member method of this class.

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

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.

Add the following notation to 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 oracle.j2ee.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 oracle.j2ee.server.OC4JStartup;

import javax.naming.*;
import java.util.*;

public class TestStartup implements OC4JStartup {

   //public, no-argument constructor
    public TestStartup() {
    }

    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.

Developing Shutdown Classes

Shutdown classes are executed before OC4J terminates. Your shutdown class implements the oracle.j2ee.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 terminate.

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.

Note:

It is strongly recommended that you give your shutdown class a public, no-argument constructor. Otherwise, java.lang.IllegalAccessException may be thrown when OC4J attempts to invoke a member method of this class.

The implementation and configuration is identical to the shutdown classes as described in "Developing 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" />