jmri.jmrit.automat
Class AbstractAutomaton

Show UML class diagram

java.lang.Object
  jmri.jmrit.automat.AbstractAutomaton

All Implemented Interfaces:

Runnable

Direct Known Subclasses:

CrrInit, CrrSection, JythonAutomaton, LocoNetAutomaton, SampleAutomaton, SampleAutomaton2, SampleAutomaton3, Siglet

public class AbstractAutomaton
extends Object
implements Runnable

Abstract base for user automaton classes, which provide individual bits of automation.

Each individual automaton runs in a separate thread, so they can operate independently. This class handles thread creation and scheduling, and provides a number of services for the user code.

Subclasses provide a "handle()" function, which does the needed work, and optionally a "init()" function. These can use any JMRI resources for input and output. It should not spin on a condition without explicit wait requests; it is more efficient to use the explicit wait services when waiting for some specific condition.

handle() is executed repeatedly until either the Automate object is halted(), or it returns "false". Returning "true" will just cause handle() to be invoked again, so you can cleanly restart the Automaton by returning from multiple points in the function.

Since handle() executes outside the GUI thread, it is important that access to GUI (AWT, Swing) objects be scheduled through the various service routines.

Services are provided by public member functions, described below. They must only be invoked from the init and handle methods, as they must be used in a delayable thread. If invoked from the GUI thread, for example, the program will appear to hang. To help ensure this, a warning will be logged if they are used before the thread starts.

For general use, e.g. in scripts, the most useful functions are:

• Wait for a specific number of milliseconds: waitMsec(int)
• Wait for a specific sensor to be active: waitSensorActive(jmri.Sensor) This is also available in a form that will wait for any of a group of sensors to be active.
• Wait for a specific sensor to be inactive: waitSensorInactive(jmri.Sensor) This is also available in a form that will wait for any of a group of sensors to be inactive.
• Wait for a specific sensor to be in a specific state: waitSensorState(jmri.Sensor, int)
• Wait for a specific sensor to change: waitSensorChange(int, jmri.Sensor)
• Set a group of turnouts and wait for them to be consistent (actual position matches desired position): setTurnouts(jmri.Turnout[], jmri.Turnout[])
• Wait for a group of turnouts to be consistent (actually as set): waitTurnoutConsistent(jmri.Turnout[])
• Wait for any one of a number of Sensors, Turnouts and/or other objects to change: waitChange(jmri.NamedBean[])
• Obtain a DCC throttle: getThrottle(int, boolean)
• Read a CV from decoder on programming track: readServiceModeCV(int)
• Write a value to a CV in a decoder on the programming track: writeServiceModeCV(int, int)
• Write a value to a CV in a decoder on the main track: writeOpsModeCV(int, int, boolean, int)

Although this is named an "Abstract" class, it's actually concrete so that Jython code can easily use some of the methods.

Nested Class Summary

class

AbstractAutomaton.MsgFrame Internal class to show a Frame

Field Summary

(package private) Thread	currentThread
(package private) JFrame	debugWaitFrame
(package private) static org.slf4j.Logger	log
(package private) String	message
(package private) JFrame	messageFrame
protected boolean	promptOnWait Control optional debugging prompt.
(package private) AutomatSummary	summary

Constructor Summary

AbstractAutomaton()

AbstractAutomaton(String name)

Method Summary

