C JSP Tag Library Reference

The Job Scheduler JSP Tag Library is used to interact with the Oracle Application Server Containers for J2EE. It is used to add, remove, pause, resume, and query jobs, as well as add, remove, and query blackout windows. In addition, a number of helper tags are provided for conditional operations on jobs and audit records (for example, distributing content based on the status of a job).

The following sections are covered:

Configuring an Application with the JSP Tag Library
JSP Tag Library Summary
JSP Tag Library Reference
JSP Tag Library Examples

C.1 Configuring an Application with the JSP Tag Library

Follow these steps to configure a web application with the JSP Tag Library:

Copy the JSP Tag Library descriptor file to the /WEB-INF subdirectory of your Web application.
Copy the JSP Tag library JAR file to the /WEB-INF/lib subdirectory of your Web application.

Add a <taglib> element to your Web application deployment descriptor in /WEB-INF/web.xml. For example:

<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 page, add the following directive at the top of each page:

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

The s is the tag name prefix for tags from this library, although any prefix can be specified.

C.2 JSP Tag Library Summary

Table C-1 provides a summary of the primary tags included in this library.

Table C-1 JSP Tag Library Summary

Tag	Description
scheduler	Top-level tag for all Job Scheduler tags.
addJob	Adds a new job.
removeJob	Removes an existing job.
pauseJob	Pauses a job.
resumeJob	Resumes a paused job.
cancelJob	Cancels a job.
addBlackoutWindow	Adds a new blackout window.
removeBlackoutWindow	Removes an existing blackout window.

C.3 JSP Tag Library Reference

This section provides reference information for each of the tags listed in Section C.2.

C.3.1 scheduler

The scheduler tag provides an implicit EJB context for interacting with Job Scheduler. Because context is implicit, this tag must be the parent of all other tags provided by this library.

Table C-2 describes the supported attributes for the scheduler tag.

Table C-2 scheduler Tag Attributes

Attribute	Required?	Description
`id`	Yes	Instance name of the Job Scheduler EJB by which the Job Scheduler may be accessed.
`name`	Yes	JNDI name of the Job Scheduler EJB responsible for processing all operations in the body of this tag.
`scope`	No	Scope^Foot 1 of the implicit EJB context. Valid values are `page`, `request`, `session`, or `application`. The default is `page`.

^Footnote 1This is equivalent to the JSP PAGECONTEXT scope.

Example:

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

C.3.2 addJob

The addJob tag adds a new job to Job Scheduler. This tag must be enclosed within a scheduler tag.

Table C-3 describes the supported helper tags for the addJob tag.

Table C-3 Helper Tags for the addJob Tag

Helper Tag	Required?	Description
className	Yes	Class name of the job.
description	No	Description of the job.
schedule	No	Job schedule (specifies how often a timeout is sent to the trigger).
trigger	No	Job trigger (specifies a condition to be met before a job is run).
retry	No	Job retry period.
logLevel	No	Job log level.

C.3.2.1 className

Use this helper tag to specify the class name when adding a new job. This tag must be enclosed in an addJob tag.

Example:

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

C.3.2.2 description

Use this helper tag to specify a job description when adding a new job. This tag must be enclosed in an addJob tag.

Example:

<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>

C.3.2.3 schedule

Use this helper tag to specify a schedule for a job or blackout window. This tag must be enclosed in either an addJob or addBlackoutWindow tag.

Table C-4 describes the supported helper tags for the schedule helper tag.

Table C-4 Helper Tags for the schedule Helper Tag

Helper Tag	Required?	Description
duration	No	Initial expiration duration of the schedule.
interval	No	Repeat interval of the schedule.
threshold	No	Execution threshold for the job (applicable only when used in conjunction with the `addJob` tag).

C.3.2.3.1 duration

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

Some example durations are:

1 week
1 month, 5 days
March 15, 2005
January 5 2004 16:00:00 PST

Table C-5 describes the supported helper tags for the duration helper tag.

Table C-5 Helper Tags for the duration Helper Tag

Helper Tag	Required?	Description
date	No	Date of initial expiration. This tag can be combined with the `time` tag.
time	No	Time of initial expiration. This tag can be combined with the `date` tag.
years	No	Expiration in years relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
months	No	Expiration in months relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
weeks	No	Expiration in weeks relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
days	No	Expiration in days relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
hours	No	Expiration in hours relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
minutes	No	Expiration in minutes relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
seconds	No	Expiration in seconds relative to the time at which the job is submitted. This tag can be combined with any other helper tag.
milliseconds	No	Expiration in milliseconds relative to the time at which the job is submitted. This tag can be combined with any other helper tag.

Detailed descriptions and examples of the helper tags described in Table C-5 are provided in the following sections.

Note:

To avoid repetition, full code examples are provided for the first few tags. Partial code examples are provided for the remainder of the tags in this section.

