Creating and Configuring a Basic Timer Control

When you create a timer control, Workshop also inserts a line at the top of your .java file to import the timer control class, com.bea.control.TimerControl.

Note that you cannot create a new timer control in a page flow or a Java Server Page (JSP file), because the timer control defines a callback, the onTimeout method, but page flow and JSP pages cannot accept callbacks.

Before using a timer control, you must specify when the timer elapses. If you do not specify when the timer elapses, the timer control will time out immediately (i.e., it will default to zero seconds). Elapsed time is specified in an additional annotation @TimerControl.TimerSettings() that is inserted into your code. Typically you will not edit the annotation manually but instead will use the Properties view to set property values.

Specifying Relative Timer Values through the Properties View

For relative times, you can specify the timeout or the repeated time interval from the Properties view, which is available in the J2EE perspective. Absolute times must be specified by calling the control's method(s) as described in Setting an Absolute Timer with a Method Call.

To set a relative timeout or recurring time interval:

From the editor window, as long as the control name is highlighted, the Properties view at the right displays the properties of the new control. To set a relative timeout, click the timeout or timeoutSeconds field and enter the amount of time you want to elapse before the timer fires. This timer will elapse only once. The time value is a string, as described below.
To set a recurring timer, in the repeatsEvery or repeatsEverySeconds field, specify the interval between firings after the timer fires the first time. The time value is a string, as described below.

Note that you should set ONLY ONE of timeout, timeoutSeconds and only ONE of repeatsEvery, or repeatsEverySeconds. If you set both values, the xxxSeconds value will be used.

Entering Relative Time Value Strings

When entering timeout or recurring time values, you must specify the relative time as a text string--integers followed by case-insensitive time units. These time units can be separated by spaces.

For example,

1 hour 30 min

means one hour and 30 minutes and

30 s

means 30 seconds.

The following time string is a valid duration specification that exercises all the time units, spelled out fully:

99 years 11 months 13 days 23 hours 43 minutes 51 seconds

This example creates a timer control which will elapse in almost 100 years.

Units may also 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.

Text strings may also be in ISO 8601 extended format with the string "p" (case insensitive) at the beginning of a text string. 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. (http://www.w3.org/TR/xmlschema-2/#duration)

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

P99Y11Mo13D23H43M51S

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 28 in a normal year, February 29 in a leap year).

Using the Properties of the TimerControl Interface

The timer control interface has three properties:

timeoutAt: initial timeout interval (date)
isRunning: tests if the timer control is currently running (boolean)
payload: extra data that you can set before starting a timer; this data is passed back to the event handler during each timeout event (serializable)

Property	Type	Getter	Setter	Description
timeoutAt	Date	Date getTimeoutAt()	void setTimeoutAt(Date arg0)	Initial timeout interval (relative time). Format is java.util.Date.
isRunning	boolean	boolean isRunning()		Whether the timer control is currently running (true=running, false=stopped).
payload	Serializable	Serializable getPayload()	void setPayload(Serializable arg0)	Extra data to be passed back to the event handler in each timer callback.

Setting a Timer Payload with a Method Call

To set a payload that will be supplied to the callback handler during a timeout event, call the

setPayload(Serializable payload)

method before starting the timer. Calling this method after the timer is started will have no effect. Since the payload is serializable, you must be careful that the class that the serializable represents still exists, so that the object can be deserialized.

Setting an Absolute Timer with setTimeoutAt()

You can configure a timer control to fire at an absolute time by setting the TimeoutAt property of the TimerControl interface by calling setTimeoutAt().

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

The getTimeoutAt method returns the time at which the timer is next scheduled to fire, if the repeats-every attribute is set to a value greater than zero. If the repeats-every attribute is set to zero, then the getTimeoutAt method returns the value set by the setTimeoutAt method or the value set in the timeout attribute. If you call the getTimeoutAt method from within the onTimeout callback handler, the first timeout has already fired, so getTimeoutAt will return either the time of the next timeout or the time of the first timeout if the timer is not set to repeat.

The following code snippet calls the setTimeoutAt method to specify that the first timeout fires at thirty seconds past the current minute, then calls the setRepeatsEvery method to specify that the timer subsequently fires every sixty seconds.

@Control
private TimerControl tTimer;

@WebMethod()
@Conversation(value= Conversation.Phase.START)
public void StartTimer()
{
    Calendar cd = new GregorianCalendar();
    cd.set(cd.SECOND, 30);
    tTimer.setTimeoutAt(cd.getTime());
    tTimer.setRepeatsEvery(60);
    tTimer.start();
}

Setting Other Timer Control Behavior

You can specify other settings of a timer control in J2EE perspective by setting the control's properties in the Properties view. For example, if you highlight the name of the timer control instance named _timer in the code editor, the Properties view displays the control's properties.

These properties correspond to attributes of the @TimerControl.TimerSettings annotation, which identifies the timer control in your code. The @TimerControl.TimerSettings annotation has the following properties:

Property	Description/Values
timeout	Time until the timer control fires the first time, once started (default: 0 seconds).
timeoutSeconds	Time in seconds until the timer control fires the first time, once started (default: 0).
repeatsEvery	How often the timer control should fire after the first time (default: 0 seconds i.e., non-recurring).
repeatsEverySeconds	How often the timer control should fire after the first time (default: 0 i.e., non-recurring).
coalesceEvents	Specifies whether multiple undelivered firing events of a Timer control are delivered as a single onTimeout (true) or as separate callbacks (false). Default: true. At times, a Timer control may be unable to deliver one or more callbacks to its referring service. This may occur because the referring service is busy or because high system load delays delivery. A set of undelivered callbacks may accumulate. If the coalesceEvents attribute is true, these accumulated callbacks are collapsed into a single callback when the service becomes available. If coalesceEvents is false, the accumulated callbacks are delivered individually.
transactional	True if timers participate in transactions and are durable (default: true).
jndiContextFactory	JNDI context factory class (default: none).
jndiProviderURL	JNDI provider URL (default: none).

Understanding the Timer Control Declaration

When you create a new timer control, its declaration appears in the source file. The following code snippet is an example of what a typical timer control declaration looks like:

import com.bea.control.TimerControl;
...
@TimerControl.TimerSettings(repeatsEverySeconds=5)
@Control
private TimerControl delayTimer;

The actual attributes that are present on the @TimerControl() annotation depend on the values you specify for the properties in the Properties view.

The @Control annotation informs Workshop that the associated declaration is a control. Without this annotation, the control is not properly connected to supporting code and will not function.

The @TimerControl() annotation controls the behavior of the timer control. All of the attributes of the @TimerControl() annotation are optional and have default values.

The timer control, named delayTimer in the example above, is declared as an instance of TimerControl.