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
static int	createId(java.lang.String name) Sets up a mapping between a name and a system-dependent ID.
protected void	finalize()
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., when 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 the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.
HappeningDispatcher	setDispatcher(HappeningDispatcher dispatcher) Change the current dispatcher for this event.
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, createReleaseParameters, fire, handledBy, removeHandler, setHandler, unbindTo

Methods inherited from class javax.realtime.AsyncBaseEvent

addHandler, disable, enable, handledBy, hasHandlers, removeHandler, setHandler

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.realtime.ActiveEvent

disable, enable

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., when it has been started.

Specified by:

isActive in interface ActiveEvent<Happening,HappeningDispatcher>

Returns:

true when active; false otherwise.

isRunning

public boolean isRunning()

Determines the firing state, releasing or skipping, of this signal, i.e., whether or not it is active and enabled.

Specified by:

isRunning in interface ActiveEvent<Happening,HappeningDispatcher>

Overrides:

isRunning in class AsyncBaseEvent

Returns:

true when releasing, false when skipping.

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.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class AsyncBaseEvent

Throws:

java.lang.Throwable