jmri.jmrit.automat
Class AbstractAutomaton

Show UML class diagram
java.lang.Object
  extended by 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:

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


Copyright © 1997-2014 JMRI Community.
JMRI, DecoderPro, PanelPro, SoundPro, DispatcherPro and associated logos are our trademarks.

Additional information on copyright, trademarks and licenses is linked here.
Site hosted by: Get JMRI Model Railroad Interface at SourceForge.net. Fast, secure and Free Open Source software downloads