javax.realtime
Class AsyncEvent

java.lang.Object
  javax.realtime.AsyncEvent

Direct Known Subclasses:

Timer

public class AsyncEvent
extends java.lang.Object

Jamaica Realtime Specification for Java class AsyncEvent.

An instance of AsyncEvent binds an external event (a happening) to a set of AsyncEventHandlers. Whenever the external event is fired, the fire count of all event handlers associated with this event will be increased and the handlers will be released.

Constructor Summary

AsyncEvent()
Constructor constructs a new AsyncEvent that is not bound to any signal.

Method Summary

void	addHandler(AsyncEventHandler handler) addHandler adds a handler to this event.
void	bindTo(java.lang.String happening) bindTo bind this handler to a happening that is identified by a platform-dependent string.
ReleaseParameters	createReleaseParameters() createReleaseParameters creates the default release parameters for this event.
void	fire() fire this event once.
boolean	handledBy(AsyncEventHandler handler) handledBy tests if this event is handled by a given handler.
void	removeHandler(AsyncEventHandler handler) removeHandler removes a handler from this event that was previously added by addHandler.
void	setHandler(AsyncEventHandler handler) setHandler removes all handlers from the list of handlers for this event and add given handler.
void	unbindTo(java.lang.String happening) unbindTo removes the binding to a certain happening.

Methods inherited from class java.lang.Object

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

Constructor Detail

AsyncEvent

public AsyncEvent()

Constructor constructs a new AsyncEvent that is not bound to any signal.

Method Detail

addHandler

public void addHandler(AsyncEventHandler handler)

addHandler adds a handler to this event. If the handler has already been added, this is a nop.

Since a reference to handler has to be stored in this, an IllegalAssignmentError will be caused if handler is allocated in a memory area that does not permit to be stored in an object allocated in this' memory area.

This call will allocate a small object in the memory area this was allocated in.

The execution of addHandler is atomic with respect to removeHandler and fire.

ensures
(handler != null) ==> (handledBy(handler));

Parameters:

handler - the new handler. If this handler is null, nothing will happen.

Throws:

java.lang.IllegalArgumentException - if handler == null;

removeHandler

public void removeHandler(AsyncEventHandler handler)

removeHandler removes a handler from this event that was previously added by addHandler.

The execution of removeHandler is atomic with respect to addHandler, setHandler, handledBy and fire.

ensures
((handler == null) || !handledBy(handler));

Parameters:

handler - the handler to be removed. If this handler is null or has not been added to this event, nothing will happen.

handledBy

public boolean handledBy(AsyncEventHandler handler)

handledBy tests if this event is handled by a given handler.

Parameters:

handler - The handler, may be null.

Returns:

true iff handler is not null and added as a handler for this event.

setHandler

public void setHandler(AsyncEventHandler handler)

setHandler removes all handlers from the list of handlers for this event and add given handler.

The execution of setHandler is atomic with respect to addHandler, removeHandler, handledBy and fire.

ensures
((handler == null) || handledBy(handler));

Parameters:

handler - The handler to be added, null if none.

createReleaseParameters

public ReleaseParameters createReleaseParameters()

createReleaseParameters creates the default release parameters for this event. The default implementation creates AperiodicParemters without cost/deadline and without overrun or miss handler.

Returns:

An instance of ReleaseParameters appropriate for handlers for this event.

bindTo

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

bindTo bind this handler to a happening that is identified by a platform-dependent string. Integer numbers 1 through POSIXSignalHandler.MAX_SIGNAL_NR bind this event to the corresponding POSIX event.

When this is allocated in ScopedMemory, then the reference count of MemoryArea.getMemoryArea(this) is incremented until this will be unbound from the happening.

Parameters:

happening - A platform-dependent string to identify the happening that causes this event.

Throws:

java.lang.IllegalArgumentException - if happening is null.

UnknownHappeningException - if happening is not supported.

unbindTo

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

unbindTo removes the binding to a certain happening.

When this is allocated in ScopedMemory, then the reference count of MemoryArea.getMemoryArea(this) is decremented.

Parameters:

happening - A platform-dependent string to identify the happening that causes this event.

Throws:

java.lang.IllegalArgumentException - if happening is null.

UnknownHappeningException - if happening is not supported or it was not bound to this event via bindTo().

fire

public void fire()
          throws MITViolationException,
                 ArrivalTimeQueueOverflowException

fire this event once. All event handlers that were added to this event will be released. If this event is bound to an external happening, it may still be fired manually by a call to this method.

If one or several handlers released by the call to fire cause an ArrivalTimeQueueOverflowException, all the handlers not affected by the exception will still be released normally.

If the release of the handlers requires both, a MITViolationException (due to a handler with SporadicParameters) and an ArrivalTimeQueueOverflowException, this method will throw the MITViolationException.

Throws:

MITViolationException

ArrivalTimeQueueOverflowException