javax.realtime

Class AsyncBaseEvent

java.lang.Object

javax.realtime.AsyncBaseEvent

Direct Known Subclasses:

AsyncEvent, AsyncLongEvent, AsyncObjectEvent

public abstract class AsyncBaseEvent
extends Object

This is the base class for all asynchronous events, where asynchronous is in regards to running code, not external time. This class unifies the original AsyncEvent with AsyncLongEvent.

Note that when this class is collected, all its handlers are automatically removed as if setHandler(javax.realtime.AsyncBaseEventHandler) was called with a null parameter.

Since:

RTSJ 2.0

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Add a handler to the set of handlers associated with this event.
ReleaseParameters<?>	createReleaseParameters() Create a ReleaseParameters object appropriate to the release characteristics of this event.
void	disable() Change the state of the event so that the associated handlers are skipped on fire.
void	enable() Change the state of the event so that associated handlers are released on fire.
boolean	handledBy(AsyncBaseEventHandler handler) Test to see if the handler given as the parameter is associated with this.
boolean	hasHandlers() Determine whether or not this event has any handlers.
boolean	isRunning() Determine the firing state (releasing or skipping) of this event, i.e, whether it is enabled or disabled
void	removeHandler(AsyncBaseEventHandler handler) Remove a handler from the set associated with this event.
void	setHandler(AsyncBaseEventHandler handler) Associate a new handler with this event and remove all existing handlers.

Methods inherited from class java.lang.Object

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

Method Detail

addHandler

public void addHandler(AsyncBaseEventHandler handler)

Add a handler to the set of handlers associated with this event. An instance of AsyncBaseEvent may have more than one associated handler. However, adding a handler to an event has no effect when the handler is already attached to the event The execution of this method is atomic with respect to the execution of the fire() method. Note that there is an implicit reference to the handler stored in this. The assignment must be valid under any applicable memory assignment rules.

Throws:

StaticIllegalArgumentException - when handler is null or the handler has PeriodicParameters

IllegalAssignmentError - when this AsyncBaseEvent cannot hold a reference to this handler

StaticIllegalStateException - when the configured scheduler and SchedulingParameters for handler are not compatible with one another

ScopedCycleException - when handler has an explicit initial scoped memory area that has already been entered from a memory area other than the area where handler was allocated

Parameters:

handler - The new handler to add to the list of handlers already associated with this. When handler is already associated with the event, the call has no effect

setHandler

public void setHandler(AsyncBaseEventHandler handler)

Associate a new handler with this event and remove all existing handlers.

Throws:

StaticIllegalArgumentException - when handler has PeriodicParameters. Only the subclass PeriodicTimer is allowed to have handlers with PeriodicParameters

IllegalAssignmentError - when this AsyncBaseEvent cannot hold a reference to handler

Parameters:

handler - The instance of AsyncBaseEventHandler to be associated with this. When handler is null then no handler will be associated with this, i.e., behave effectively as if setHandler(null) invokes removeHandler(AsyncBaseEventHandler) for each associated handler.

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

Remove a handler from the set associated with this event. A removed handler continues to execute until its fireCount becomes a zero and it completes. When handler has a scoped non-default initial memory area and execution of this method causes handler to become unfirable this method shall not return until all related finalization has completed

Parameters:

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

hasHandlers

public boolean hasHandlers()

Determine whether or not this event has any handlers.

Returns:

true iff at least one handler is associated with this event

enable

public void enable()

Change the state of the event so that associated handlers are released on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method enables that request mechanism

disable

public void disable()

Change the state of the event so that the associated handlers are skipped on fire. Each subclass provides a fire method as means of dispatching its handlers when requested. This method disables that request mechanism

isRunning

public boolean isRunning()

Determine the firing state (releasing or skipping) of this event, i.e, whether it is enabled or disabled

Returns:

true when releasing, false when skipping

handledBy

public boolean handledBy(AsyncBaseEventHandler handler)

Test to see 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 when the parameter is associated with this. false when the handler is null or the parameters is not associated with this

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()

Create a ReleaseParameters object appropriate to the release 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 for which it has values, e.g.,cost. The returned ReleaseParameters object is not bound to the event. Any changes in the event's release parameters are not reflected in previously returned objects. When an event returns PeriodicParameters, there is no requirement for an implementation to check that the handler is released periodically

Throws:

StaticUnsupportedOperationException - always, since it is not yet implemented.

Returns:

a new ReleaseParameters object