Using a Timer Control

IDE Commands to Work with Timer Control

To insert a timer control, right click on the code editor and choose Insert > Control.

To insert a timer control using the TimerControlBean:

  1. Right click on the code editor and choose Insert > Control.
  2. Manually edit the annotation to change TimerControl to TimerControlBean.
  3. Do the required import for TimerControlBean by right clicking on the problem marker in the marker bar beside the annotation line and choosing Quick Fix. Use the Quick Fix menu to do the necessary import for TimerControlBean.

To display the properties of the timer control (or timer control bean) in the Properties view,

  1. Be sure that J2EE perspective is open (as displayed just below the toolbar at the top of the workbench window); if it is not open, click Window > Open Perspective to open J2EE perspective.
  2. Double click on the timer control (or bean) name. The properties of the annotation will be displayed in the Properties view.

The IDE does not validate time strings that are entered in the Properties view. Times are validated only at run-time.

Requirements for Web Services that use a Timer Control

Timer controls can only be used within a web service that is conversational and implements Serializable. See Designing Conversational Web Services for more information.

TimerControl Annotation

See the TimerControl.TimerSettings annotation for a description of the annotations to set timer control parameters

The TimerControl Interface

The following properties and methods are provided on the TimerControl interface.

Properties

Property Type Getter Setter Description
running boolean boolean isRunning()   Tests if the timer is currently running.
timeoutAt Date Date getTimeoutAt() void setTimeoutAt(Date arg0) Initial timeout (absolute date);date is java.util.Date. Calling setTimeoutAt() replaces any existing relative timer with the specified absolute time. Setting an absolute date in the past causes an immediate callback.
payload Serializable Serializable getPayload() void setPayload(Serializable arg0) Extra data that is passed back to event handler on a callback. If you specify a payload, be sure that when the timer callback occurs, the object still exists, since the payload is serializable.

Methods

There are three methods for TimerControl.

Method Description
void start()

Starts timer operation. The timer control will fire after the period specified by the timeout, timeoutSeconds, repeatsEvery or repeatsEverySeconds attribute has passed. The start() method can be called in either the START or CONTINUE phase of the conversation.

Calling the start() method a second time on a timer has no effect. If a timer has been stopped, calling start() starts the timer again.
void stop()

Stops the timer control from firing again. Calling start() will start the timer again. The stop() method can be called in either the FINISH or CONTINUE phase of the conversation. Be sure to call the stop() method when the conversation ends. Note that if you do not call the stop() method, the container will automatically terminate the timer for you.

Calling the stop() method for a stopped event timer does not generate an exception. Calling the stop() method more than once on a timer does not generate an exception.
void restart() Stops the timer control and starts it again. This method is only useful when working with relative timeout or recurring time intervals, since the timer is restarted with the same parameters.

Events

There is one event generated by the timer control

Event   Description
onTimeout void callback(long timeout, Serializable payload) Occurs when the timer expires.

TimerControlBean

TimerControlBean implements the TimerControl interface and provides the following additional methods and properties.

Properties

Property Type Getter Setter Description
coalesceEvents boolean boolean isTimerSettingCoalesceEvents() void setTimerSettingCoalesceEvents(boolean arg0) Whether the timer control is set to use the coalesce method for recurring events.
transactional boolean boolean isTimerSettingTransactional() void setTimerSettingTransactional(boolean arg0) Whether the timer control is currently running in transactional mode.

Methods

The following additional methods are provided to get/set the property values displayed in the Properties view:

Method Description
String getTimerSettingJNDIContextFactory() Returns the JNDI Context Factory.
String getTimerSettingJNDIProviderURL() Returns the JNDI Provider URL.
String getTimerSettingRepeatsEvery() Returns the relative time string for the recurring timer setting.
Long getTimerSettingRepeatsEverySeconds() Returns the number of seconds for the recurring timer.
String getTimerSettingTimeout() Returns the relative time string for the timeout.
Long getTimerSettingTimeoutSeconds() Returns the number of seconds for the timeout.
void setTimerSettingJNDIContextFactory(String arg0) Sets the JNDI Context Factory.
void setTimerSettingJNDIProviderURL(String arg0) Sets the JNDI Provider URL.
void setTimerSettingRepeatsEvery(String arg0) Sets the recurring timer by specifying a relative time string.
void setTimerSettingRepeatsEverySeconds(Long arg0) Sets the recurring timer to the specified number of seconds.
void setTimerSettingTimeout(String arg0) Sets the relative timeout to the relative time string.
void setTimerSettingTimeoutSeconds(Long arg0) Sets the relative time to the specified number of seconds.