(package private) void	defaultName()
(package private) void	done() Part of the internal implementation; not for general use.
int	getCount() Returns the number of times the handle routine has executed.
String	getName() Gives access to the thread name.
DccThrottle	getThrottle(BasicRosterEntry re) Obtains a DCC throttle, including waiting for the command station response.
DccThrottle	getThrottle(int address, boolean longAddress) Obtains a DCC throttle, including waiting for the command station response.
protected boolean	handle() User-provided main routine.
protected void	init() User-provided initialization routine.
int	readServiceModeCV(int CV) Read a CV on the service track, including waiting for completion.
void	run() Part of the implementation; not for general use.
void	setName(String name) Update the name of this object.
void	setTurnouts(Turnout[] closed, Turnout[] thrown) Convenience function to set a bunch of turnouts and wait until they are all in a consistent state
void	start() Start this automat processing.
void	stop() Stop the thread immediately.
protected void	wait(int milliseconds) Part of the intenal implementation, not intended for users.
void	waitChange(NamedBean[] mInputs) Wait for one of a list of NamedBeans (sensors, signal heads and/or turnouts) to change.
void	waitMsec(int milliseconds) Wait for a specified number of milliseconds, and then return control.
void	waitSensorActive(Sensor mSensor) Wait for a sensor to be active.
void	waitSensorActive(Sensor[] mSensors) Wait for one of a list of sensors to be be active.
int	waitSensorChange(int mState, Sensor mSensor) Wait for a sensor to change state.
void	waitSensorChange(Sensor[] mSensors) Wait for one of an array of sensors to change.
void	waitSensorInactive(Sensor mSensor) Wait for a sensor to be inactive.
void	waitSensorInactive(Sensor[] mSensors) Wait for one of a list of sensors to be be inactive.
void	waitSensorState(Sensor[] mSensors, int state) Wait for one of a list of sensors to be be in a selected state.
void	waitSensorState(Sensor mSensor, int state) Internal service routine to wait for one sensor to be in (or become in) a specific state.
void	waitTurnoutConsistent(Turnout[] mTurnouts) Wait for a list of turnouts to all be in a consistent state This works by registering a listener, which is likely to run in another thread.
boolean	writeOpsModeCV(int CV, int value, boolean longAddress, int loco) Write a CV in ops mode, including waiting for completion.
boolean	writeServiceModeCV(int CV, int value) Write a CV on the service track, including waiting for completion.

Methods inherited from class java.lang.Object

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

Field Detail

summary

AutomatSummary summary

currentThread

Thread currentThread

promptOnWait

protected boolean promptOnWait

Control optional debugging prompt. If this is set true, each call to wait() will prompt the user whether to continue.

messageFrame

JFrame messageFrame

message

String message

debugWaitFrame

JFrame debugWaitFrame

log

static org.slf4j.Logger log

Constructor Detail

AbstractAutomaton

public AbstractAutomaton()

AbstractAutomaton

public AbstractAutomaton(String name)

Method Detail

start

public void start()

Start this automat processing. Overrides the superclass method to do local accounting.

run

public void run()

Part of the implementation; not for general use.

This is invoked on currentThread.

Specified by:

run in interface Runnable

stop

public void stop()

Stop the thread immediately. Overrides superclass method to handle local accounting.

done

void done()

Part of the internal implementation; not for general use. Common internal end-time processing

getCount

public int getCount()

Returns the number of times the handle routine has executed. Used by e.g. jmri.jmrit.automat.monitor to monitor progress

getName

public String getName()

Gives access to the thread name. Used internally for e.g. jmri.jmrit.automat.monitor

setName

public void setName(String name)

Update the name of this object. name is not a bound parameter, so changes are not notified to listeners

See Also:

getName()

defaultName

void defaultName()

init

protected void init()

User-provided initialization routine. This is called exactly once for each object created. This is where you put all the code that needs to be run when your object starts up: Finding sensors and turnouts, getting a throttle, etc.

handle

protected boolean handle()

User-provided main routine. This is run repeatedly until it signals the end by returning false. Many automata are intended to run forever, and will always return true.

Returns:

false to terminate the automaton, for example due to an error.

waitMsec

public void waitMsec(int milliseconds)

Wait for a specified number of milliseconds, and then return control.

wait

protected void wait(int milliseconds)

Part of the intenal implementation, not intended for users.

This handles exceptions internally, so they needn't clutter up the code. Note that the current implementation doesn't guarantee the time, either high or low.

Because of the way Jython access handles synchronization, this is explicitly synchronized internally.

Parameters:

milliseconds -

waitSensorChange

public int waitSensorChange(int mState,
                            Sensor mSensor)

Wait for a sensor to change state.

