Package jmri.jmrix.can.cbus

Class CbusThrottleManager

java.lang.Object

jmri.jmrix.AbstractThrottleManager

jmri.jmrix.can.cbus.CbusThrottleManager

All Implemented Interfaces:

java.util.EventListener, Disposable, AbstractMRListener, CanListener, ThrottleManager

public class CbusThrottleManager
extends AbstractThrottleManager
implements CanListener, Disposable

CBUS implementation of a ThrottleManager.

Nested Class Summary

Nested classes/interfaces inherited from class jmri.jmrix.AbstractThrottleManager

AbstractThrottleManager.Addresses

Field Summary

Fields

Modifier and Type	Field	Description
protected int	THROTTLE_TIMEOUT

Fields inherited from class jmri.jmrix.AbstractThrottleManager

adapterMemo, userName

Constructor Summary

Constructors

Constructor	Description
CbusThrottleManager(CanSystemConnectionMemo memo)

Method Summary

Modifier and Type	Method	Description
boolean	addressTypeUnique()	Short and long address spaces overlap and are not unique.
boolean	canBeLongAddress(int address)	Any address is potentially a long address.
boolean	canBeShortAddress(int address)	Address 127 and below is a short address.
void	cancelThrottleRequest(LocoAddress address, ThrottleListener l)	Cancel a request for a throttle.
void	dispose()	Allow to cleanly release the traffic controller in ThrottleManager Tests remove listeners, if any stop timers, is any
boolean	disposeThrottle(DccThrottle t, ThrottleListener l)	Not for general use, see releaseThrottle and dispatchThrottle.
boolean	enablePrefSilentShareOption()	Hardware has a sharing implementation.
boolean	enablePrefSilentStealOption()	Hardware has a stealing implementation.
protected void	forceDisposeThrottle(LocoAddress la)	Throttle can no longer be relied upon, potentially from an external forced steal or hardware error.
boolean	hasDispatchFunction()	CBUS has a dynamic Dispatch function, defaulting to false Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary
(package private) static boolean	isLongAddress(int num)	Local method for deciding short/long address.
protected void	makeHardwareDecision(LocoAddress address, ThrottleListener.DecisionType question)	CBUS Hardware will make its own decision on preferred option.
void	message(CanMessage m)	Called when an outgoing message is sent to the CAN Network.
void	reply(CanReply m)	Called when an incoming CanFrame is received from the CAN Network.
void	requestThrottleSetup(LocoAddress address, boolean control)	Abstract member to actually do the work of configuring a new throttle, usually via interaction with the DCC system.
void	responseThrottleDecision(LocoAddress address, ThrottleListener l, ThrottleListener.DecisionType decision)	Send a request to steal or share a requested throttle.
protected boolean	singleUse()	CBUS allows Throttle sharing, both internally within JMRI and externally by command stations
java.util.EnumSet<SpeedStepMode>	supportedSpeedModes()	MERG CBUS Throttle sessions default to 128 SS.
protected void	updateNumUsers(LocoAddress la, int numUsers)	The number of users of this throttle has been updated

Methods inherited from class jmri.jmrix.AbstractThrottleManager

addressReleased, addressStillRequired, addressStillRequired, addressStillRequired, addressStillRequired, attachListener, cancelThrottleRequest, cancelThrottleRequest, cancelThrottleRequest, dispatchThrottle, failedThrottleRequest, getAddress, getAddress, getAddressProtocolTypes, getAddressTypes, getAddressTypeString, getProtocolFromString, getThrottleInfo, getThrottleUsageCount, getThrottleUsageCount, getThrottleUsageCount, getThrottleUsageCount, getUserName, hideStealNotifications, notifyDecisionRequest, notifyThrottleKnown, releaseThrottle, removeListener, requestThrottle, requestThrottle, requestThrottle, requestThrottle, requestThrottle, requestThrottle, requestThrottleSetup, responseThrottleDecision, responseThrottleDecision, showSessionCancelDialogue

Methods inherited from class java.lang.Object

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

Methods inherited from interface jmri.jmrix.can.CanListener

addTc, addTc, removeTc, removeTc

Field Detail

THROTTLE_TIMEOUT

protected int THROTTLE_TIMEOUT

Constructor Detail

CbusThrottleManager

public CbusThrottleManager(CanSystemConnectionMemo memo)

Method Detail

dispose

public void dispose()

Allow to cleanly release the traffic controller in ThrottleManager Tests

• remove listeners, if any
• stop timers, is any

Specified by:

dispose in interface Disposable

Specified by:

dispose in interface ThrottleManager

Overrides:

dispose in class AbstractThrottleManager

singleUse

protected boolean singleUse()

CBUS allows Throttle sharing, both internally within JMRI and externally by command stations

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

Overrides:

singleUse in class AbstractThrottleManager

Returns:

true or false

requestThrottleSetup

public void requestThrottleSetup(LocoAddress address,
                                 boolean control)

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

Specified by:

requestThrottleSetup in class AbstractThrottleManager

Parameters:

address - address

control - false - read only.

message

public void message(CanMessage m)

Called when an outgoing message is sent to the CAN Network.

Specified by:

message in interface CanListener

Parameters:

m - the CanMessage being sent.

reply

public void reply(CanReply m)

Called when an incoming CanFrame is received from the CAN Network.

Specified by:

reply in interface CanListener

Parameters:

m - the CanReply being received.

hasDispatchFunction

