javax.realtime.device

Class Happening

java.lang.Object

javax.realtime.AsyncBaseEvent

javax.realtime.AsyncEvent

javax.realtime.device.Happening

All Implemented Interfaces:

ActiveEvent<Happening,HappeningDispatcher>, Releasable<Happening,HappeningDispatcher>

public class Happening
extends AsyncEvent
implements ActiveEvent<Happening,HappeningDispatcher>

This class provides second level handling for external events such as interrupts. A happening can be triggered by an interrupt service routine or from native code. Application-defined Happenings can be identified by an application-provided name or a system-provided id, both of which must be unique. A system Happening has a name provided by the system which is a string beginning with @.

Since:

RTSJ 2.0

Constructor Summary

Constructors

Constructor and Description
Happening(java.lang.String name) Creates a happening with the given name and the default dispatcher.
Happening(java.lang.String name, HappeningDispatcher dispatcher) Creates a happening with the given name.

Method Summary

Modifier and Type	Method and Description
void	addHandler(AsyncBaseEventHandler handler) Adds a handler to the set of handlers associated with this event.
static int	createId(java.lang.String name) Sets up a mapping between a name and a system-dependent ID.
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.
static Happening	get(int id) Gets the external event corresponding to a given id.
static Happening	get(java.lang.String name) Gets the external event corresponding to a given name.
HappeningDispatcher	getDispatcher() Obtain the current dispatcher for this event.
static Happening	getHappening(java.lang.String name) Finds an active happening by its name.
int	getId() Gets the number of this happening.
static int	getId(java.lang.String name) Obtains the ID of name, when one exists or -1, when name is not registered.
java.lang.String	getName() Gets the name of this happening.
boolean	isActive() Determines the activation state of this happening, i.e., if it has been started.
static boolean	isHappening(java.lang.String name) Determines whether or not there is an active happening with name given as parameter.
boolean	isRunning() Determines whether or not this happening is both active an enabled.
void	removeHandler(AsyncBaseEventHandler handler) Removes a handler from the set associated with this event.
HappeningDispatcher	setDispatcher(HappeningDispatcher dispatcher) Change the current dispatcher for this event.
void	setHandler(AsyncBaseEventHandler handler) Associates a new handler with this event and removes all existing handlers.
void	start() Starts this happening, i.e., changes its state to the active and enabled.
void	start(boolean disabled) Starts this happening, but leaves it in the disabled state.
boolean	stop() Stops this happening from responding to the fire and trigger methods.
void	trigger() Causes the event dispatcher associated with this to be scheduled for execution.
static boolean	trigger(int id) Causes the event dispatcher corresponding to happeningId to be scheduled for execution.

Methods inherited from class javax.realtime.AsyncEvent

addHandler, bindTo, fire, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

createReleaseParameters, handledBy, hasHandlers

Methods inherited from class java.lang.Object

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

Constructor Detail

Happening

public Happening(java.lang.String name,
                 HappeningDispatcher dispatcher)
          throws StaticIllegalArgumentException

Creates a happening with the given name.

Parameters:

name - A string to name the happening.

dispatcher - To use when being triggered.

Throws:

StaticIllegalArgumentException - when name is null or does not match the pattern full identifier naming convention, i.e., package plus name. An implementation may throw this exception for all names starting with java. and javax.

Happening

public Happening(java.lang.String name)
          throws StaticIllegalArgumentException

Creates a happening with the given name and the default dispatcher.

Parameters:

name - A string to name the happening.

Throws:

StaticIllegalArgumentException - when name is null or does not match the pattern full type naming convention, i.e., package plus name. An implementation may throw this exception for all names starting with java. and javax.

Method Detail

getHappening

public static Happening getHappening(java.lang.String name)

Finds an active happening by its name.

Parameters:

name - Identifies the happening to get.

Returns:

a reference to the happening with the given name, or null, if no happening with the given name is found.

Throws:

StaticIllegalArgumentException - when name is null.

isHappening

public static boolean isHappening(java.lang.String name)

Determines whether or not there is an active happening with name given as parameter.

Parameters:

name - A string that might name an active happening.

Returns:

true only when there is a registered happening with the given name.

Throws:

StaticIllegalArgumentException - when name is null.

createId

public static int createId(java.lang.String name)
                    throws StaticIllegalStateException

Sets up a mapping between a name and a system-dependent ID. This can be called either in native code that sets up an interrupt service routine to link it with a happening. Once created, it cannot be removed.

This must take no more than linear time in the number of ID (n) registered, but should be O(log2(n)).

Parameters:

name - A string to name a happening.

Returns:

an ID assigned by the system.

Throws:

StaticIllegalStateException - when name is already registered.

