Using a Timer Control

This topic describes how to configure and use an existing Timer control.

To learn how to create a Timer control, see Creating a New Timer Control.

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

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

# Using a Timer Control

There are three aspects to using a Timer control:

- Configure default Timer control behavior using the timer property

- Control the behavior of the Timer control using the methods of the TimerControl interface to start, stop or configure it.

- Respond to timer events by handling callbacks from the Timer control.

Each of these aspects are described in the following sections.

## Setting Default Timer Control Behavior

You can set the initial behavior of a Timer control using the control's timeout and repeats-every properties. For example, if you select a Timer control instance named delayTimer in Design View, the Properties Pane displays the following properties:

In the JWS file, the property values are expressed as attribute values associated with the @jws:timer tag. The @jws:timer tag has the following attributes:

- timeout, which specifies the time until the Timer control fires the first time, once started

- repeats-every, which specifies how often the Timer control should fire after the first time

- coalesce-events, which specifies how the Timer control should behave if delivery of its events is delayed

Note: The properties of a Timer control set the Timer control's initial behavior. The weblogic.jws.control.TimerControl class exposes methods that may be used to change the Timer control's behavior after it is created. See Using Methods of the TimerControl Interface below.

To learn more about specifying default Timer control behavior with attributes of the @jws:timer tag, see @jws:timer Tag.

## Using Methods of the TimerControl Interface

Once you have declares and configured a Timer control, you can invoke its control's methods from within your web service's methods and implement handlers for the Timer control's callbacks.

Brief descriptions of each method are provided below. For complete information on each method, see TimerControl Interface.

### Basic Timer Control Methods

The methods of the TimerControl interface that are most commonly called are:

- start: starts timer operation. The Timer control will fire after the period specified by the timeout attribute has passed.

- restart: resets the Timer control such that the next firing will occur after the period specified by the timeout attribute has passed.

- stop: stops the Timer control from firing again until start or restart has been called.

### Timer Control Configuration Methods

In addition to the methods listed above, the TimerControl interface also defines the following methods that may be used to configure a Timer control. Each method sets or gets the value of the attribute named in the method name.

- setTimeoutAt

- getTimeoutAt

- setTimeout

- getTimeout

- setRepeatsEvery

- getRepeatsEvery

- setCoalesceEvents

- getCoalesceEvents

## Handling Timer Control Callbacks

The Timer control defines one callback:

- onTimeout

The purpose of a Timer control is to notify a web service when a specified time period has elapsed or an absolute time has been reached. The Timer control delivers this notification using its onTimeout callback. You receive the callback by implementing a callback handler named timerName_onTimeout, where timerName is the name of the Timer control instance.

The callback has a single parameter that is the time at which the callback was scheduled. Note that this is not the same as the time at which the callback handler executes. A delay may occur between Timer control expiration and callback handler invocation due to system load.

### Creating a Timer Control Callback Handler Automatically

WebLogic Workshop will create the skeleton of a Timer control's callback handler for you. To create a skeleton callback handler for a Timer control's onTimeout callback, click the onTimeout link associated with the Timer control in Design View, as shown here:

If a callback handler does not exist for the selected callback, WebLogic Workshop creates one, switches to Source View, and places the cursor in the callback handler for the selected callback.

In the example above, the callback handler will be named delayTimer_onTimeout.

Related Topics

Creating a New Timer Control

Add Timer Control Dialog

Specifying Time on a Timer Control

TimerControl Interface