jmri.jmrix
Class AbstractThrottleManager

Show UML class diagram

java.lang.Object
  jmri.jmrix.AbstractThrottleManager

All Implemented Interfaces:

ThrottleManager

Direct Known Subclasses:

CbusThrottleManager, DebugThrottleManager, EasyDccThrottleManager, EcosDccThrottleManager, LnPr2ThrottleManager, LnThrottleManager, MarklinThrottleManager, NceThrottleManager, OlcbThrottleManager, SerialThrottleManager, SprogCSThrottleManager, SprogThrottleManager, SRCPThrottleManager, TamsThrottleManager, ThrottleManager, XNetThrottleManager, XpaThrottleManager

public abstract class AbstractThrottleManager
extends Object
implements ThrottleManager

Abstract implementation of a ThrottleManager.

Based on Glen Oberhauser's original LnThrottleManager implementation.

Nested Class Summary

protected static class	AbstractThrottleManager.Addresses This subClass, keeps track of which loco address have been requested and by whom, it primarily uses a increment count to keep track of all the the Addresses in use as not all external code will have been refactored over to use the new disposeThrottle.
(package private) static class	AbstractThrottleManager.WaitingThrottle

Field Summary

protected SystemConnectionMemo	adapterMemo
(package private) static org.slf4j.Logger	log
protected String	userName

Constructor Summary

AbstractThrottleManager()

AbstractThrottleManager(SystemConnectionMemo memo)

Method Summary

protected boolean	addressReleased(DccLocoAddress la, ThrottleListener l)
boolean	addressStillRequired(DccLocoAddress la)
void	attachListener(BasicRosterEntry re, PropertyChangeListener p)
void	attachListener(DccLocoAddress la, BasicRosterEntry re, PropertyChangeListener p)
void	attachListener(DccLocoAddress la, PropertyChangeListener p) Attach a PropertyChangeListener to a specific loco address, where the requesting code does not need or require control over the loco.
void	cancelThrottleRequest(BasicRosterEntry re, ThrottleListener l) Cancel a request for a throttle.
void	cancelThrottleRequest(int address, boolean isLong, ThrottleListener l) Cancel a request for a throttle
void	cancelThrottleRequest(int address, ThrottleListener l) Cancel a request for a throttle.
void	dispatchThrottle(DccThrottle t, ThrottleListener l) The throttle listener has finished with the specific Throttle and is is available for reuse/reallocation by somebody else.
boolean	disposeThrottle(DccThrottle t, ThrottleListener l) Not for general use, see releaseThrottle and dispatchThrottle.
void	failedThrottleRequest(DccLocoAddress address, String reason) If the system-specific ThrottleManager has been unable to create the DCC throttle then it needs to be removed from the throttleListeners, otherwise any subsequent request for that address results in the address being reported as already in use, if singleUse is set.
LocoAddress	getAddress(String value, LocoAddress.Protocol protocol)
LocoAddress	getAddress(String value, String protocol) Get the object representing a particular address
LocoAddress.Protocol[]	getAddressProtocolTypes() returns an Integer list of different protocols that are supported by system, to include short vs long or DCC vs Selectrix vs Motorola
String[]	getAddressTypes() By default, only DCC in this implementation
String	getAddressTypeString(LocoAddress.Protocol prot) By default, only DCC in this implementation
LocoAddress.Protocol	getProtocolFromString(String selection) Get the integer value representing a protocol
Object	getThrottleInfo(DccLocoAddress la, String item) Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has used the attachListener to only be notified of changes in the throttle and not control it.
String	getUserName() A method to get the Name of the system that the programmer is associated with.
boolean	hasDispatchFunction() Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary
void	notifyThrottleKnown(DccThrottle throttle, LocoAddress addr) Handle throttle information when it's finally available, e.g. when a new Throttle object has been created.
void	releaseThrottle(DccThrottle t, ThrottleListener l) The specified Throttle Listener has finished using a given throttle and no longer requires access to it.
void	removeListener(DccLocoAddress la, PropertyChangeListener p) Remove a PropertyChangeListener to a specific loco address, where the requesting code has used attachListener to get notification of changes in a throttle.
boolean	requestThrottle(BasicRosterEntry re, ThrottleListener l) Request a throttle from a given Roster Entry.
boolean	requestThrottle(DccLocoAddress la, BasicRosterEntry re, ThrottleListener l) Request a throttle, given a decoder address.
boolean	requestThrottle(DccLocoAddress la, ThrottleListener l) Request a throttle, given a decoder address.
boolean	requestThrottle(int address, boolean isLongAddress, ThrottleListener l) Request a throttle, given a decoder address & whether it is a long or short DCC address.
boolean	requestThrottle(int address, ThrottleListener l) Request a throttle, given a decoder address.
void	requestThrottleSetup(LocoAddress a) Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system
abstract void	requestThrottleSetup(LocoAddress a, boolean control) Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system
protected boolean	singleUse() Does this DCC system allow a Throttle (e.g. an address) to be used by only one user at a time?
int	supportedSpeedModes() What speed modes are supported by this system?