public boolean hasDispatchFunction()

CBUS has a dynamic Dispatch function, defaulting to false Check to see if the Dispatch Button should be enabled or not Default to true, override if necessary

Specified by:

hasDispatchFunction in interface ThrottleManager

Overrides:

hasDispatchFunction in class AbstractThrottleManager

Returns:

true if dispatch is possible; false otherwise

canBeLongAddress

public boolean canBeLongAddress(int address)

Any address is potentially a long address. Test if a specific number is a valid long address on this system.

Specified by:

canBeLongAddress in interface ThrottleManager

Parameters:

address - address number to test

Returns:

true if address can be long; false otherwise

canBeShortAddress

public boolean canBeShortAddress(int address)

Address 127 and below is a short address. Test if a specific number is a valid short address on this system.

Specified by:

canBeShortAddress in interface ThrottleManager

Parameters:

address - address number to test

Returns:

true if address can be short; false otherwise

addressTypeUnique

public boolean addressTypeUnique()

Short and long address spaces overlap and are not unique.

Specified by:

addressTypeUnique in interface ThrottleManager

Returns:

always false. true if ambiguous addresses are not allowed; false otherwise

isLongAddress

static boolean isLongAddress(int num)

Local method for deciding short/long address.

Parameters:

num - the address number

Returns:

true if address equal to or greater than 128.

enablePrefSilentStealOption

public boolean enablePrefSilentStealOption()

Hardware has a stealing implementation. Hardware that uses the Silent Steal preference will need to override Test if the Silent Steal Throttles preference option should be enabled.

Specified by:

enablePrefSilentStealOption in interface ThrottleManager

Overrides:

enablePrefSilentStealOption in class AbstractThrottleManager

Returns:

true if steal is possible; false otherwise

enablePrefSilentShareOption

public boolean enablePrefSilentShareOption()

Hardware has a sharing implementation. Hardware that uses the Silent Share preference will need to override Test if the Silent Share Throttles preference option should be enabled.

Specified by:

enablePrefSilentShareOption in interface ThrottleManager

Overrides:

enablePrefSilentShareOption in class AbstractThrottleManager

Returns:

true if steal is possible; false otherwise

makeHardwareDecision

protected void makeHardwareDecision(LocoAddress address,
                                    ThrottleListener.DecisionType question)

CBUS Hardware will make its own decision on preferred option.

This is the default for scripts that do NOT have a GUI for asking what to do when a steal / share decision is required. For when a steal / share decision is needed and the ThrottleListener has delegated this decision to the ThrottleManager.

Responds to the question by requesting a Throttle "Steal" by default.

Can be overridden by hardware types which do not wish the default behaviour to Steal.

This applies only to those systems where "stealing" or "sharing" applies, such as LocoNet.

Overrides:

makeHardwareDecision in class AbstractThrottleManager

Parameters:

address - The LocoAddress the steal / share question relates to

question - The Question to be put to the ThrottleListener

responseThrottleDecision

public void responseThrottleDecision(LocoAddress address,
                                     ThrottleListener l,
                                     ThrottleListener.DecisionType decision)

Send a request to steal or share a requested throttle.

Steal or Share a requested throttle.

Specified by:

responseThrottleDecision in interface ThrottleManager

Overrides:

responseThrottleDecision in class AbstractThrottleManager

Parameters:

address - desired LocoAddress

l - The ThrottleListener which has made the decision

decision - from the ThrottleListener, STEAL or SHARE.

supportedSpeedModes

public java.util.EnumSet<SpeedStepMode> supportedSpeedModes()

MERG CBUS Throttle sessions default to 128 SS. This can be changed by a subsequent message from Throttle to CS, or by message from Command Station to CbusThrottle. Supported modes are 128, 28 and 14. 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

Overrides:

supportedSpeedModes in class AbstractThrottleManager

Returns:

an XOR of the possible modes specified in the throttle interface

disposeThrottle

public boolean disposeThrottle(DccThrottle t,
                               ThrottleListener l)

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

Overrides:

disposeThrottle in class AbstractThrottleManager

Parameters:

t - Throttle being released

l - Throttle Listener releasing the throttle

Returns:

true if the throttle has been disposed of.

forceDisposeThrottle

protected void forceDisposeThrottle(LocoAddress la)

Throttle can no longer be relied upon, potentially from an external forced steal or hardware error.

Normally, #releaseThrottle should be used to close throttles.

Removes locoaddress from list to force new throttle requests to request new sessions where the Command station model implements a dynamic stack, not a static stack.

Managers still need to advise listeners that the session has been cancelled and actually dispose of the throttle

Overrides:

forceDisposeThrottle in class AbstractThrottleManager

Parameters:

la - address release

updateNumUsers

protected void updateNumUsers(LocoAddress la,
                              int numUsers)

The number of users of this throttle has been updated

Typically used to update dispatch / release availablility specific implementations can override this function to get updates

Overrides:

updateNumUsers in class AbstractThrottleManager

Parameters:

la - the Loco Address which has been updated

numUsers - current number of users

cancelThrottleRequest

public void cancelThrottleRequest(LocoAddress address,
                                  ThrottleListener l)

Cancel a request for a throttle.

Specified by:

cancelThrottleRequest in interface ThrottleManager

Overrides:

cancelThrottleRequest in class AbstractThrottleManager

Parameters:

address - unwanted Loco address

l - ThrottleListener canceling request for a throttle