IBM WebSphere Application ServerTM
Release 8

com.ibm.websphere.scheduler
Interface UserCalendar

All Superinterfaces:
javax.ejb.EJBObject, java.rmi.Remote

public interface UserCalendar
extends javax.ejb.EJBObject

The remote interface for all UserCalendar stateless session beans. All calendars are required to use this remote interface and the be com.ibm.websphere.scheduler.UserCalendarHome home interface.

One calendar session bean can implement one or more physical calendars. Each calendar implementation is identified using a the calendar specifier string. The calendar specifier for the supplied default calendars are not case sensistive. It is recommended that all UserCalendar implementations use case insensitive calendar specifiers.

The default UserCalendar supplied with the WebSphere Scheduler implements two types of calendars:

The default calendar is accessed in one of two ways:
  1. When creating a TaskInfo object, if the setUserCalendar is not set, then the default UserCalendar described here is implied.
  2. Lookup the default UserCalendar using the JNDI name: com/ibm/websphere/scheduler/calendar/DefaultUserCalendarHome
CRON Calendar
The CRON calendar is named 'CRON'. When the calendar specifier string is CRON then the interval is calculated using a cron based scheme. A cron based interval looks like a list of term expressions seperated by spaces or tabs. Each term represents an element of the time. The element describes the valid values for that term. The next time is calculated by moving the lowest term to the next valid value for that term. If the value wraps then we move up to the next term and do the same.

Note that whilst seconds can be specified, the scheduler is not designed to be accurate to the second so we only recommend intervals at least a minute apart. We therefore recommend the seconds term is always 0

second minute hourOfDay DayOfMonth Month DayOfWeek

All terms except for day of week are very similar in syntax. Here are examples of the syntax:

The numbers can be replaced with symbols. The month term can be one of JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV or DEC. Example:

FEB,JAN-DEC/3 is the same as [JAN,FEB,APR,JUL,OCT]

The day of week and day of month terms cannot be specified at the same time. One must be a '?' and the other a term.

Examples of intervals.

If desired then multiple cron expressions can be concatenated if seperated by the '|' vertical bar character. This allows the next valid time from a set of cron expressions to be returned. This is useful when different times are needed during weekdays and weekends. For example:

0 0 8 ? * MON-FRI | 0 0 10 ? * SAT,SUN

The next time is calculated for each of the cron expressions and the first occuring time is chosen as the next time.

When combining multiple calendars using the bar operator then some complex interactions can occur. It's recommended that you write a simple client of the user calendar that prints out the various times it would fire to make sure that the event times are what you expect.

SIMPLE Arithmetic Calendar
The default calendar is named 'SIMPLE'. When the calendar specifier string is absent or 'SIMPLE' then the interval is calculated using a simple java.util.Calendar based scheme.

The interval for the simple calendar is applied to the base java.util.Date object and consists of a set of space-delimited terms and is evaluated from left to right using the default java.util.Calendar.add() instance method for the current locale.

Each term has the form NNNNNtype, where NNNN is an integer and type indicates one of the following values:

Examples of these sorts of intervals are (note there are no spaces between the number and the type string):

Note that since each term is processed in order from left to right, the order of the term sequence directly affects the final date result. For example, if applying "1months 2days" to January 29, 2003, the result will be March 2nd, 2003 (Jan 29 + 1 month is Feb 28 + 2 days is March 2nd). If you instead apply "2days 1months" to January 29, 2003, the result is now February 28th, 2003 (Jan 29 + 2 days is Jan 31 + 1 month is Feb 28).

Since:
5.0
Version:
5.0

Method Summary
 java.util.Date applyDelta(java.util.Date baseTime, java.lang.String calendar, java.lang.String delta)
          Returns the result of applying the supplied interval to the base time.
 java.lang.String[] getCalendarNames()
          Retrieves an array of valid calendar names that this UserCalendar implementation supports.
 void validate(java.lang.String calendar, java.lang.String delta)
          Used to validate a calendar interval.
 
Methods inherited from interface javax.ejb.EJBObject
getEJBHome, getHandle, getPrimaryKey, isIdentical, remove
 

Method Detail

validate

void validate(java.lang.String calendar,
              java.lang.String delta)
              throws UserCalendarSpecifierInvalid,
                     UserCalendarPeriodInvalid,
                     java.rmi.RemoteException
Used to validate a calendar interval. Both the calendar specifier and the calendar interval are supplied. An exception is thrown is there is a problem. Usually this method simply calls the applyDelta method with the time now.

Parameters:
calendar - the calendar specifier. This uniquely identifies a physical calendar within this session bean.
delta - the interval string. The syntax of this is completely dependant on the calendar.
Throws:
UserCalendarSpecifierInvalid - thrown if the specified calendar was unknown.
UserCalendarPeriodInvalid - thrown if the interval string cannot be parsed as valid.
java.rmi.RemoteException
Since:
5.0

applyDelta

java.util.Date applyDelta(java.util.Date baseTime,
                          java.lang.String calendar,
                          java.lang.String delta)
                          throws UserCalendarSpecifierInvalid,
                                 UserCalendarPeriodInvalid,
                                 java.rmi.RemoteException
Returns the result of applying the supplied interval to the base time.

Parameters:
baseTime - the time from which we want to add the interval.
calendar - the calendar specifier. This uniquely identifies a physical calendar.
delta - the interval string. The syntax of this is completely dependant on the calendar.
Throws:
UserCalendarSpecifierInvalid - thrown if the specified calendar was unknown.
UserCalendarPeriodInvalid - thrown if the interval string cannot be parsed as valid.
java.rmi.RemoteException
Since:
5.0

getCalendarNames

java.lang.String[] getCalendarNames()
                                    throws java.rmi.RemoteException
Retrieves an array of valid calendar names that this UserCalendar implementation supports.

Returns:
the array of calendar names.
Throws:
java.rmi.RemoteException
Since:
5.0

IBM WebSphere Application ServerTM
Release 8