Methods inherited from class java.lang.Object

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

Methods inherited from interface jmri.ThrottleManager

addressTypeUnique, canBeLongAddress, canBeShortAddress

Field Detail

adapterMemo

protected SystemConnectionMemo adapterMemo

userName

protected String userName

log

static org.slf4j.Logger log

Constructor Detail

AbstractThrottleManager

public AbstractThrottleManager()

AbstractThrottleManager

public AbstractThrottleManager(SystemConnectionMemo memo)

Method Detail

getUserName

public String getUserName()

Description copied from interface: ThrottleManager

A method to get the Name of the system that the programmer is associated with.

Specified by:

getUserName in interface ThrottleManager

getAddressTypes

public String[] getAddressTypes()

By default, only DCC in this implementation

Specified by:

getAddressTypes in interface ThrottleManager

getAddressTypeString

public String getAddressTypeString(LocoAddress.Protocol prot)

By default, only DCC in this implementation

Specified by:

getAddressTypeString in interface ThrottleManager

getAddressProtocolTypes

public LocoAddress.Protocol[] getAddressProtocolTypes()

Description copied from interface: ThrottleManager

returns an Integer list of different protocols that are supported by system, to include short vs long or DCC vs Selectrix vs Motorola

Specified by:

getAddressProtocolTypes in interface ThrottleManager

getAddress

public LocoAddress getAddress(String value,
                              LocoAddress.Protocol protocol)

Specified by:

getAddress in interface ThrottleManager

getAddress

public LocoAddress getAddress(String value,
                              String protocol)

Description copied from interface: ThrottleManager

Get the object representing a particular address

Specified by:

getAddress in interface ThrottleManager

Parameters:

value - String in format specific to the protocol

protocol - specific protocol string, see the specific throttle manager for values

Returns:

probably of a subtype

getProtocolFromString

public LocoAddress.Protocol getProtocolFromString(String selection)

Description copied from interface: ThrottleManager

Get the integer value representing a protocol

Specified by:

getProtocolFromString in interface ThrottleManager

Returns:

the integer value of the protocol

singleUse

protected boolean singleUse()

Does this DCC system allow a Throttle (e.g. an address) to be used by only one user at a time?

requestThrottle

