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.

When you compile these classes, the oc4j-api.jar file must be in a path specified in the Java CLASSPATH environment variable, such as ORACLE_HOME/j2ee/home/oc4j-api.jar.

OC4J deploys and executes the startup and shutdown classes based on configuration of these classes in the server.xml file.

This chapter includes these topics:

Developing Startup Classes
Developing Shutdown Classes

Developing Startup Classes

Startup classes are executed only once after OC4J initializes. They are not reexecuted every time the server.xml file is touched. A startup class implements the oracle.j2ee.server.OC4JStartup interface, which contains two methods:

preDeploy

This method executes before any OC4J application initialization.
postDeploy

This method executes after all OC4J applications initialize.

In these methods, you can implement code for starting services, performing other initialization routines, ending services, and performing other termination routines.

Each method requires two arguments:

Hashtable

This argument specifies a hash table that is populated from the configuration.
Context

This argument specifies a JNDI context to which you can bind to process values contained within the context.

Both methods return a String value, which is currently ignored.

Note:

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

After you create a startup class, you must configure it within the <startup-classes> element in the server.xml file. You can access this file through the Application Server Control Console 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> element defines the following attributes:

The name of the class that implements the oracle.j2ee.server.OC4JStartup interface
Whether a failure is fatal

The default is not fatal. When an exception is thrown for a failure that is not considered fatal, OC4J logs the exception and continues. When an exception is thrown for a failure that is considered fatal, OC4J logs the exception and exits.
The order of execution

Each startup class receives an integer. The integers designate in what order the classes are executed, starting with 0.
The initialization parameters, which contain key-value pairs of type String, that OC4J takes

Initialization parameters are provided through the input Hashtable argument. The name of each key-value pair must be unique because JNDI is used to bind each value to its name.

In the <init-library> element in the server.xml file, you configure the directory where the startup class resides or the directory and JAR file where the class is archived. The path attribute can be fully qualified or relative to /j2ee/instance/config.

For example, the configuration for the TestStartup class is contained within a <startup-class> element in the server.xml file:

The failure-is-fatal attribute is true, so an exception would cause OC4J to exit.
The <execution-order> subelement contains 0, so this is the first startup class to execute.
Two initialization key-value pairs are defined, of type String. These key-value pairs will be populated in the hash table that the Hashtable argument specifies:
```
"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="test.oc4j.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 key-value pairs within the input Hashtable argument 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 hash table and prints them. The postDeploy method is a null method. The oc4j.jar file must be in the path that the Java CLASSPATH environment variable specifies when you compile TestStartup.

package text.oc4j;
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", you would modify the <init-library> element in the server.xml file as follows:

<init-library path="../app1/startup.jar" />

When OC4J starts, the preDeploy method of TestStartup is executed before any application is initialized. OC4J populates the JNDI context with the values from the hash table. If TestStartup throws an exception, then OC4J exits because the failure-is-fatal attribute was set to true.

Developing Shutdown Classes

Shutdown classes are executed before OC4J terminates. A shutdown class implements the oracle.j2ee.server.OC4JShutdown interface, which 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 hash table that is populated from the configuration and a JNDI context to which you can bind to process values specified in key-value pairs.

Note:

Oracle strongly recommends that if you give your shutdown class a constructor, you give it 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="test.oc4j.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 "/j2ee/home/app1/shutdown.jar", add another <init-library> element in the server.xml file, as follows:

<init-library path="../app1/shutdown.jar" />