The current (OK) state of the Sensor is passed to avoid a possible race condition. The new state is returned for a similar reason.

This works by registering a listener, which is likely to run in another thread. That listener then interrupts the automaton's thread, who confirms the change.

Parameters:

mState - Current state of the sensor

mSensor - Sensor to watch

Returns:

newly detected Sensor state

waitSensorActive

public void waitSensorActive(Sensor mSensor)

Wait for a sensor to be active. (Returns immediately if already active)

Parameters:

mSensor - Sensor to watch

waitSensorInactive

public void waitSensorInactive(Sensor mSensor)

Wait for a sensor to be inactive. (Returns immediately if already inactive)

Parameters:

mSensor - Sensor to watch

waitSensorState

public void waitSensorState(Sensor mSensor,
                            int state)

Internal service routine to wait for one sensor to be in (or become in) a specific state.

Used by waitSensorActive and waitSensorInactive

This works by registering a listener, which is likely to run in another thread. That listener then interrupts the automaton's thread, who confirms the change.

waitSensorInactive

public void waitSensorInactive(Sensor[] mSensors)

Wait for one of a list of sensors to be be inactive.

waitSensorActive

public void waitSensorActive(Sensor[] mSensors)

Wait for one of a list of sensors to be be active.

waitSensorState

public void waitSensorState(Sensor[] mSensors,
                            int state)

Wait for one of a list of sensors to be be in a selected state.

This works by registering a listener, which is likely to run in another thread. That listener then interrupts the automaton's thread, who confirms the change.

Parameters:

mSensors - Array of sensors to watch

state - State to check (static value from jmri.Sensors)

waitTurnoutConsistent

public void waitTurnoutConsistent(Turnout[] mTurnouts)

Wait for a list of turnouts to all be in a consistent state

This works by registering a listener, which is likely to run in another thread. That listener then interrupts the automaton's thread, who confirms the change.

Parameters:

mTurnouts - list of turnouts to watch

setTurnouts

public void setTurnouts(Turnout[] closed,
                        Turnout[] thrown)

Convenience function to set a bunch of turnouts and wait until they are all in a consistent state

Parameters:

closed - turnouts to set to closed state

thrown - turnouts to set to thrown state

waitChange

public void waitChange(NamedBean[] mInputs)

Wait for one of a list of NamedBeans (sensors, signal heads and/or turnouts) to change.

This works by registering a listener, which is likely to run in another thread. That listener then interrupts the automaton's thread, who confirms the change.

Parameters:

mInputs - Array of NamedBeans to watch

waitSensorChange

public void waitSensorChange(Sensor[] mSensors)

Wait for one of an array of sensors to change.

This is an older method, now superceded by waitChange, which can wait for any NamedBean.

Parameters:

mSensors - Array of sensors to watch

getThrottle

public DccThrottle getThrottle(int address,
                               boolean longAddress)

Obtains a DCC throttle, including waiting for the command station response.

Parameters:

address -

longAddress - true if this is a long address, false for a short address

Returns:

A usable throttle, or null if error

getThrottle

public DccThrottle getThrottle(BasicRosterEntry re)

Obtains a DCC throttle, including waiting for the command station response.

Parameters:

re - specifies the desired locomotive

Returns:

A usable throttle, or null if error

writeServiceModeCV

public boolean writeServiceModeCV(int CV,
                                  int value)

Write a CV on the service track, including waiting for completion.

Parameters:

CV - Number 1 through 512

value -

Returns:

true if completed OK

readServiceModeCV

public int readServiceModeCV(int CV)

Read a CV on the service track, including waiting for completion.

Parameters:

CV - Number 1 through 512

Returns:

-1 if error, else value

writeOpsModeCV

public boolean writeOpsModeCV(int CV,
                              int value,
                              boolean longAddress,
                              int loco)

Write a CV in ops mode, including waiting for completion.

Parameters:

CV - Number 1 through 512

value -

loco - Locomotive decoder address

longAddress - true is the locomotive is using a long address

Returns:

true if completed OK