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 (see AsyncEventHandler and Scheduler).

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() differs from a method call because the handler (a) has scheduling parameters and (b) is executed asynchronously.


Constructor Summary
AsyncEvent()
           
 
Method Summary
 void addHandler(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).
 ReleaseParameters createReleaseParameters()
          Create a ReleaseParameters block appropriate to the timing characteristics of this event.
 void fire()
          Fire (schedule the run() methods of) the handlers associated with this event.
 boolean handledBy(AsyncEventHandler handler)
          Returns true if and only if this event is handled by this handler.
 void removeHandler(AsyncEventHandler handler)
          Remove a handler from the set associated with this event.
 void setHandler(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
 

Constructor Detail

AsyncEvent

public AsyncEvent()
Method Detail

addHandler

public void addHandler(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.

Since this affects the constraints expressed in the release parameters of the existing schedulable objects, this may change the feasibility of the current schedule.


removeHandler

public void removeHandler(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.

handledBy

public boolean handledBy(AsyncEventHandler handler)
Returns true if and only if this event is handled by this handler.
Parameters:
target - The handler to be tested to determine if it is associated with this. Returns false if target is null.

setHandler

public void setHandler(AsyncEventHandler handler)
Associate a new handler with this event, removing all existing handlers.

Since this affects the constraints expressed in the release parameters of the existing schedulable objects, this may change the feasibility of the current schedule.

Parameters:
handler - The new and only handler to be associated with this. If handler is null then no handler will be associated with this (i.e., remove all handlers).

createReleaseParameters

public ReleaseParameters createReleaseParameters()
Create a ReleaseParameters block appropriate to the timing characteristics of this 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 that it knows the values for, like cost.

bindTo

public void bindTo(java.lang.String happening)
Binds this to an external event (a happening). The meaningful values of happening are implementation dependent. This AsyncEvent is considered to have occurred whenever the external event occurs.
Parameters:
happening - An implementation dependent value that binds this AsyncEvent to some external event.
Throws:
UnknownHappeningException - (a runtime exception) if if this event is not bound to the happening or if the happening string is not supported by the system.

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 AsyncEvent is bound.
Throws:
UnknownHappeningException - if this AsyncEvent is not bound to the given happening or the given happening string is not supported by the system.

fire

public void fire()
Fire (schedule the run() methods of) the handlers associated with this event.