javax.realtime

Class ActiveEventDispatcher<D extends ActiveEventDispatcher<D,T>,T extends Releasable<T,D>>

java.lang.Object

javax.realtime.ActiveEventDispatcher<D,T>

Type Parameters:

D - The type of dispatcher this class is.

T - The type of event to be dispatched.

Direct Known Subclasses:

HappeningDispatcher, RealtimeSignalDispatcher, SignalDispatcher, TimeDispatcher

public abstract class ActiveEventDispatcher<D extends ActiveEventDispatcher<D,T>,T extends Releasable<T,D>>
extends java.lang.Object

Provides a means of dispatching a set of ActiveEvents. It acts as if it contains a daemon RealtimeThread to perform this task. The priority of this thread can be specified when a dispatcher object is created. The default dispatcher runs at the highest realtime priority on the base scheduler. Dispatchers do not maintain a queue of pending event.

Application code cannot extend this class.

Since:

RTSJ 2.0

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ActiveEventDispatcher(RealtimeThread thread) Creates a new dispatcher.

Method Summary

Modifier and Type	Method and Description
protected void	activate(T event) Activate an active event registered with this dispatcher.
protected void	deactivate(T event) Deactivate an active event registered with this dispatcher.
protected abstract void	deregister(T event) Deregisters an active event from this dispatcher, breaking its association with this dispatcher.
abstract void	destroy() Makes the dispatcher unusable.
RealtimeThreadGroup	getRealtimeThreadGroup() Determines in which group the thread associated with this dispatcher is.
Scheduler	getScheduler() Gets a reference to the Scheduler object for this schedulable.
SchedulingParameters	getSchedulingParameters() Determines how the thread associated with this dispatcher is scheduled.
protected RealtimeThread	getThread() Obtain the thread behind the dispatcher.
abstract boolean	isRegistered(T event) Test wether or not a given event is registered with this dispatcher.
protected abstract void	register(T event) Registers an active event with this dispatcher.
ActiveEventDispatcher<D,T>	setScheduler(Scheduler scheduler) Sets the reference to the Scheduler object.
ActiveEventDispatcher<D,T>	setScheduler(Scheduler scheduler, SchedulingParameters scheduling) Sets the scheduler and associated parameter objects.
ActiveEventDispatcher<D,T>	setSchedulingParameters(SchedulingParameters scheduling) Sets the scheduling parameters associated with this instance of Schedulable.

Methods inherited from class java.lang.Object

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

Constructor Detail

ActiveEventDispatcher

protected ActiveEventDispatcher(RealtimeThread thread)
                         throws StaticIllegalStateException

Creates a new dispatcher. The thread is provided by the caller and is specific to the type of dispatcher. The scheduling of the thread and its thread group are also provided by the caller.

Parameters:

thread - a realtime thread set up to run the dispatcher.

Throws:

StaticIllegalArgumentException - thread is null.

StaticIllegalStateException

Method Detail

getScheduler

public Scheduler getScheduler()

Gets a reference to the Scheduler object for this schedulable.

Returns:

a reference to the associated Scheduler object.

setScheduler

public ActiveEventDispatcher<D,T> setScheduler(Scheduler scheduler)
                                        throws IllegalTaskStateException

Sets the reference to the Scheduler object. The timing of the change must be agreed between the scheduler currently associated with this schedulable, and scheduler. If the Schedulable is running, its associated SchedulingParameters (if any) must be compatible with scheduler.

Parameters:

scheduler - A reference to the scheduler that will manage execution of this schedulable. Null is not a permissible value.

Returns:

this

Throws:

StaticIllegalArgumentException - when scheduler is null, or the schedulable's existing parameter values are not compatible with scheduler. Also when this schedulable may not use the heap and scheduler is located in heap memory.

IllegalAssignmentError - when the schedulable cannot hold a reference to scheduler or the current Schedulable is running and its associated SchedulingParameters are incompatible with scheduler.

StaticSecurityException - when the caller is not permitted to set the scheduler for this schedulable.

IllegalTaskStateException - when scheduler has scheduling or release parameters that are not compatible with the new scheduler and this schedulable is running.

setScheduler

public ActiveEventDispatcher<D,T> setScheduler(Scheduler scheduler,
                                               SchedulingParameters scheduling)
                                        throws StaticSecurityException,
                                               IllegalTaskStateException

Sets the scheduler and associated parameter objects. The timing of the change must be agreed between the scheduler currently associated with this schedulable, and scheduler.