date

Use this helper tag to specify an exact date for the initial expiration of a job. This tag must be enclosed in a duration tag. The format of the date expression must comply with the date parsing routines provided by the java.text.DateFormat class. If this tag is not used in conjunction with a time tag, the enclosing body of the duration tag uses the default time of 12:00:00 a.m.

Use the following code to set the schedule duration to October 27, 2003 12:00 a.m. PST.

<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>

time

Use this helper tag to specify an exact time for the initial expiration of a job. This tag must be enclosed in a duration tag. The format of the time expression specified must comply with the time parsing routines provided by the java.text.TimeFormat class. If this tag is not used in conjunction with a date tag, the enclosing body of the duration tag defaults to use the date on which the job was submitted.

Use the following code to set the schedule duration to October 27, 2003 4:30 p.m. PST.

<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>

years

Use this unit tag in conjunction with either the duration or interval tag to specify the number of years to expiration. This tag can be used in conjunction with any of the other unit tags (months, weeks, days, hours, or 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. For example, February 29 would be rounded to February 28 of the following year.

Use the following code to set the schedule duration to one year from the time of submission.

<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>

The following example shows how to set the schedule interval to 1 year:

<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:interval> </s:schedule> </s:addJob></s:scheduler>

months

Use this unit tag in conjunction with either the duration or interval tag to specify the number of months to expiration. This tag can be used in conjunction with any of the other unit tags (years, weeks, days, hours, or minutes). The body of the tag must be a positive non zero integer. If the duration or interval occurs at the end of the month, some rounding may occur so that the interval remains at the end of the month. For example, January 31 would be rounded to February 28 of the following month.

Use the following code to set the schedule to expire after 1 month.

<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>

The following example shows how to set the schedule to repeat every 3 months.

<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:interval> </s:schedule> </s:addJob></s:scheduler>

weeks

Use this unit tag in conjunction with either the duration or interval tag to specify the number of weeks to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, days, hours, minutes, seconds, or milliseconds). The body of the tag must be a positive non zero integer.

Use the following code to set the schedule to expire after 1 week:

... <s:duration> <s:weeks>1</s:weeks> </s:duration>...

days

Use this unit tag in conjunction with either the duration or interval tag to specify the number of days to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, weeks, hours, minutes, seconds, or milliseconds). The body of the tag must be a positive non zero integer.

Use the following code to set the schedule to repeat every 14 days:

... <s:interval> <s:days>14</s:days> </s:interval>...

hours

Use this unit tag in conjunction with either the duration or interval tag to specify the number of hours to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, weeks, hours, minutes, seconds, or milliseconds). The body of the tag must be a positive non zero integer.

Use this code to set the schedule to expire after 48 hours:

... <s:duration> <s:hours>48</s:hours> </s:duration>...

minutes

Use this unit tag in conjunction with either the duration or interval tag to specify the number of minutes to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, weeks, hours, days, seconds, or milliseconds). The body of the tag must be a positive non zero integer.

Use the following code to set the schedule to repeat every 720 minutes:

... <s:interval> <s:minutes>720</s:minutes> </s:interval>...

seconds

Use this unit tag in conjunction with either the duration or interval tag to specify the number of seconds to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, weeks, hours, days, minutes, or milliseconds). The body of the tag must be a positive non zero integer.

Use the following code to set the schedule to expire after 86,400 seconds (24 hours):

... <s:duration> <s:seconds>86400</s:seconds> </s:duration>...

milliseconds

Use this unit tag in conjunction with either the duration or interval tag to specify the number of milliseconds to expiration. This tag can be used in conjunction with any of the other unit tags (years, months, weeks, hours, days, minutes, or seconds). The body of the tag must be a positive non zero integer.

Use the following code to set the schedule to repeat every 43,200,000 milliseconds:

... <s:interval> <s:milliseconds>43200000</s:milliseconds> </s:interval>...

C.3.2.3.2 interval

Use this helper tag to specify the interval of the schedule. This tag must be enclosed in a schedule tag. The body of this tag is used to specify the schedule interval. The interval is specified as an arbitrary number of units and associated values.

Some example intervals are:

1 week
1 month, 5 days
1 month, 6 days, 3 hours

Table C-6 describes the supported helper tags for the interval helper tag.

Table C-6 Helper Tags for the interval Helper Tag

Helper Tag	Required?	Description
`end`	No	End date of a repeating interval.
`years`	No	Repeating interval in years relative to the time at which the job is submitted. This tag may be combined with any other unit tag.
`months`	No	Repeating interval in months relative to the time at which the job is submitted. This tag may be combined with any other unit tag.
`weeks`	No	Repeating interval in weeks relative to the time at which the job is submitted. This tag may be combined with any other unit tag.
`days`	No	Repeating interval in days relative to the time at which the job is submitted. This tag may be combined with any other unit tag.
`hours`	No	Repeating interval in hours relative to the time at which the job is submitted. This tag may be combined with any other unit tag.
`minutes`	No	Repeating interval in minutes relative to the time at which the job is submitted. This tag may be combined with any other unit tag.

