OracleAS Job Scheduler Tag Library Reference

Table of Contents

1. Overview

This tag library is used to interact with the OracleAS Job Scheduler.

With this tag library jobs can be added, removed, paused, resumed and queried. Likewise blackout windows can be added, removed and queried. In addition a number of helper tags are provided for conditional operations on jobs and audit records. For example, emitting content based on the status of a job execution.

2. Configuration

Follow these steps to configure an web application with this tag library:

    <taglib>
      <taglib-uri>scheduler-taglib</taglib-uri>
      <taglib-location>/WEB-INF/scheduler.tld</taglib-location>
    </taglib>

To use the tags from this library in a JSP pages, add the following directive at the top of each page:

    <%@ taglib uri="scheduler-taglib" prefix="s" %>

Where, following the example, "s" is the tag name prefix for tags from this library although any prefix may be specified.

3. Tag Summary

This section provides a summary of each of the tags provided by this library.

4. Tag Reference

4.1 scheduler tag

Provides an implicit EJB context for interacting with the scheduler. Because context is implicit this tag must be the parent of all other tags provided by this library. The following attributes are supported:

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler" scope="application">
      .
      .
      .
    </s:scheduler>

4.2 jobIterator tag

Provides an iterator to jobs submitted to the scheduler. Because an EJB context is required to communicate with the scheduler EJB this tag must be enclosed in a scheduler tag. The following attributes are supported:

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobsIterator id="job">
        .
        .
        .
      </s:jobsIterator>
    </s:scheduler>

This tag supports the following sub-tags:

4.3 jobIsActive tag

Helper tag for evaluating a job's state resulting in conditional processing of the tag's body. If the associated job's state is active then the contents of the tags body is further evaluated. The job to evaluate may either be specified implicitly (when used in conjunction with the jobIterator tag or explicitly by specifying a oracle.ias.scheduler.Job bean instance. The following attributes are supported:

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobsIterator id="job">
        <jsp:getProperty name="job" property="description"/>
        <s:jobIsActive>is active</s:jobIsActive><BR>
      </s:jobsIterator>
    </s:scheduler>

This example outputs the descriptions of all jobs optionally appending the text 'is active' if the job is active.

4.4 jobIsPaused tag

Helper tag for evaluating a job's state resulting in conditional processing of the tag's body. If the associated job's state is paused then the contents of the tags body is further evaluated. The job to evaluate may either be specified implicitly (when used in conjunction with the jobIterator tag or explicitly by specifying a oracle.ias.scheduler.Job bean instance. The following attributes are supported:

4.5 jobIsCompleted tag

Helper tag for evaluating a job's state resulting in conditional processing of the tag's body. If the associated job's state is complete then the contents of the tags body is further evaluated. The job to evaluate may either be specified implicitly (when used in conjunction with the jobIterator tag or explicitly by specifying a oracle.ias.scheduler.Job bean instance. The following attributes are supported:

4.6 removeAuditRecords tag

Removes all audit records for a job. This tag must be enclosed in a jobIterator tag. The audit records are removed for the job specified by the enclosing tag.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobsIterator id="job">
        <s:jobIsCompleted><s:removeAuditRecords/>Removed audit records for completed job</s:jobIsCompleted>
      </s:jobsIterator>
    </s:scheduler>

This example removes the audit records of all jobs that are completed. This is accomplished by using the tag in conjunction with the jobIsCompleted tag.

4.7 auditRecordIterator tag

Provides an iterator to audit records for a job. This tag must be enclosed in a jobIterator tag. The audit records are retrieved for the job specified by the enclosing tag.

The following attributes are supported:

This tag supports the following sub-tags:

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobsIterator id="job"><jsp:getProperty name="job" property="description"/>: 
        <s:auditRecordIterator id="record"><jsp:expression>record</jsp:expression></s:auditRecord>
      </s:jobsIterator>
      <BR>
    </s:scheduler>

This example outputs all job descriptions followed by a comma delimted list of all the job's audit records.

4.7.1 executionSucceeded tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is successful then the contents of the tags body is further evaluated.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobsIterator id="job">
        <s:auditRecordIterator id="record">
          <s:executionSucceeded>
            <jsp:getProperty name="job" property="description"/><BR>
          </s:executionSucceeded>
        </s:auditRecordIterator>
      </s:jobsIterator>
    </s:scheduler>

