javax.realtime
Class AsyncEvent

java.lang.Object
  |
  +--javax.realtime.AsyncEvent

Direct Known Subclasses:

Timer

public class AsyncEvent

extends java.lang.Object

An asynchronous event represents something that can happen, like a light turning red. It can have a set of handlers associated with it, and when the event occurs, the handler is scheduled by the scheduler to which it holds a reference.

A major motivator for this style of building events is that we expect to have lots of events and lots of event handlers. An event handler is logically very similar to a thread, but it is intended to have a much lower cost (in both time and space) -- assuming that a relatively small number of events are fired and in the process of being handled at once. AsyncEvent.fire() deffers from a method call because the handler has scheduling parameters and is executed asynchronously.

Field Summary

protected java.util.LinkedList

handlersList

Constructor Summary

AsyncEvent()
Create a new AsyncEvent object.

Method Summary

void	addHandler(javax.realtime.AsyncEventHandler handler) Add a handler to the set of handlers associated with this event.
void	bindTo(java.lang.String happening) Binds this to an external event, a happening.
javax.realtime.ReleaseParameters	createReleaseParameters() Create a ReleaseParameters block appropriate to the timing characteristics of the event.
void	fire() Fire this instance of AsyncEvent.
boolean	handledBy(javax.realtime.AsyncEventHandler handler) Returns true if and only if the handler given as the parameter is associated with this.
void	removeHandler(javax.realtime.AsyncEventHandler handler) Remove a handler from the set associated with this event.
void	setHandler(javax.realtime.AsyncEventHandler handler) Associate a new handler with this event, removing all existing handlers.
void	unbindTo(java.lang.String happening) Removes a binding to an external event, a happening.

Methods inherited from class java.lang.Object

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

Field Detail

handlersList

protected java.util.LinkedList handlersList

Constructor Detail

AsyncEvent

public AsyncEvent()

Create a new AsyncEvent object.

Method Detail

addHandler

public void addHandler(javax.realtime.AsyncEventHandler handler)

Add a handler to the set of handlers associated with this event. An AsyncEvent may have more than one associated handler.

Parameters:

handler - The new handler to add to the list of handlers already associated with this. If handler is null then nothing happens.

bindTo

public void bindTo(java.lang.String happening)
            throws UnknownHappeningException

Binds this to an external event, a happening. The meaningful values of happening are implementation dependent. This instance of AsyncEvent is considered to have occured whenever the happening occurs.

Throws:

UnknownHappeningException - If the string value is not supported by the implementation.

createReleaseParameters

public javax.realtime.ReleaseParameters createReleaseParameters()

Create a ReleaseParameters block appropriate to the timing characteristics of the event. The default is the most pessimistic: AperiodicParameters. This is typically called by code that is setting up a handler for this event that will fill in the parts of the release parameters for which it has values, e.g., cost.

Returns:

A new ReleaseParameters object.

fire

public void fire()

Fire this instance of AsyncEvent. The run() methods of intances of AsyncEventHandler associated with this event will be made raedy to run.

handledBy

public boolean handledBy(javax.realtime.AsyncEventHandler handler)

Returns true if and only if the handler given as the parameter is associated with this.

Parameters:

handler - The handler to be tested to determine if it is associated with this.

Returns:

True if the parameter is associated with this. False, if target is null or the parameter is not associated with this.

removeHandler

public void removeHandler(javax.realtime.AsyncEventHandler handler)

Remove a handler from the set associated with this event.

Parameters:

handler - The handler to be disassociated from this. If null nothing happens. If not already associated with this then nothing happens.

setHandler

public void setHandler(javax.realtime.AsyncEventHandler handler)

Associate a new handler with this event, removing all existing handlers.

Parameters:

handler - The new instance of AsyncEventHandler to be associated with this. If handler is null then no handler will be associated with this (i.e., remove all handlers).

unbindTo

public void unbindTo(java.lang.String happening)
              throws UnknownHappeningException

Removes a binding to an external event, a happening. The meaningful values of happening are implementation dependent.

Parameters:

happening - An implementation dependent value representing some external event to which this instance of AsyncEvent is bound.

Throws:

UnknownHappeningException - If this intance of AsyncEvent is not bound to the given happening or the given java.lang.String value is not supported by the implementation.