jmri
Class TurnoutOperation

java.lang.Object
  jmri.TurnoutOperation

All Implemented Interfaces:

Comparable

Direct Known Subclasses:

CommonTurnoutOperation

public abstract class TurnoutOperation
extends Object
implements Comparable

Framework for automating reliable turnout operation. This interface allows a particular style (e.g. retries) to be implemented and then to have multiple instances for variations in parameters if required

This mechanism is designed to extensible to allow new operation types (e.g. for Tortoise-style point machines) and to allow individual system types to change it, for example to allow operation with alternative feedback arrangements.

The TurnoutOperation class is at the heart of things, although there are several other classes, partly to fit in with JMRI's package structure. Each specific retry scheme has its own concrete subclass of TurnoutOperation. One instance of each such class is created at startup. It has the same name as the prefix to the class, and is called the "defining instance". Further instances can exist with different parameter values (e.g. number of retries).

The TurnoutOperationManager class (only one instance) keeps track of the instances and can retrieve them by name. It can also supply a suitable TurnoutOperation for a given turnout, based on the feedback type, if the turnout does not identify one for itself.

Each AbstractTurnout may have a reference to a TurnoutOperation class, which may be unique to this turnout or may be shared. When the turnout is thrown, if it has its own TurnoutOperation, this is used (unless the turnout has selected no automation). Otherwise, the TurnoutOperationManager is asked to find one.

The TurnoutOperation has a factory method (getOperation) which is called when a turnout is operated, to supply the operator. Each subclass of TurnoutOperation has a corresponding subclass of TurnoutOperator, which contains the logic for the retry scheme. Each operator runs in its own thread, which terminates when the operation is complete. If another operation of the same turnout is made before the first one completes, the older thread terminates itself when it realises it is no longer the active operation for the turnout.

The parameters of a TurnoutOperation can be edited. Each subclass has its own xxxTurnoutOperationConfig class, which knows how to display the parameters in a JPanel and gather them up again and store them afterwards.

Each subclass also has its own xxxTurnoutOperationXml class, which knows how to store the information in an XML element, and restore it.

The current code defines two operations, NoFeedback and Sensor. Because these have so much in common (only the xxxTurnoutOperator class has any differences), most of them is implemented in the CommonTurnout... classes. This family is not part of the general structure, although it can be reused if it helps.

Extensibility

To write a new type of operation:

1. Create the xxxTurnoutOperation class 2. Create the xxxTurnoutOperator class, including the logic for what you're trying to do 3. Create the xxxTurnoutOperationConfig class - the CommonTurnoutOperationConfig class can be used as a reference 4. Create the xxxTurnoutOperationXml class - again the Common... class can be used as a reference 5. Add the prefix to the class name (e.g. "Tortoise") to the list AbstractTurnoutManager.validOperationTypes, otherwise it will not be instantiated at startup and hence will not be available

To change the behavior for a particular system type:

There are some functions which can be overridden in the system-specific subclasses to change default behaviour if desired. These mechanisms are orthogonal to the operation subclasses.

1. Override AbstractTurnoutManager.getValidOperationTypes to change the operation types allowed for this system. 2. Override AbstractTurnout.getFeedbackModeForOperation to map system-specific feedback modes into modes that the general classes know about. 3. Override AbstractTurnout.getTurnoutOperator if you want to do something really different.

Author:

John Harper Copyright 2005

Method Summary

void	addPropertyChangeListener(PropertyChangeListener l)
int	compareTo(Object other) ordering so operations can be sorted, using their name
void	dispose() delete all knowledge of this operation.
abstract boolean	equivalentTo(TurnoutOperation other)
TurnoutOperation	getDefinitive() get the definitive operation for this parameter variation
String	getName() get the descriptive name of the operation
abstract TurnoutOperator	getOperator(AbstractTurnout t) Get an instance of the operator for this operation type, set up and started to do its thing in a private thread for the specified turnout.
boolean	isDefinitive()
boolean	isDeleted()
boolean	isInUse() see if operation is in use (needed by the UI)
boolean	isNonce() Nonce support.
abstract TurnoutOperation	makeCopy(String n) factory to make a copy of an operation identical in all respects except the name
TurnoutOperation	makeNonce(Turnout t)
boolean	matchFeedbackMode(int mode)
void	removePropertyChangeListener(PropertyChangeListener l)
boolean	rename(String newName) rename an operation
protected void	setFeedbackModes(int fm) set feedback modes - part of construction but done separately for ordering problems
void	setNonce(boolean n)

Methods inherited from class java.lang.Object

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

Method Detail

makeCopy

public abstract TurnoutOperation makeCopy(String n)

factory to make a copy of an operation identical in all respects except the name

Parameters:

n - name for new copy

Returns:

TurnoutOperation of same concrete class as this

setFeedbackModes

protected void setFeedbackModes(int fm)

set feedback modes - part of construction but done separately for ordering problems

Parameters:

fm - valid feedback modes for this class

getName

public String getName()

get the descriptive name of the operation

Returns:

name

compareTo

public int compareTo(Object other)

ordering so operations can be sorted, using their name

Specified by:

compareTo in interface Comparable

Parameters:

other - other TurnoutOperation object

Returns:

usual compareTo return values

equivalentTo

public abstract boolean equivalentTo(TurnoutOperation other)

Parameters:

other - another TurnoutOperation

Returns:

true iff the two operations are equivalent, i.e. same subclass and same parameters

rename

public boolean rename(String newName)

rename an operation

Parameters:

newName -

Returns:

true iff the name was changed to the new value - otherwise name is unchanged

getDefinitive

public TurnoutOperation getDefinitive()

get the definitive operation for this parameter variation

Returns:

definitive operation

isDefinitive

public boolean isDefinitive()

Returns:

true iff this is the "defining instance" of the class, which we determine by the name of the instance being the same as the prefix of the class

getOperator

public abstract TurnoutOperator getOperator(AbstractTurnout t)

Get an instance of the operator for this operation type, set up and started to do its thing in a private thread for the specified turnout.

Parameters:

t - the turnout to apply the operation to

Returns:

the operator

dispose

public void dispose()

delete all knowledge of this operation. Reset any turnouts using it to the default

isDeleted

public boolean isDeleted()

isInUse

public boolean isInUse()

see if operation is in use (needed by the UI)

Returns:

true iff any turnouts are using it

isNonce

public boolean isNonce()

Nonce support. A nonce is a TurnoutOperation created specifically for one turnout, which can't be directly referred to by name. It does have a name, which is the turnout it was created for, prefixed by "*"

Returns:

true if this object is a nonce

setNonce

public void setNonce(boolean n)

makeNonce

public TurnoutOperation makeNonce(Turnout t)

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)

matchFeedbackMode

public boolean matchFeedbackMode(int mode)

Parameters:

mode - feedback mode for a turnout

Returns:

true iff this operation's feedback mode is one we know how to deal with