This example outputs a list of all the job's that have executed successfully.

4.7.2 executionFailed tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is failed then the contents of the tags body is further evaluated.

4.7.3 executionIncomplete tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is incomplete then the contents of the tags body is further evaluated.

4.7.4 executionCancelled tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is cancelled then the contents of the tags body is further evaluated.

4.7.5 executionBlackout tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is blackout (i.e. execution was attempted while an execution blackout window was in effect) then the contents of the tags body is further evaluated.

4.7.6 executionThresholdExceeded tag

Helper tag for evaluating the status of a job's audit record resulting in conditional processing of the tags body. This tag must be enclosed in a auditRecordIterator tag. The record evaluated is specified by the enclosing tag. If the associated record's status is threshold exceeded (i.e. the actual time of execution exceeded the expected time of execution by the threshold specified for the job) then the contents of the tags body is further evaluated.

4.8 addJob tag

Adds a job to the scheduler. This tag must be enclosed in a scheduler tag.

This tag supports the following sub-tags:

4.8.1 className tag

Specifies the class name when adding a new job. This must be enclosed in a addJob tag. This tag is required.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
      </s:addJob>
    </s:scheduler>

4.8.2 description tag

Specifies the job description when adding a new job. This must be enclosed in a addJob tag. This tag is optional.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:description>Example job description</s:description>
      </s:addJob>
    </s:scheduler>

4.8.3 schedule tag

Used to specify a schedule for a job or blackout window. This tag must be enclosed in a either of a addJob or addBlackoutWindow tag.

This tag supports the following sub-tags:

4.8.3.1 duration tag

Used to specify the initial expiration duration of the schedule. This tag must be enclosed in a schedule tag. Use of this tag is optional. The body of this tag is used to specify the duration. The duration is specified as an arbitrary number of units and associated value(s) or a specific date and time.

Some example durations are:

This tag supports the following sub-tags:

4.8.3.1.1 date tag

This tag is used to specify an exact date for the initial exipration of a job. This tag must be enclosed in a duration tag. The format of the date expression specified must be compliant with the date parsing routines provided by the java.text.DateFormat. If a time tag does not accompany this tag in the enclosing body of the duration tag the default time of 12:00:00AM will be used.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:duration>
            <s:date>October 27, 2003</s:date>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the duration of the schedule is set to the date October 27, 2003 12:00AM PST.

4.8.3.1.2 time tag

This tag is used to specify an exact time for the initial exipration of a job. This tag must be enclosed in a duration tag. The format of the time expression specified must be compliant with the time parsing routines provided by the java.text.TimeFormat. If a date tag does not accompany this tag in the enclosing body of the duration tag, the date on which the job was submitted will be used.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:duration>
            <s:date>October 27, 2003</s:date>
            <s:time>16:30:00 PST</s:date>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the duration of the schedule is set to the date October 27, 2003 4:30PM PST.

4.8.3.1.3 years unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of years to expiration. This tag may be used in conjunction with any of the tags months, weeks, days, hours, and minutes. The body of the tag must be a positive non-zero integer. If the duration or interval occurs on a leap day the expiration will be rounded to the last day of the month (e.g. February 29 + 1 year = February 28).

Example usage as a duration:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:duration>
            <s:years>1</s:years>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the duration of the schedule is set to one year from the time of submission.

Example usage as interval:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:interval>
            <s:years>1</s:years>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the interval of the schedule is set to repeat every year.

4.8.3.1.4 months unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of months to expiration. This tag may be used in conjunction with any of the tags years, weeks, days, hours, and minutes. The body of the tag must be a positive non-zero integer. Rounding may result when calculating the duration or interval when expiration occurs at the end of the month. In such cases the rounding always occurs to the last day of the month (e.g. January 31 + 1 month = Februrary 28).

Example usage as a duration:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:duration>
            <s:months>1</s:months>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the duration of the schedule is set to one month from the time of submission.

Example usage as interval:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:interval>
            <s:months>3</s:months>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the interval of the schedule is set to repeat every three months.