public boolean requestThrottle(BasicRosterEntry re,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Request a throttle from a given Roster Entry. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

re - The Roster Entry desired.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(int address,
                               boolean isLongAddress,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Request a throttle, given a decoder address & whether it is a long or short DCC address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

address - The decoder address desired.

isLongAddress - True if this is a request for a DCC long (extended) address.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(DccLocoAddress la,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Request a throttle, given a decoder address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

la - The decoder address desired.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(DccLocoAddress la,
                               BasicRosterEntry re,
                               ThrottleListener l)

Request a throttle, given a decoder address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

la - DccLocoAddress of the decoder desired.

l - The ThrottleListener awaiting notification of a found throttle.

re - The RosterEntry desired.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottle

public boolean requestThrottle(int address,
                               ThrottleListener l)

Request a throttle, given a decoder address. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

requestThrottle in interface ThrottleManager

Parameters:

address - The decoder address desired.

l - The ThrottleListener awaiting notification of a found throttle.

Returns:

True if the request will continue, false if the request will not be made. False may be returned if a the throttle is already in use.

requestThrottleSetup

public abstract void requestThrottleSetup(LocoAddress a,
                                          boolean control)

Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system

requestThrottleSetup

public void requestThrottleSetup(LocoAddress a)

Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system

cancelThrottleRequest

public void cancelThrottleRequest(int address,
                                  boolean isLong,
                                  ThrottleListener l)

Cancel a request for a throttle

Specified by:

cancelThrottleRequest in interface ThrottleManager

Parameters:

address - The decoder address desired.

isLong - True if this is a request for a DCC long (extended) address.

l - The ThrottleListener cancelling request for a throttle.

cancelThrottleRequest

public void cancelThrottleRequest(BasicRosterEntry re,
                                  ThrottleListener l)

Description copied from interface: ThrottleManager

Cancel a request for a throttle.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

cancelThrottleRequest in interface ThrottleManager

Parameters:

re - The Roster Entry desired.

l - The ThrottleListener cancelling request for a throttle.

cancelThrottleRequest

public void cancelThrottleRequest(int address,
                                  ThrottleListener l)

Cancel a request for a throttle.

This is a convenience version of the call, which uses system-specific logic to tell whether the address is a short or long form.

Specified by:

cancelThrottleRequest in interface ThrottleManager

Parameters:

address - The decoder address desired.

l - The ThrottleListener cancelling request for a throttle.

failedThrottleRequest

public void failedThrottleRequest(DccLocoAddress address,
                                  String reason)

If the system-specific ThrottleManager has been unable to create the DCC throttle then it needs to be removed from the throttleListeners, otherwise any subsequent request for that address results in the address being reported as already in use, if singleUse is set. This also sends a notification message back to the requestor with a string reason as to why the request has failed.

Parameters:

address - The DCC Loco Address that the request failed on.

reason - A text string passed by the ThrottleManae as to why

notifyThrottleKnown

public void notifyThrottleKnown(DccThrottle throttle,
                                LocoAddress addr)

Handle throttle information when it's finally available, e.g. when a new Throttle object has been created.

This method creates a throttle for all ThrottleListeners of that address and notifies them via the ThrottleListener.notifyThrottleFound method.

hasDispatchFunction

public boolean hasDispatchFunction()

Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary

Specified by:

hasDispatchFunction in interface ThrottleManager

supportedSpeedModes

public int supportedSpeedModes()

What speed modes are supported by this system? value should be xor of possible modes specifed by the DccThrottle interface

Specified by:

supportedSpeedModes in interface ThrottleManager

attachListener

public void attachListener(BasicRosterEntry re,
                           PropertyChangeListener p)

attachListener

public void attachListener(DccLocoAddress la,
                           PropertyChangeListener p)

Description copied from interface: ThrottleManager

Attach a PropertyChangeListener to a specific loco address, where the requesting code does not need or require control over the loco. If the loco address is not in the active in the list, then a new throttle will be created by the manager and the listener attached.

The propertyChangeListener will be notified if it has been attached to a loco address or not, via a propertyChange notification.

Specified by:

attachListener in interface ThrottleManager

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attach to the throttle

attachListener

public void attachListener(DccLocoAddress la,
                           BasicRosterEntry re,
                           PropertyChangeListener p)

removeListener

public void removeListener(DccLocoAddress la,
                           PropertyChangeListener p)

Description copied from interface: ThrottleManager

Remove a PropertyChangeListener to a specific loco address, where the requesting code has used attachListener to get notification of changes in a throttle.

The propertyChangeListener will be notified if it has been removed via a propertyChange notification.

Specified by:

removeListener in interface ThrottleManager

Parameters:

la - - DccLocoAddress of the loco we wish to monitor

p - - PropertyChangeListener to attachremove from the throttle

addressStillRequired

public boolean addressStillRequired(DccLocoAddress la)

Specified by:

addressStillRequired in interface ThrottleManager

releaseThrottle

public void releaseThrottle(DccThrottle t,
                            ThrottleListener l)

Description copied from interface: ThrottleManager

The specified Throttle Listener has finished using a given throttle and no longer requires access to it.

After releasing the throttle, the manager will perform further checks to see if it is in use by any other listeners or if there are any propertychangelisteners attached. If there are no other uses of the throttle then it is disposed of.

Normally, release ends with a call to dispose.

Specified by:

releaseThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

disposeThrottle

public boolean disposeThrottle(DccThrottle t,
                               ThrottleListener l)

Description copied from interface: ThrottleManager

Not for general use, see releaseThrottle and dispatchThrottle.

Dispose of object when finished it. This will free up hardware resource

Used for handling certain internal error conditions, where the object still exists but hardware is not associated with it.

After this, further usage of this Throttle object will result in a JmriException.

Specified by:

disposeThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

Returns:

true if the throttle has been disposed of.

dispatchThrottle

public void dispatchThrottle(DccThrottle t,
                             ThrottleListener l)

Description copied from interface: ThrottleManager

The throttle listener has finished with the specific Throttle and is is available for reuse/reallocation by somebody else. If possible, tell the layout that this locomotive has been dispatched to another user. Not all layouts will implement this, in which case it is synomous with release();

Normally, dispatch ends with a call to dispose.

Specified by:

dispatchThrottle in interface ThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

addressReleased

protected boolean addressReleased(DccLocoAddress la,
                                  ThrottleListener l)

getThrottleInfo

public Object getThrottleInfo(DccLocoAddress la,
                              String item)

Description copied from interface: ThrottleManager

Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has used the attachListener to only be notified of changes in the throttle and not control it.

Valid values for item are IsForward SpeedSetting SpeedIncrement SpeedStepMode F0-F28

Specified by:

getThrottleInfo in interface ThrottleManager

Parameters:

la - DccLocoAddress that we wish interrogate

item - A string of the item we wish to know the value of.

Returns:

the value as an objet, if the loco address has not been assigned to a throttle or the item value is not valid, null is returned.