Use the end helper tag to specify an end date for a repeating interval. This tag must be enclosed in an interval tag. The interval is specified as an arbitrary number of units and associated values.

Use the following code to set an end date of 1 year for a monthly repeating interval:

<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:interval>
      </s:schedule>
   </s:addJob>
</s:scheduler>

Table C-7 describes the unit tags supported be the end helper tag.

Table C-7 Helper Tags for the end Helper Tag

Helper Tag	Required?	Description
`date`	No	Date on which the schedule ends. This tag can be combined with the `time` tag.
`time`	No	Time at which the schedule ends. This tag can be combined with the `date` tag.
`years`	No	End date in years relative to the time at which the job is submitted. This tag can be combined with any other unit tag.
`months`	No	End date in months relative to the time at which the job is submitted. This tag can be combined with any other unit tag.
`weeks`	No	End date in weeks relative to the time at which the job is submitted. This tag can be combined with any other unit tag.
`days`	No	End date in days relative to the time at which the job is submitted. This tag can be combined with any other unit tag.
`hours`	No	End date in hours relative to the time at which the job is submitted. This tag can be combined with any other unit tag.
`minutes`	No	End date in minutes relative to the time at which the job is submitted. This tag can be combined with any other unit tag.

These unit tags are used in the same manner as with the duration helper tag. For more information, see Section C.3.2.3.1.

C.3.2.3.3 threshold

Use this helper tag to specify the execution threshold of the schedule; if the schedule is not run before the specified threshold, the job is suppressed and will be retried only if a retry tag is specified. This tag must be enclosed in a schedule tag. The body of this tag is used to specify the schedule threshold. The threshold is specified as an arbitrary number of units and associated values.

Some example thresholds are:

1 day
10 hours, 26 minutes

Table C-8 describes the helper tags available for the threshold tag.

Table C-8 Helper Tags for the threshold Helper Tag

Helper Tag	Required?	Description
`days`	No	Threshold in days. This tag can be combined with any of the other unit tags.
`hours`	No	Threshold in hours. This tag can be combined with any of the other unit tags.
`minutes`	No	Threshold in minutes. This tag can be combined with any of the other unit tags.

These unit tags are used in the same manner as with the duration helper tag. For more information, see Section C.3.2.3.1.

C.3.2.4 trigger

Use this helper tag to specify the trigger for the job. This tag must enclosed in an addJob tag. The body is used to specify the associated expression for the trigger. If no trigger is specified, a default trigger is provided for execution based on the associated schedule's expiration.

Example:

<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>

C.3.2.5 retry

Use this helper tag to specify the retry period for the job. This tag must be enclosed in an addJob tag. The body of this tag is used to specify the retry period and is specified as an arbitrary number of units and associated values.

Table C-9 describes the supported helper tags for the retry helper tag:

Table C-9 Helper Tags for the retry Helper Tag

Helper Tag	Required?	Description
`months`	No	Retry period in months. This tag can be combined with any of the other unit tags.
`weeks`	No	Retry period in weeks. This tag can be combined with any of the other unit tags.
`days`	No	Retry period in days. This tag can be combined with any of the other unit tags.
`hours`	No	Retry period in hours. This tag can be combined with any of the other unit tags.
`minutes`	No	Retry period in minutes. This tag can be combined with any of the other unit tags.

If a job fails and you want it to retry in 1 hour and 30 minutes, then use the following code:

<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>

The unit tags described in Table C-9 are used in the same manner as with the duration helper tag. For more information, see Section C.3.2.3.1.

C.3.2.6 logLevel

Use this helper tag to set the log level for the job. This tag must be enclosed in an addJob tag. The body of this tag is used to specify the log level. The following values are supported:

WARNING

Logs a message each time a job results in a run time exception. This is the lowest logging level.
FINE

Logs a message each time a job begins and ends.
FINER

Logs a message each time the job's associated trigger is evaluated, and logs the result of the evaluation.
FINEST

Logs a message when the job completes, and logs the cumulative time it took to run This is the highest level of logging.

C.3.3 removeJob

Use this tag to remove an existing job from the Job Scheduler. This tag must be enclosed within a scheduler tag. Specify the oracle.ias.scheduler.Job bean instance name of the job you want to remove.

The name attribute is the only supported attribute for the removeJob tag. It is an optional attribute used to specify the bean instance name by which the associated job is accessed.

The following example shows how to remove a job named "job":

<%@ 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>

C.3.4 pauseJob

