javax.realtime

Class AsyncBaseEvent

java.lang.Object

javax.realtime.AsyncBaseEvent

Direct Known Subclasses:

AsyncEvent, AsyncLongEvent, AsyncObjectEvent

public abstract class AsyncBaseEvent
extends java.lang.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 and AsyncObjectEvent.

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) Adds a handler to the set of handlers associated with this event.
ReleaseParameters<?>	createReleaseParameters() Creates a ReleaseParameters object appropriate to the release characteristics of this event.
void	disable() Changes the state of the event so that associated handlers are skipped on fire.
void	enable() Changes the state of the event so that associated handlers are released on fire.
boolean	handledBy(AsyncBaseEventHandler handler) Determines whether or not the handler given as the parameter is associated with this.
boolean	hasHandlers() Determines whether or not this event has any handlers.
boolean	isRunning() Determines the firing state (releasing or skipping) of this event, i.e., whether it is enabled or disabled.
void	removeHandler(AsyncBaseEventHandler handler) Removes a handler from the set associated with this event.
void	setHandler(AsyncBaseEventHandler handler) Associates a new handler with this event and removes all existing handlers.

Methods inherited from class java.lang.Object

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

Method Detail

isRunning

public boolean isRunning()

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

Returns:

true when releasing, false when skipping.

Since:

RTSJ 2.0 Inherited by AyncEvent

handledBy

public boolean handledBy(AsyncBaseEventHandler handler)

Determines whether or not 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 handler is null or the parameters is not associated with this.

Since:

RTSJ 2.0 Inherited by AyncEvent

enable

public void enable()

Changes 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.

Since:

RTSJ 2.0 Inherited by AyncEvent

disable

public void disable()

Changes the state of the event so that 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.

Since:

RTSJ 2.0 Inherited by AyncEvent

addHandler

public void addHandler(AsyncBaseEventHandler handler)

Adds 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.

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.

Throws:

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

IllegalAssignmentError - when this AsyncBaseEvent cannot hold a reference to 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.

Since:

RTSJ 2.0 Inherited by AyncEvent

setHandler

public void setHandler(AsyncBaseEventHandler handler)

Associates a new handler with this event and removes all existing handlers. The execution of this method is atomic with respect to the execution of the fire() method.

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., it behaves effectively as if setHandler(null) invokes removeHandler(AsyncBaseEventHandler) for each associated handler.

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.

Since:

RTSJ 2.0 Inherited by AyncEvent

removeHandler

public void removeHandler(AsyncBaseEventHandler handler)

Removes a handler from the set associated with this event. The execution of this method is atomic with respect to the execution of the fire() method.

A removed handler continues to execute until its fireCount becomes 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.

Since:

RTSJ 2.0 Inherited by AyncEvent

hasHandlers

public boolean hasHandlers()

Determines whether or not this event has any handlers.

Returns:

true when and only when at least one handler is associated with this event.

Since:

RTSJ 2.0 Inherited by AyncEvent

createReleaseParameters

public ReleaseParameters<?> createReleaseParameters()

Creates 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.

Returns:

a new ReleaseParameters object.