Parameters:

scheduler - A reference to the scheduler that will manage the execution of this schedulable. Null is not a permissible value.

scheduling - A reference to the SchedulingParameters which will be associated with this. When null, the default value is governed by scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)

Returns:

this

Throws:

StaticIllegalArgumentException - when scheduler is null or the parameter values are not compatible with scheduler. Also thrown when this schedulable may not use the heap and scheduler, scheduling release, memoryParameters, or group is located in heap memory.

IllegalAssignmentError - when this object cannot hold references to all the parameter objects or the parameters cannot hold references to this.

StaticSecurityException - when the caller is not permitted to set the scheduler for this schedulable.

IllegalTaskStateException

getSchedulingParameters

public SchedulingParameters getSchedulingParameters()

Determines how the thread associated with this dispatcher is scheduled.

Returns:

the scheduling parameters of the dispatcher thread.

setSchedulingParameters

public ActiveEventDispatcher<D,T> setSchedulingParameters(SchedulingParameters scheduling)
                                                   throws IllegalTaskStateException,
                                                          IllegalAssignmentError,
                                                          StaticIllegalArgumentException

Sets the scheduling parameters associated with this instance of Schedulable.

This change becomes effective under conditions determined by the scheduler controlling the schedulable. For instance, the change may be immediate or it may be delayed until the next release of the schedulable. See the documentation for the scheduler for details.

Parameters:

scheduling - A reference to the SchedulingParameters object. When null, the default value is governed by the associated scheduler; a new object is created when the default value is not null. (See PriorityScheduler.)

Returns:

this

Throws:

StaticIllegalArgumentException - when scheduling is not compatible with the associated scheduler or when scheduling is null. Also when this schedulable may not use the heap and scheduling is located in heap memory.

IllegalAssignmentError - when this object cannot hold a reference to scheduling or scheduling cannot hold a reference to this.

IllegalTaskStateException - when the task is active and the new scheduling parameters are not compatible with the current scheduler or the affinity in scheduling is invalid or not a subset of the affinity of this object's realtime thread group.

getRealtimeThreadGroup

public RealtimeThreadGroup getRealtimeThreadGroup()

Determines in which group the thread associated with this dispatcher is.

Returns:

the realtime thread group of the dispatcher thread.

getThread

protected RealtimeThread getThread()

Obtain the thread behind the dispatcher.

Returns:

the realtime thread behind the dispatcher.

isRegistered

public abstract boolean isRegistered(T event)

Test wether or not a given event is registered with this dispatcher.

Parameters:

event - The event to test

Returns:

true when event is registered with this dispatcher.

register

protected abstract void register(T event)
                          throws RegistrationException,
                                 StaticIllegalStateException

Registers an active event with this dispatcher. Registering an event prevents the event from being programmatically destroyed, but it may not hold the dispatcher from being collected when the dispatcher is in a more deeply nested scope.

Parameters:

event - The event to register

Throws:

RegistrationException - when event is already registered.

StaticIllegalStateException - when this object has been destroyed.

activate

protected void activate(T event)
                 throws RegistrationException,
                        StaticIllegalArgumentException

Activate an active event registered with this dispatcher.

Parameters:

event - The event to register

Throws:

RegistrationException - when event is not already registered.

StaticIllegalStateException - when event is stopped.

StaticIllegalArgumentException

deregister

protected abstract void deregister(T event)
                            throws RegistrationException,
                                   StaticIllegalStateException

Deregisters an active event from this dispatcher, breaking its association with this dispatcher. This should only happen when an event is assoicated with another dispather.

Parameters:

event - The event to deregister

Throws:

StaticIllegalStateException - when this object has been destroyed

StaticIllegalArgumentException - when event is not stopped or is null.

RegistrationException

deactivate

protected void deactivate(T event)
                   throws DeregistrationException,
                          StaticIllegalStateException,
                          StaticIllegalArgumentException

Deactivate an active event registered with this dispatcher.

Parameters:

event - The event to deregister

Throws:

DeregistrationException - when event is not already registered.

StaticIllegalStateException - when this object has been destroyed.

StaticIllegalArgumentException - when event is not stopped or is null.

destroy

public abstract void destroy()
                      throws StaticIllegalStateException

Makes the dispatcher unusable.

Throws:

StaticIllegalStateException - when called on a dispatcher that has one or more registered objects.