Use this tag to pause an existing job in Job Scheduler. This tag must be enclosed within a scheduler tag. Specify the oracle.ias.scheduler.Job instance name of the job you want to pause.

The name attribute is the only supported attribute for the pauseJob tag. It is an optional attribute used to specify the bean instance name by which the associated job is accessed.

The following example shows how to pause a job named job:

<%@ 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>

C.3.5 resumeJob

Use this tag to resume a job in Job Scheduler. This tag must be enclosed within a scheduler tag. Specify the oracle.ias.scheduler.Job instance name of the job you want to resume.

The name attribute is the only supported attribute for the resumeJob tag. It is an optional attribute used to specify the bean instance name by which the associated job is accessed.

The following example shows how to resume a job named job:

<%@ 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>

C.3.6 cancelJob

Use this tag to cancel an existing job in Job Scheduler. This tag must be enclosed within a scheduler tag. Specify the oracle.ias.scheduler.Job instance name of the job you want to cancel.

The name attribute is the only supported attribute for the cancelJob tag. It is an optional attribute used to specify the bean instance name by which the associated job is accessed.

The following example shows how to cancel a job named job:

<%@ 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>

C.3.7 addBlackoutWindow

Use this tag to add a blackout window to Job Scheduler. This tag must be enclosed within a scheduler tag

Table C-10 describes the helper tags supported by the addBlackoutWindow tag.

Table C-10 Helper Tags for the addBlackoutWindow Tag

Helper Tag	Required?	Description
`description`	Yes	Description of the blackout window.
`duration`	Yes	Duration of the blackout window.
`schedule`	No	Schedule for the blackout window; specifies when, how often, and for how long the blackout window is in effect. If no schedule is specified, the blackout window is effective starting at the time of submission.

The following example adds a blackout window lasting 2 hours, effective immediately:

<%@ 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>

C.3.8 removeBlackoutWindow

Use this tag to remove an existing blackout window from Job Scheduler. This tag must be enclosed within a scheduler tag.

The following example shows how to remove a an existing blackout window using the blackout window's description. (See Section C.3.7, where the blackout window was created).

<%@ 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>

C.4 JSP Tag Library Examples

This section contains more comprehensive examples illustrating the use of the various tags described in this chapter.

Example C-1 shows how to list all submitted jobs.

Example C-1 Listing All Submitted Jobs

<%@ taglib uri="scheduler-taglib" prefix="s" %>
<HTML>
<HEAD>
<TITLE>OracleAS Job Scheduler: all jobs</TITLE>
</HEAD>
<BODY>
<TABLE>
   <TR>
      <TH>Description</TH>
      <TH>Class Name</TH>
   </TR>
   <s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
      <s:jobIterator id="job">
         <TR>
            <TD><jsp:getProperty name="job" property="Description"/></TD>
            <TD><jsp:getProperty name="job" property="ClassName"/></TD>
         </TR>
      </s:jobIterator>
   </s:scheduler>
</TABLE>
</BODY>
</HTML>

Example C-2 shows how to submit a job to Job Scheduler. In this example, an HTTP request is sent to the JSP page. Once the request is processed, the JSP forwards the request to a status page. The parameters in the request are described in the following table:

Parameter	Description
`description`	Job description.
`class`	Job implementation class name.
`expirationDate`	Job schedule's expiration date.
`expirationTime`	Job schedule's time of expiration on the specified `expirationDate`.
`intervalDays`	Job schedule's repeat interval.

Example C-2 Submitting a Job to Job Scheduler

<%@ taglib uri="scheduler-taglib" prefix="s" %>
<jsp:useBean id="params" scope="request" class="RequestParametersBean" />    
<jsp:setProperty name="params" property="*" />
<HTML>
<BODY>
<s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
   <s:addJob>
      <s:description><jsp:getProperty name="params" property="description"/></s:description>
      <s:class><jsp:getProperty name="params" property="class"/></s:className>
      <s:schedule>
         <s:duration><jsp:getProperty name="params" property="expirationDate"/></s:duration>
         <s:interval><jsp:getProperty name="params" property="expirationTime"/></s:interval>
      </s:schedule>
   </s:addJob>
</s:scheduler>
<jsp:forward url="/JobScheduled.html"/>
</BODY>
</HTML>

Example C-3 shows how to remove a job from Job Scheduler. In this example, a job is removed based on its description and class. Once the job has been removed, the JSP forwards the request to a status page.

Example C-3 Removing a Job from Job Scheduler

<%@ taglib uri="scheduler-taglib" prefix="s" %>
<HTML>
<BODY>
<s:scheduler id="scheduler" name="java:comp/env/ejb/scheduler">
   <s:jobIterator id="job" desc="description of job to remove" class="test">
      <s:removeJob/>
   </s:jobIterator>
</s:scheduler>
<jsp:forward url="/JobRemoved.html"/>
</BODY>
</HTML>