How-To Configure and Use Job Scheduler in OC4J 10g (10.1.3) with database persistence

Date: 12/16/2005
Author:  Tony D'Silva

• Introduction
• Prerequisites
  • What you need to know
  • Software requirements
  • Notations
• Building the Application
  • Implementing a Job
    
  • Accessing the scheduler
    
  • Submitting a job
  • Demo Application Implementation
• Running the Application
  • Examining the How to distribution
    
  • Configuring the Environment
  • Starting the OC4J Instance
  • Generating, Compiling and Deploying the Application
  • Running the Application
• Summary

Introduction

• API for submitting, controlling, and monitoring jobs
• API-level JTA support for job submission and control
• Temporal- and trigger-based job execution
• Automatic retry of failed jobs
• Job blackout windows
• JMX monitoring and administration
• Auditing and logging

For full documentation and javadoc on the Scheduler see the Oracle Containers for Java Scheduler Developer's Guide on OTN. 
The application accompanying this how-to demonstrates how to deploy and use the scheduler in the JDBC jobstore configuration, from a  J2EE application in the OC4J container.

Prerequisites

What you need to know

• You should be familiar with these technologies: J2EE and in particular EJB and  Servlets,.

Software Requirements

Provide links to where the software is available. The least should include a JDK, Ant, and OC4J

• OracleAS 10.1.3 is installed, available from OTN
• Apache Ant 1.6.2 or above, to build the application, available from here
• Any HTML browser like Mozilla, Microsoft Internet Explorer, Netscape, etc.

Notations

List the notation used throughout the document. Keep to the convention of %NAME% for environment like variables.

• %ORACLE_HOME% - The directory where you installed the Oracle Application Server 10 g.
• %JAVA_HOME% - The directory where your JDK is installed
• %ANT_HOME% -The location where Ant is installed
• %HOWTO_HOME% - The directory where this demo is unzipped

Building the Application

Implementing a Job

public interface Executable {
                          

    public void execute (JobContext context);
                          

}
                          

                        

Accessing the Scheduler

The Scheduler is an application component. In order to access the Scheduler a JNDI lookup is necessary. The following example demonstrates how to perform this lookup:

InitialContext ic = new InitialContext();
                          

Object objRef = ic.lookup("java:comp/env/ejb/scheduler");
                          

SchedulerHome home = (SchedulerHome)
                          

PortableRemoteObject.narrow(objRef, SchedulerHome.class);
                          

Scheduler scheduler = home.create();
                          

                        

Submitting a job

public JobHandle add(String description,
                          

                     String className,
                          

                     Schedule schedule,
                          

                     Properties properties)
                          

                        

description

The description for this job.

className

The name of the Java class that will be run when the specified schedule expires. This class must implement the Executable interface.

schedule

Specifies when and how often the job is run by the Scheduler. The Scheduler supports several different options for specifying including including iCalendar recurrence expressions.

properties

This parameter is used to specifying runtime parameters for the job.

Demo Application Implementation

Running the Application

The following instructions are for running this demonstration on a standalone instance of Oracle Containers for J2EE 10g (10.1.3.0.0).

Examining the Sample File Directories

• readme.html the description of this how-to
• build - temporary directory created during the build
• etc - all necessary configuration files to package the application
• dist - holds the application archives that could be deployed (e.g., ear, war, rar, jar files)
• src - the source code of the demo
• sql - the sql scripts required to run the demo

Configuring the Environment

• %ORACLE_HOME% - The directory where you installed OC4J
• %JAVA_HOME% - The directory where your JDK is installed
• %ANT_HOME% -The directory where Ant is installed.

• oracle.home - the root directory of oracle installation.  Defaults to ORACLE_HOME environment variable.
• java.home -  the root directory of JDK installation.  Defaults to JAVA_HOME environment variable.
• oracleas.host - the hostname of the platform on which the OC4J instance is running.  Defaults to localhost.
• oracleas.http.port - the port on which the OC4J HTTP listener is listening.  Defaults to 8888.
• oracleas.admin.port  - the port on which the OC4J administration processor is listening.  Defaults to 23791.
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.admin.password - the password for the OC4J administrator.  Defaults to " welcome".
• oracleas.binding.module - the name of the HTTP web site to which the deployed application is bound.  Defaults to " default-web-site".

Database setup

•   The script  must be run as db administrator.
•  The script must be edited and the %ORACLE_HOME% placeholder must be replaced with the root of the user's installation. 
• DO NOT change the user name or user password used. This is because the demo application's data-source ( %TEST_HOME%/etc/data-sources.xml)  have been configured with the same user name and user password.

Configuring the Environment for a Managed OracleAS Instance

• oracleas.http.port - the port on which the Oracle HTTP Server (OHS) is listening.
• oracleas.admin.port  - The OPMN request port, as specified in opmn.xml, the default value is 6003.  You can also check the OPMN request port using the following command: %ORACLE_HOME%/opmn/bin/opmnctl status -port
• oracleas.admin.user - the name of the OC4J administrator.  Defaults to " oc4jadmin".
• oracleas.deployer.uri - the URI to use to do the different administration operation (deployment, undeployment). The file contains different URI depending of the topology of your application: stand alone OC4J, Managed Single Node or Managed Cluster. You just need to un-comment the URI that matches your toplogy.
• oracleas.oc4j.instance - This is the managed OC4J instance where the application will be deployed or undeployed.

• Adding the JMS queue destinations to jms.xml :  Insert the following configuration snippet (also provided at %HOWTO_HOME%/etc/frag-jms.xml) into %ORACLE_HOME%/j2ee/home/config/jms.xml

Starting the OC4J Instance

Generating, Compiling and Deployin the Application

To build and deploy the application, type the following command from the %HOWTO_HOME% directory:

• ant

You should now have the newly created  SchedulerJDBCDemo .ear in your %HOWTO_HOME%/dist directory.

Before deploying it will first test whether OC4J is running.

Note that you can also deploy the application separately . Ensure the %ORACLE_HOME% environment variable is defined, and from the %HOWTO_HOME% directory, type the command:

ant deploy

Running the Application

http://localhost:8888/scheduler/simple-jdbcdemo

This will bring up the main page for submitting a job that periodically puts a timestamped message on a jms queue :

Job  Starts in  :

The number of seconds from current time for job executions to commence

Job Ends in :

The  number of seconds from current time for job to end

Interval :

The interval between executions

After filling in the form and clicking on the submit button,  watch the oc4j console for timestamped messages output from the scheduler's job

Summary

• Learned how to create a job
• Learned how to access the Scheduler
• Learned how to submit a job