Note that the setTimerSettingxxx methods have no effect if the timer is already started. To set time values, you must stop the timer, call the method to set the value, and start the timer. This will not create a new timer object, but will simply restart the existing control.

If both repeatEverySecond and repeatEvery are set, the timer does not generate an error, it uses the repeatEverySecond value.

If both timeout and timeoutSeconds are set, the timer does not generate an error, it uses the timeoutSeconds value.

Setting an absolute date in the past or a negative time value in either the setTimeout or setTimeoutSeconds methods causes an immediate callback.

The getTimerSettingxxx methods work whether the timer is running or stopped.

The following methods are for internal use only and should NOT be used:

Methods for Internal Use Only
getCallbackListener
addCallbackListener
removeCallback
removeCallbackListener
getControlImplementation
setControlImplementation

Events

There are no additional events generated by TimerControlBean.

Relative and Absolute Time Strings

Relative Time Strings

Relative time values are used for relative timeouts and for recurring times. Relative time values are set either through the Properties view or by calling a method on TimerControlBean.

Relative time is expressed as a text string, it is formatted as integers followed by case-insensitive time units. These time units can be separated by spaces. For example, the following code sample is a valid duration specification that exercises all the time units, spelled out fully:

@TimerControl.TimerSettings(timeout="99 years 11 months 13 days 23 hours 43 minutes 51 seconds") 
@Control()
Timer almostCentury;

This example creates a timer control whose default initial firing will occur 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:

@TimerControl.TimerSettings(timeout="P99Y11Mo13D23H43M51S")
@Control()
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).

Absolute Time Strings

To specify that the timer fires at a specific (absolute time), you must use the setTimeoutAt method.

Absolute time is useful when you know the exact moment you want operations to begin and end. For example, your application can have your web service send a reminder email to remind you that someone's birthday is coming up. Specific times are set as for with a java.util.Date object (Java 1.5). Since the TimerSetting annotation does not allow you to specify a timeout in java.util.Date format, you must use the setTimeoutAt method. For more information, see Using Methods of the TimerControlBean Interface to Set Parameters.

Methods on TimerControl for Backward Compatibility

An additional group of methods are provided on the TimerControl interface to provide backward compatibility with WebLogic Workshop 8.1 applications. These methods are no longer recommended. The backward compatibility methods are:

Method Description
long getTimeout() Get the current relative timeout value.
String getRepeatsEvery() Returns the recurring time interval in ISO 8601 format (Pxxx).
boolean getCoalesceEvents() Returns whether the timer is running in coalesced or non-coalesced mode. Deprecated.
void setCoalesceEvents(boolean coalesce) Turns on coalesced mode.
void setRepeatsEvery(long seconds) Sets the recurring timer by specifying a recurring time in seconds.
void setRepeatsEvery(String interval) Sets the recurring timer to the specified interval string.
void setTimeout(String arg0) Sets the relative timeout to the relative time string.
void setTimeout(long seconds) Sets the relative time to the specified number of seconds.

In WebLogic Workshop 8.1, a call to the start() method on a timer that was already started could potentially generate new timer events. In Workshop 9.2, 10.x, calling start() on a timer control that has already been started has no effect.

Caveats and Implementation Notes

The file weblogic_timer_control.jar contains the implementation of the timer control. This file defines the control interface and implementation and a stateless session bean. This JAR is deployed automatically when a web services project is created.

The timer control implementation is provided by com.bea.wlw.control.timer.EjbTimerControlImpl which uses the EJB 2.1 Timer Service. A control bean delegates the creation and canceling of timers through the stateless session bean, using an EJB Local interface. When a timer is expired, the ejbTimeout method on the session bean will be invoked by the EJB container. The ejbTimeout method in turn retrieves the ControlHandle that was stored with the timer when the timer was created, and uses the ControlHandle to dispatch the callback event to the target TimerControl. This implementation is agnostic of what container the TimerControl is running in.

Since timer controls are based on the EJB 2.1 timer service, they are a best-effort to do a callback to the client as requested, not a true real-time time service.

 

Still need help? Post a question on the Workshop newsgroup.