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:

• A cron-like calendar.
• A simple arithmetic calendar.

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:

• *
  This indicates all values are acceptable. The interval simply includes all valid numbers.
• 1,4,7
  This indicates only the specified values are acceptable.
• 1-4,10-20,25
  Ranges can be specified for the comma delimited terms.
• 4/5
  This indicates all values starting at 4 incrementing by 5 at a time up to the maximum permissable value. For example, for hours, the resulting sequence is [4,9,14,19,4,9,...]
• 1-10/3
  This indicates all numbers inside the range skipping 3 at a time, in this example, this is [1,4,7,10].

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.

• 0 0 18 ? SEP MON-FRI
  This means at 1800 hours from Mon to Fri during Sept only. Note the day of month is a '?' as we specified a day of week.
• 0 0 18 L * ?
  This means 6pm on the last day of every month (Jan 31, feb 28, Mar 31, etc) taking in to account leap years also.
• 0 1/17 9-18 ? * MON-FRI
  This means from Monday to Friday from 9 until 1800 hours every 17 minutes starting at the first minute (9:01,9:18,9:35,9:52,10:01 etc). Note that ? was used for the day of month as we specified a day of week. It's also important to note that this isn't every 17 minutes minutes during 9-18 hours. For each hour periond, it's every 17 minutes starting at 1 minute but we reset back to 1 once we exhaust all values within the hour. So it's every 17 minutes within an hour but not over the range. The final period of the hour is 9 minutes (9:52 -> 10:01)

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:

• ms
  Add x milliseconds to the base date.
• seconds
  Add x seconds to the base date.
• minutes
  Add x minutes to the base date.
• hours
  Add x hours to the base date.
• days
  Add x days to the base date.
• months
  Add x months to the base date.
• years
  Add x years to the base date.

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

• 10minutes
  Every 10 minutes.
• 1hours
  Every hour. Note the term 'hours' is used even when 1 is the number. The term types are always plural
• 20minutes 1hours
  Every hour and twenty minutes.
• 5seconds 5minutes 1hours 2days 1months 1years
  Add each term from left-to-right to the base time.

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

Methods

Modifier and Type	Method and Description
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