bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Time Services

Programming WebLogic Time Services (Deprecated)

The WebLogic Time API provides a mechanism for scheduling actions (triggers) to take place at a future date and time, or on a regularly recurring schedule. The following sections provide an introductiont to the Time Services features:

- Time Services Deprecated

- Overview

- WebLogic Time Architecture

- WebLogic Time API

Time Services Deprecated

WebLogic Time Services were deprecated in WebLogic Server Version 6.1. See J2EE Scheduling Tools in WebLogic Server Tools for third-party scheduling services.

BEA Systems, Inc. recommends you use the implementation of the JMX timer service, javax.management.timer.Timer, included with WebLogic Server. For information and documentation, see JavaTM Management Extensions (JMX).

Overview

The Time API allows any user-written trigger to be scheduled and then executed, either in the client JVM, or on WebLogic Server on behalf of a client. The Time API provides a dependable, distributable method of setting up actions that occur automatically.

Note: Although you can use the time service with individual WebLogic Server instances in a cluster, the service itself is non-clusterable. The WebLogic Time API does not make use of cluster features such as load balancing and failover.

WebLogic Time Architecture

WebLogic Time is a lightweight, efficient API that shares many characteristics of other WebLogic Server APIs. WebLogic Time is built around a ScheduledTriggerDef object, constructed from a Schedulable object. The ScheduledTriggerDef object is responsible for starting, stopping, or repeating the action schedule. A Triggerable object defines the action to be carried out on schedule. You use an object factory to create a ScheduledTrigger. Object factories provide a well-defined, easy-to-use methodology for managing scarce resources within WebLogic Server.

Accounting for scheduling is kept in a series of efficient linked lists that are sorted only at the most proximate chronological point as new triggers are scheduled and then acted upon. For example, a trigger for a week from Tuesday at 12:15:30 is initially inserted into the schedule for next Tuesday. Not until noon on Tuesday is the schedule for the noon hour sorted, and not until fifteen minutes past noon are the triggers for that minute sorted. This drastically reduces the overhead for scheduling in a heavily scheduled environment.

WebLogic Server also keeps accounting of the differences in time zone, clock accuracy, and latency between users of the Time service. Note that WebLogic triggers are not real time triggers that can be used to millisecond granularity. WebLogic triggers used properly will function reliably within an estimated 1 second of accuracy.

WebLogic Time API

A ScheduledTrigger takes two objects in its constructor:

- An object that implements either weblogic.time.common.Schedulable or weblogic.time.common.ScheduleDef

- An object that implements either weblogic.time.common.Triggerable or weblogic.time.common.TriggerDef

An object passed to the ScheduledTrigger object factory method may also be a client-side object, in which case the client creates, schedules, and executes a ScheduledTrigger within its own JVM. The client-side object must implement Schedulable (or ScheduleDef) and Triggerable (or TriggerDef).

The TimeServicesDef interface also provides methods for obtaining time-related information about client and server:

- currentTimeMillis() returns the current server time, in "local server time" format, which is the server's time adjusted for propagation delay between the method invoker and the server (zero when the method invoker is the server, and some positive milliseconds when the invoker is the client or another WebLogic Server).

- getRoundTripDelayMillis() returns the number of milliseconds of round-trip delay between the client and server. This method depends on the algorithm described in the overview.

- getLocalClockOffsetMillis() returns the number of milliseconds of offset between the client and server clocks, based on the algorithm described in the overview.

The weblogic.time.common.TimeRepeat class implements Schedulable. This utility class is a prefabricated scheduler you can use to set up a repeating trigger. Just pass an int that is the interval (in milliseconds) at which the trigger should repeat. Then call its schedule() method with the starting time.

Warning: If your trigger throws an exception, it is not rescheduled. This is to ensure that a failing trigger is not re-executed indefinitely. If you want to reschedule a trigger after an exception, you must catch the exception and schedule the trigger again.

The package contains a single exception class, TimeTriggerException.