4.8.3.1.5 weeks unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of weeks until expiration. This tag may be used in conjunction with any of the tags years, months, days, hours, minutes, seconds, and milliseconds. The body of the tag must be a positive non-zero integer.

4.8.3.1.6 days unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of days until expiration. This tag may be used in conjunction with any of the tags years, months, weeks, hours, minutes, seconds, and milliseconds. The body of the tag must be a positive non-zero integer.

4.8.3.1.7 hours unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of hours until expiration. This tag may be used in conjunction with any of the tags years, months, weeks, days, minutes, seconds, and milliseconds. The body of the tag must be a positive non-zero integer.

4.8.3.1.8 minutes unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of minutes until expiration. This tag may be used in conjunction with any of the tags years, months, weeks, days, hours, seconds, and milliseconds. The body of the tag must be a positive non-zero integer.

4.8.3.1.9 seconds unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of minutes until expiration. This tag may be used in conjunction with any of the tags years, months, weeks, days, hours, minutes and milliseconds. The body of the tag must be a positive non-zero integer.

4.8.3.1.8 milliseconds unit tag

This tag may be used in conjunction with either of the tags duration or interval. This tag is used to specify the number of minutes until expiration. This tag may be used in conjunction with any of the tags years, months, weeks, days, hours, minutes, and seconds. The body of the tag must be a positive non-zero integer.

4.8.3.2 interval tag

Used to specify the repeating interval of the schedule. This tag must be enclosed in a schedule tag. Use of this tag is optional. The body of this tag is used to specify the interval. The interval is specified as an arbitrary number of units (months, days, weeks, etc..) and associated values.

Some example intervals are:

This tag supports the following sub-tags:

4.8.3.2.1 end tag

Used to specify the end date for the repeating interval of the schedule. This tag must be enclosed in a interval tag. Use of this tag is optional. The body of this tag is used to specify the end date. The interval is specified as an arbitrary number of units (months, days, weeks, etc..) and associated values.

Example usage:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:interval>
            <s:months>1</s:months>
            <s:end>
              <s:years>1</s:years>
            </s:end>
          </s:duration>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

In this example the job repeats execution every year for one year.

4.8.3.4 threshold tag

Specifies the execution threshold for the job. This tag must be enclosed in a schedule tag. The body of this tag is used to specify the threshold whereby specified as an arbitrary number of units (days, hours, minutes, etc..) and associated value(s). Use of this tag is optional.

Some example thresholds are:

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:schedule>
          <s:threshold>
            <s:hours>1</s:hours>
          </s:threshold>
        </s:schedule>
      </s:addJob>
    </s:scheduler>

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:trigger>do_it_now</s:trigger>
      </s:addJob>
    </s:scheduler>

    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addJob>
        <s:className>TestJobImpl</s:className>
        <s:retry>
          <s:hours>1</s:hours>
          <s:minutes>30</s:minutes>
        </s:retry>
      </s:addJob>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <jsp:useBean id="job" class="oracle.ias.scheduler.Job" scope="session"/>
    <s:scheduler id="scheduler"  name="java:comp/env/ejb/scheduler">
      <s:removeJob name="job"/>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobIterator>
        <s:removeJob/>
      </s:jobIterator>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <jsp:useBean id="job" class="oracle.ias.scheduler.Job" scope="session"/>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:pauseJob name="job"/>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobIterator>
        <s:pauseJob/>
      </s:jobIterator>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <jsp:useBean id="job" class="oracle.ias.scheduler.Job" scope="session"/>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:resumeJob name="job"/>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobIterator>
        <s:resumeJob/>
      </s:jobIterator>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <jsp:useBean id="job" class="oracle.ias.scheduler.Job" scope="session"/>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:cancelJob name="job"/>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobIterator>
        <s:cancelJob/>
      </s:jobIterator>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:addBlackoutWindow>
        <s:description>two hour downtime, effective immediately</s:description>
        <s:duration>
          <s:hours>2</s:hours>
        </s:duration>
      </s:addBlackoutWindow>
    </s:scheduler>

    <%@ taglib uri="scheduler-taglib" prefix="s" %>
    <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:removeBlackoutWindow>two hour downtime, effective immediately</s:removeBlackoutWindow>
    </s:scheduler>