Specifying Time on a Timer Control

This topic describes how to specify relative and absolute time values for a Timer control.

To learn more about controls, see Controls: Using Resources from a Web Service.

To learn about the Timer control, see Timer Control: Using Timers in Your Web Service.

To learn about configuring and using a Timer control, see Using a Timer Control.

# Specifying Relative Time

You need to specify relative time periods whenever you are:

- setting the values of the timeout or repeats-every attributes of the @jws:timer tag.

- calling the setTimeout or setRepeatsEvery methods of the TimerControl interface.

When expressed as a text string, the format of relative time specifications is:

- Integers followed by time units (which are listed below), optionally truncated, case insensitive, and optionally separated by spaces.

- the string "p" (case insensitive) is allowed at the beginning; if it is present, then single-letter abbreviations and no spaces must be used and parts must appear in the order y m d h m s.

For example, the following code smaple is a valid duration specification that exercises all the time units, spelled out fully:

    /**
     * @jws:control
     * @jws:timer timeout="99 years 11 months 13 days 23 hours 43 minutes 51 seconds"
     */
    Timer almostCentury;

This example creates a Timer control whose default initial firing will occur in almost 100 years.

Units may be truncated, for example: valid truncations of "months" are "month", "mont", "mon", "mo", and "m". If both months and minutes are specified, use long enough abbreviations to be unambiguous.

The following Timer control declaration is equivalent to the previous example, but uses the fully truncated form:

    /*
     * @control
     * @timer timeout="P99Y11Mo13D23H43M51S"

     */
    Timer almostCentury;

Durations are computed according to Gregorian calendar rules, so if today is the 17th of the month, 3 months from now is also the 17th of the month. If the target month is shorter and doesn't have a corresponding day (for example, no February 31), then the closest day in the same month is used (for example, February 29 on a leap year).

# Specifying Absolute Time

You can configure a Timer control to fire at an absolute time by calling the setTimeoutAt methods of the TimerControl interface.

The setTimeoutAt method configures the timer to fire an event as soon as possible on or after the supplied absolute time. If you supply an absolute time in the past, the timer will fire as soon as possible.

If setTimeoutAt is called within a transaction, its effect (any work performed in the callback handler) is rolled back if the transaction is rolled back, and its effect is committed only when the transaction is committed.

If setTimeoutAt is called while the timer is already running, it will have no effect until the timer is stopped and restarted.

The setTimeoutAt method takes as its argument a java.util.Date object. Please see the documentation for the java.util.Date class to learn how to manipulate Date objects. Other Java classes that are useful when dealing with Date are java.util.GregorianCalendar and java.text.SimpleDateFormat.

Related Topics

Timer Control: Using Timers in Your Web Service