one.world.util
Class Timer

java.lang.Object
  |
  +--one.world.core.Component
        |
        +--one.world.util.Timer

All Implemented Interfaces:

Serializable

public final class Timer

extends Component

Implementation of a timer. A timer is a component that provides event notification based on time. Notification can be once or periodically, in which case it can be either fixed rate or fixed delay, as described for java.util.Timer.

This component exports a request event handler that accepts timer events requesting to schedule timed notification(s). This event handler is forcibly linked through a concurrency domain to ensure that timer notifications complete quickly. This component also provides a synchronous interface through the schedule(int, long, long, one.world.core.EventHandler, one.world.core.Event) method.

Unlike other resources in one.world, the timed notification provided by this component is not leased and, if it is periodic, must be explicitly canceled. As a result, this component can be used to implement leases.

If a timed notification results in an exceptional condition other than a NoBufferSpaceException, any future notification is automatically canceled. Furthermore, if the event handler receiving timed notification is currently not active (as determined by Domain.isActive(one.world.core.EventHandler)), the notification is silently dropped.

Note that each environment has its own timer component, which can be accessed through Component.getTimer().

Imported and Exported Event Handlers

Exported event handler(s):

request

Handles timer events requesting the scheduling of timed notifications.

Version:

$Revision: 1.25 $

See Also:

Serialized Form

Inner Class Summary

static class	Timer.Event Definition of a timer event.
static class	Timer.Notification The notification handler.

Inner classes inherited from class one.world.core.Component

Component.HandlerReference, Component.Importer

Field Summary

static int	CANCEL The type code for canceling a timer.
static int	CANCELED The type code for a canceled timer.
static int	FIXED_DELAY The frequency code for a fixed delay timer.
static int	FIXED_RATE The frequency code for a fixed rate timer.
static int	ONCE The frequency code for a one-time timer.
static int	SCHEDULE The type code for scheduling a timer.
static int	SCHEDULED The type code for a scheduled timer.

Constructor Summary

Timer(Environment env)
Create a new instance of Timer.

Method Summary

ComponentDescriptor	getDescriptor() Get the component descriptor.
Timer.Notification	schedule(int frequency, long firstTime, long period, EventHandler handler, Event event) Synchronously schedule timed notification(s).

Methods inherited from class one.world.core.Component

declareExported, declareImported, equals, eventHandlers, getDescriptor, getEnvironment, getLinkedHandlers, getLinkedNumber, getTimer, hasEventHandler, hashCode, isFullyLinked, isLinked, isSealed, link, link, run, seal, unbox, undeclare, unlink, wrap

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

SCHEDULE

public static final int SCHEDULE

The type code for scheduling a timer.

SCHEDULED

public static final int SCHEDULED

The type code for a scheduled timer.

CANCEL

public static final int CANCEL

The type code for canceling a timer.

CANCELED

public static final int CANCELED

The type code for a canceled timer.

ONCE

public static final int ONCE

The frequency code for a one-time timer.

FIXED_RATE

public static final int FIXED_RATE

The frequency code for a fixed rate timer.

FIXED_DELAY

public static final int FIXED_DELAY

The frequency code for a fixed delay timer.

Constructor Detail

Timer

public Timer(Environment env)

Create a new instance of Timer.

Parameters:

env - The environment for the new instance.

Method Detail

getDescriptor

public ComponentDescriptor getDescriptor()

Get the component descriptor.

Overrides:

getDescriptor in class Component

Following copied from class: one.world.core.Component

Returns:

The component descriptor for this component.

schedule

public Timer.Notification schedule(int frequency,
                                   long firstTime,
                                   long period,
                                   EventHandler handler,
                                   Event event)

Synchronously schedule timed notification(s). The event to signal notification(s) must be a valid event.

Parameters:

frequency - The frequency.

firstTime - The first time.

period - The period.

handler - The handler to receive notification(s).

event - The event to signal notification(s).

Returns:

The notification handler managing the scheduled notification(s).

Throws:

NullPointerException - Signals that handler or event is null.

IllegalArgumentException - Signals an invalid frequency, a negative first time, or a non-positive period.