StaticIllegalArgumentException - when name is null.

getId

public static int getId(java.lang.String name)

Obtains the ID of name, when one exists or -1, when name is not registered.

This must take no more than linear time in the number of ID (n) registered, but should be O(log2(n)).

Parameters:

name - A happening name string.

Returns:

The ID, or -1 when no happening is found with that name.

Throws:

StaticIllegalArgumentException - when name is null.

get

public static Happening get(int id)

Gets the external event corresponding to a given id.

Parameters:

id - The identifier of a registered signal.

Returns:

the signal corresponding to id.

get

public static Happening get(java.lang.String name)

Gets the external event corresponding to a given name.

Parameters:

name - The name of a registered signal.

Returns:

the signal corresponding to name.

Throws:

StaticIllegalArgumentException - when name is null.

trigger

public static boolean trigger(int id)

Causes the event dispatcher corresponding to happeningId to be scheduled for execution. The implementation should be simple enough so that it can be done in the context of an interrupt service routine.

trigger() and any native code analog to it interact with other ActiveEvent code effectively as if trigger() signals a POSIX counting semaphore that the happening is waiting on.

The implementation is encouraged to create (and document) a native code analog to this method that can be used without a Java context.

This method must execute in constant time.

Parameters:

id - Identifies which happening to trigger.

Returns:

true when a happening with ID happeningId was found, false otherwise.

getId

public final int getId()

Gets the number of this happening.

Returns:

the happening number or -1, when not registered.

getName

public java.lang.String getName()

Gets the name of this happening.

Returns:

the name of this happening.

isActive

public boolean isActive()

Determines the activation state of this happening, i.e., if it has been started.

Specified by:

isActive in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

true when active; false otherwise.

isRunning

public boolean isRunning()

Determines whether or not this happening is both active an enabled.

Specified by:

isRunning in interface ActiveEvent<Happening,HappeningDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true when this happening is both active and enabled; false otherwise.

enable

public void enable()

Description copied from class: AsyncBaseEvent

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.

Specified by:

enable in interface ActiveEvent<Happening,HappeningDispatcher>

Overrides:

enable in class AsyncBaseEvent

disable

public void disable()

Description copied from class: AsyncBaseEvent

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.

Specified by:

disable in interface ActiveEvent<Happening,HappeningDispatcher>

Overrides:

disable in class AsyncBaseEvent

start

public void start()
           throws StaticIllegalStateException

Starts this happening, i.e., changes its state to the active and enabled. Once a happening is started for the first time, when it is in a scoped memory it increments the scope count of that scope; otherwise, it becomes a member of the root set. An active and enabled happening dispatches its handlers when fired.

Specified by:

start in interface ActiveEvent<Happening,HappeningDispatcher>

Throws:

StaticIllegalStateException - when this happening has already been started or its name is already in use by another happening that has been started.

See Also:

stop()

start

public void start(boolean disabled)
           throws StaticIllegalStateException

Starts this happening, but leaves it in the disabled state. When fired before being enabled, it does not dispatch its handlers.

Specified by:

start in interface ActiveEvent<Happening,HappeningDispatcher>

Parameters:

disabled - true for starting in a disabled state.

Throws:

StaticIllegalStateException - when this happening has already been started.

See Also:

stop()

stop

public boolean stop()
             throws StaticIllegalStateException

Stops this happening from responding to the fire and trigger methods.

Specified by:

stop in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

true when this is in the enabled state; false otherwise.

Throws:

StaticIllegalStateException - when this happening is not active.

trigger

public void trigger()

Causes the event dispatcher associated with this to be scheduled for execution. The implementation should be simple enough so that it can be done in the context of an interrupt service routine.

This method must execute in constant time.

getDispatcher

public HappeningDispatcher getDispatcher()

Description copied from interface: ActiveEvent

Obtain the current dispatcher for this event.

Specified by:

getDispatcher in interface ActiveEvent<Happening,HappeningDispatcher>

Specified by:

getDispatcher in interface Releasable<Happening,HappeningDispatcher>

Returns:

the dispatcher associated with this event.

setDispatcher

public HappeningDispatcher setDispatcher(HappeningDispatcher dispatcher)

Description copied from interface: ActiveEvent

Change the current dispatcher for this event. When dispatcher is null, the default dispatcher is restored.

Specified by:

setDispatcher in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

the dispatcher associated with this event.

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.

Overrides:

addHandler in class AsyncBaseEvent

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)

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.

Overrides:

setHandler in class AsyncBaseEvent

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 AsyncBaseEvent.removeHandler(AsyncBaseEventHandler) for each associated handler.

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.

Overrides:

removeHandler in class AsyncBaseEvent

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.