The OracleAS Job Scheduler is a new component accompanying the 10.1.3
release. The Scheduler provides asynchronous scheduling services for
J2EE applications. Some key features are:
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
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
10g.
%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
To start
using the Scheduler from a J2EE application, all you need is a handle
to the Scheduler. The following steps will show how to build, deploy
and use the scheduler from a J2EE application.
Implementing a Job
A job is a POJO (Plain Old Java Object) that provides an
implementation of the oracle.ias.scheduler.Executable
interface. This interface is defined as follows:
public interface Executable { public void execute (JobContext context); }
To execute a job the Scheduler invokes the job's
execute() method.
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();
As you may have guessed from the look of the JNDI name used the
Scheduler's API is implemented as an EJB. More specifically the it is
implemented as stateless session EJB. The Scheduler provides a
plethora of APIs for submitting and managing jobs.
Submitting a job
Once you have a handle to the Scheduler you can submit the job. This
is done using Scheduler's add() method. This method has
the following definition:
public JobHandle add(String description, String className, Schedule schedule, Properties properties)
The input parameters are as follows:
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.
A JobHandle object is returned by this API. This object
can be used to further manage, for example to cancel the job's
execution.
Demo Application
Implementation
The application that accompanies this how-to demonstrates how to use
the scheduler from a J2EE application. The application consists of a
simple servlet component that adds a scheduler job. When the job
executes it puts a timestamped message onto a JMS queue. The servlet
receives this timestamped message and outputs the result to the
OC4Jconsole. The job's scheduling information is posted to the servlet
via an html form.
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
Make sure the following environment variables are defined.
%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.
Make sure that the following properties are configured
correctly in the ant-oracle.properties
file located in the root of the sample's distribution (NOTE:
Some
of these properties will default to the values of corresponding
environment variables as noted below. If you have these
variables
setup in your environment you may not have to alter the values in the
file). If necessary, modify these variable to the proper
values
for you environment:
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".
In addition, please make sure that the ant command associated with the
OC4J ant distribution is in your execution path (%ORACLE_HOME%/ant/bin).
Database setup
The following SQL script must be installed in an ORACLE DB. This
script creates a new db user (schedulerDemoUser) and installs the
jobstore tables under that user's schema: %TEST_HOME%/sql/dbsetup.sql
You can issue the following command on your database installation:
sqlplus
<admin_db_user>/<admin_db_password> @dbsetup.sql
important !
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
If you are running a managed version of the Oracle Application Server 10g, you are using OPMN, you must
change the following values to match your configuration:
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.
The following configuration change required for scheduler :
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
<queue
name="jms/SCHEDULER_DEMO_events"
location="jms/SCHEDULER_DEMO_events"
persistence-file="scheduler_SCHEDULER_DEMO_events">
<description>Scheduler event queue
for demo</description>
</queue>
<queue name="jms/SCHEDULER_DEMO_notifications"
location="jms/SCHEDULER_DEMO_notifications"
persistence-file="scheduler_SCHEDULER_DEMO_notifications">
<description>Scheduler
notification queue for demo</description>
</queue>
Starting
the OC4J Instance
Start an OracleAS 10g (10.1.3)
instance as follows:
Stand Alone Installation: %ORACLE_HOME%/bin/oc4j
start Note that the oc4j command
expects the JAVA_HOME environment variable to point to a full JDK
installation.
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
To run the application open the following URL in a browser on the same
machine on which application is deployed:
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
Bookmark
