Interface ThrottleManager
- All Known Implementing Classes:
AbstractThrottleManager
,CbusThrottleManager
,DCCppThrottleManager
,DebugThrottleManager
,EasyDccThrottleManager
,EcosDccThrottleManager
,EliteXNetThrottleManager
,Ib1ThrottleManager
,Ib2ThrottleManager
,LnPr2ThrottleManager
,LnThrottleManager
,MarklinThrottleManager
,MrcThrottleManager
,Mx1ThrottleManager
,NceThrottleManager
,OlcbThrottleManager
,RocoXNetThrottleManager
,SerialThrottleManager
,SprogCSThrottleManager
,SprogThrottleManager
,SRCPThrottleManager
,TamsThrottleManager
,ThrottleManager
,UhlenbrockLnThrottleManager
,XNetThrottleManager
,XpaThrottleManager
,Z21XNetThrottleManager
public interface ThrottleManager
Throttle
objects.
"Address" is interpreted in the context of the DCC implementation. Different systems will distinguish between short and long addresses in different ways.
When the allocated Throttle is no longer needed, it is told that it's released. If a specific ThrottleManager and/or Throttle implementation needs to keep track of that operation, it is handled internally.
This file is part of JMRI.
JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.
JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
-
Method Summary
Modifier and Type Method Description boolean
addressStillRequired(int address)
boolean
addressStillRequired(int address, boolean addressIsLong)
boolean
addressStillRequired(BasicRosterEntry re)
boolean
addressStillRequired(LocoAddress la)
boolean
addressTypeUnique()
Test if ambiguous addresses (short vs long) are not allowed on this system.void
attachListener(LocoAddress la, PropertyChangeListener p)
Attach a PropertyChangeListener to a specific loco address, where the requesting code does not need or require control over the loco.boolean
canBeLongAddress(int address)
Test if a specific number is a valid long address on this system.boolean
canBeShortAddress(int address)
Test if a specific number is a valid short address on this system.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
cancelThrottleRequest(BasicRosterEntry re, ThrottleListener l)
Cancel a request for a throttle.void
cancelThrottleRequest(LocoAddress 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.void
dispose()
Allow to cleanly release the traffic controller in ThrottleManager Tests remove listeners, if any stop timers, is anyboolean
disposeThrottle(DccThrottle t, ThrottleListener l)
Not for general use, seereleaseThrottle
anddispatchThrottle
.boolean
enablePrefSilentShareOption()
Test if the Silent Share Throttles preference option should be enabled.boolean
enablePrefSilentStealOption()
Test if the Silent Steal Throttles preference option should be enabled.LocoAddress
getAddress(String value, String protocol)
Get the object representing a particular address.LocoAddress
getAddress(String value, LocoAddress.Protocol protocol)
Get the object representing a particular address.LocoAddress.Protocol[]
getAddressProtocolTypes()
Get a list of different protocols supported by the system, to include short vs long or DCC vs Selectrix vs Motorola.String[]
getAddressTypes()
This returns a list of the different protocols that are supported by the system, to include short vs long or DCC vs Selectrix vs Motorola.String
getAddressTypeString(LocoAddress.Protocol prot)
Get a string value for a given protocol value.LocoAddress.Protocol
getProtocolFromString(String selection)
Get a protocol given a description.Object
getThrottleInfo(LocoAddress la, String item)
Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has usedattachListener
to only be notified of changes in the throttle and not control it.int
getThrottleUsageCount(int address)
Get the number of Throttles sharing the throttle for a ddcaddress.int
getThrottleUsageCount(int address, boolean isLongAddress)
Get the number of Throttles sharing the throttle for a ddcaddress.int
getThrottleUsageCount(BasicRosterEntry re)
Get the number of Throttles sharing the throttle for a ddcaddress.int
getThrottleUsageCount(LocoAddress la)
Get the number of Throttles sharing the throttle for a ddcaddress.String
getUserName()
Get the user name of the system that the programmer is associated with.boolean
hasDispatchFunction()
Test if the Dispatch Button should be enabled or not.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(LocoAddress la, PropertyChangeListener p)
Remove a PropertyChangeListener to a specific loco address, where the requesting code has usedattachListener
to get notification of changes in a throttle.boolean
requestThrottle(int address, boolean isLong, ThrottleListener l)
Deprecated.since 4.15.7; use #requestThrottle(int, boolean, ThrottleListener, boolean) insteadboolean
requestThrottle(int address, boolean isLong, ThrottleListener l, boolean canHandleDecisions)
Request a throttle, given a decoder address and whether it is a long or short DCC address.boolean
requestThrottle(int address, ThrottleListener l)
Request a throttle, given a decoder address.boolean
requestThrottle(int address, ThrottleListener l, boolean canHandleDecisions)
Request a throttle, given a decoder address.boolean
requestThrottle(BasicRosterEntry re, ThrottleListener l)
Deprecated.since 4.15.7; use #requestThrottle(BasicRosterEntry, ThrottleListener, boolean) insteadboolean
requestThrottle(BasicRosterEntry re, ThrottleListener l, boolean canHandleDecisions)
Request a throttle from a given RosterEntry.boolean
requestThrottle(LocoAddress address, BasicRosterEntry re, ThrottleListener l)
Deprecated.since 4.15.7; use #requestThrottle(LocoAddress, ThrottleListener, boolean) or #requestThrottle(BasicRosterEntry, ThrottleListener, boolean) insteadboolean
requestThrottle(LocoAddress address, ThrottleListener l)
Deprecated.since 4.15.7; use #requestThrottle(LocoAddress, ThrottleListener, boolean) insteadboolean
requestThrottle(LocoAddress address, ThrottleListener l, boolean canHandleDecisions)
Request a throttle, given a LocoAddress.void
responseThrottleDecision(int address, boolean isLong, ThrottleListener l, ThrottleListener.DecisionType decision)
Steal or Share a requested throttle.void
responseThrottleDecision(int address, ThrottleListener l, ThrottleListener.DecisionType decision)
Steal or Share a requested throttle.void
responseThrottleDecision(LocoAddress address, ThrottleListener l, ThrottleListener.DecisionType decision)
Steal or Share a requested throttle.void
stealThrottleRequest(int address, boolean isLong, ThrottleListener l, boolean steal)
Deprecated.since 4.15.7; use #responseThrottleDecisionvoid
stealThrottleRequest(int address, ThrottleListener l, boolean steal)
Deprecated.since 4.15.7; use #responseThrottleDecisionvoid
stealThrottleRequest(BasicRosterEntry re, ThrottleListener l, boolean steal)
Deprecated.void
stealThrottleRequest(LocoAddress address, ThrottleListener l, boolean steal)
Deprecated.since 4.15.7; use #responseThrottleDecisionEnumSet<SpeedStepMode>
supportedSpeedModes()
Get the supported speed modes.
-
Method Details
-
requestThrottle
Deprecated.since 4.15.7; use #requestThrottle(BasicRosterEntry, ThrottleListener, boolean) insteadRequest a throttle from a given RosterEntry. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.- Parameters:
re
- desired RosterEntryl
- 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
Request a throttle from a given RosterEntry. When the decoder address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.- Parameters:
re
- desired RosterEntryl
- ThrottleListener awaiting notification of a found throttlecanHandleDecisions
- true if the ThrottleListener has a mechanism for dealing with Share / Steal decisions, else false- 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
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, and assumes that the hardware makes and steal / share decisions.
- Parameters:
address
- desired decoder addressl
- 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
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, and assumes that the hardware makes and steal / share decisions.
- Parameters:
canHandleDecisions
- true if the ThrottleListener has a mechanism for dealing with Share / Steal decisions, else falseaddress
- desired decoder addressl
- 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
Deprecated.since 4.15.7; use #requestThrottle(int, boolean, ThrottleListener, boolean) insteadRequest a throttle, given a decoder address and 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.- Parameters:
address
- desired decoder addressisLong
- true if requesting a DCC long (extended) addressl
- 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
boolean requestThrottle(int address, boolean isLong, ThrottleListener l, boolean canHandleDecisions)Request a throttle, given a decoder address and 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.- Parameters:
address
- desired decoder addressisLong
- true if requesting a DCC long (extended) addressl
- ThrottleListener awaiting notification of a found throttlecanHandleDecisions
- true if the ThrottleListener has a mechanism for dealing with Share / Steal decisions, else false- 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
Deprecated.since 4.15.7; use #requestThrottle(LocoAddress, ThrottleListener, boolean) insteadRequest 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.
- Parameters:
address
- desired decoder addressl
- 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
Deprecated.since 4.15.7; use #requestThrottle(LocoAddress, ThrottleListener, boolean) or #requestThrottle(BasicRosterEntry, ThrottleListener, boolean) insteadRequest a throttle, given a decoder address or a RosterEntry. 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.
- Parameters:
address
- desired decoder addressre
- desired RosterEntryl
- 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
Request a throttle, given a LocoAddress. When the address is located, the ThrottleListener gets a callback via the ThrottleListener.notifyThrottleFound method.- Parameters:
address
- desired loco addressl
- ThrottleListener awaiting notification of a found throttlecanHandleDecisions
- true if the ThrottleListener has a mechanism for dealing with Share / Steal decisions, else false- 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
-
cancelThrottleRequest
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.
- Parameters:
re
- desired Roster Entryl
- ThrottleListener canceling the request for a throttle
-
cancelThrottleRequest
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.
- Parameters:
address
- desired decoder addressl
- ThrottleListener canceling request for a throttle
-
cancelThrottleRequest
Cancel a request for a throttle.- Parameters:
address
- desired decoder addressisLong
- true if requesting a DCC long (extended) addressl
- ThrottleListener canceling request for a throttle
-
cancelThrottleRequest
Cancel a request for a throttle.- Parameters:
address
- unwanted Loco addressl
- ThrottleListener canceling request for a throttle
-
stealThrottleRequest
Deprecated.Steal a requested 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.
- Parameters:
re
- desired Roster Entryl
- ThrottleListener requesting the throttle steal occur.steal
- true if the request should continue, false otherwise.- Since:
- 4.9.2
-
stealThrottleRequest
Deprecated.since 4.15.7; use #responseThrottleDecisionSteal a requested 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.
- Parameters:
address
- desired decoder addressl
- ThrottleListener requesting the throttle steal occur.steal
- true if the request should continue, false otherwise.- Since:
- 4.9.2
-
stealThrottleRequest
Deprecated.since 4.15.7; use #responseThrottleDecisionSteal a requested 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.
- Parameters:
address
- desired decoder addressl
- ThrottleListener requesting the throttle steal occur.steal
- true if the request should continue, false otherwise.- Since:
- 4.9.2
-
stealThrottleRequest
@Deprecated void stealThrottleRequest(int address, boolean isLong, ThrottleListener l, boolean steal)Deprecated.since 4.15.7; use #responseThrottleDecisionSteal a requested 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.
- Parameters:
address
- desired decoder addressisLong
- true if requesting a DCC long (extended) addressl
- ThrottleListener requesting the throttle steal occur.steal
- true if the request should continue, false otherwise.- Since:
- 4.9.2
-
responseThrottleDecision
void responseThrottleDecision(int address, ThrottleListener l, ThrottleListener.DecisionType decision)Steal or Share a requested 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.
- Parameters:
address
- desired decoder addressl
- ThrottleListener requesting the throttle steal occur.decision
- from the ThrottleListener, STEAL or SHARE.
-
responseThrottleDecision
void responseThrottleDecision(int address, boolean isLong, ThrottleListener l, ThrottleListener.DecisionType decision)Steal or Share a requested 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.
- Parameters:
address
- desired decoder addressisLong
- true if requesting a DCC long (extended) addressl
- ThrottleListener requesting the throttle steal occur.decision
- from the ThrottleListener, STEAL or SHARE.
-
responseThrottleDecision
void responseThrottleDecision(LocoAddress address, ThrottleListener l, ThrottleListener.DecisionType decision)Steal or Share a requested throttle.- Parameters:
address
- desired LocoAddressl
- The ThrottleListener which has made the decisiondecision
- from the ThrottleListener, STEAL or SHARE.- Since:
- 4.9.2
-
enablePrefSilentStealOption
boolean enablePrefSilentStealOption()Test if the Silent Steal Throttles preference option should be enabled.- Returns:
- true if steal is possible; false otherwise
-
enablePrefSilentShareOption
boolean enablePrefSilentShareOption()Test if the Silent Share Throttles preference option should be enabled.- Returns:
- true if steal is possible; false otherwise
-
hasDispatchFunction
boolean hasDispatchFunction()Test if the Dispatch Button should be enabled or not.- Returns:
- true if dispatch is possible; false otherwise
-
canBeLongAddress
Test if a specific number is a valid long address on this system.- Parameters:
address
- address number to test- Returns:
- true if address can be long; false otherwise
-
canBeShortAddress
Test if a specific number is a valid short address on this system.- Parameters:
address
- address number to test- Returns:
- true if address can be short; false otherwise
-
addressTypeUnique
boolean addressTypeUnique()Test if ambiguous addresses (short vs long) are not allowed on this system. Also indicates support for multi-protocol decoders.- Returns:
- true if ambiguous addresses are not allowed; false otherwise
-
getAddressTypes
This returns a list of the different protocols that are supported by the system, to include short vs long or DCC vs Selectrix vs Motorola.- Returns:
- the list of supported address protocols
-
getAddressTypeString
Get a string value for a given protocol value.- Parameters:
prot
- the protocol- Returns:
- a human-readable, possibly localized, description of the protocol
-
getAddressProtocolTypes
Get a list of different protocols supported by the system, to include short vs long or DCC vs Selectrix vs Motorola.- Returns:
- a list of supported address protocols
-
getProtocolFromString
Get a protocol given a description.- Parameters:
selection
- human-readable, possibly localized, description of the protocol- Returns:
- the protocol
-
getAddress
Get the object representing a particular address.- Parameters:
value
- address in protocol-specific formatprotocol
- specific protocol string, see the specific throttle manager for values- Returns:
- the address, possibly as a protocol-specific subclass
-
getAddress
Get the object representing a particular address.- Parameters:
value
- address in protocol-specific formatprotocol
- the control protocol- Returns:
- the address, possibly as a protocol-specific subclass
-
supportedSpeedModes
Get the supported speed modes.- Returns:
- an XOR of the possible modes specified in the throttle interface
-
getThrottleInfo
Provides a Proxy method to return the SpeedSetting, Direction, Function Settings, of a throttle, where the requesting code has usedattachListener
to only be notified of changes in the throttle and not control it.Valid values for item are IsForward SpeedSetting SpeedIncrement SpeedStepMode F0-F28
- Parameters:
la
- LocoAddress that we wish interrogateitem
- A string of the item we wish to know the value of.- Returns:
- the value as an object, if the loco address has not been assigned to a throttle or the item value is not valid, null is returned.
-
addressStillRequired
- Parameters:
la
- Loco address to test- Returns:
- true, its still required, false its not.
-
addressStillRequired
- Parameters:
address
- Loco number to test.addressIsLong
- true if long address.- Returns:
- true, its still required, false its not.
-
addressStillRequired
- Parameters:
address
- Loco number to test- Returns:
- true, its still required, false its not.
-
addressStillRequired
- Parameters:
re
- roster entry to test- Returns:
- true, its still required, false its not.
-
releaseThrottle
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.
- Parameters:
t
- Throttle being releasedl
- Throttle Listener releasing the throttle
-
disposeThrottle
Not for general use, seereleaseThrottle
anddispatchThrottle
.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.
- Parameters:
t
- Throttle being releasedl
- Throttle Listener releasing the throttle- Returns:
- true if the throttle has been disposed of.
-
dispatchThrottle
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.
- Parameters:
t
- Throttle being releasedl
- Throttle Listener releasing the throttle
-
attachListener
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.
- Parameters:
la
- LocoAddress of the loco we wish to monitorp
- PropertyChangeListener to attach to the throttle
-
removeListener
Remove a PropertyChangeListener to a specific loco address, where the requesting code has usedattachListener
to get notification of changes in a throttle.The PropertyChangeListener will be notified if it has been removed via a PropertyChange notification.
- Parameters:
la
- LocoAddress of the loco we wish to monitorp
- PropertyChangeListener to remove from the throttle
-
getUserName
Get the user name of the system that the programmer is associated with.- Returns:
- the user name for the system
-
getThrottleUsageCount
Get the number of Throttles sharing the throttle for a ddcaddress.- Parameters:
la
- LocoAddress of the loco you want the throttle usage count for.- Returns:
- number of throttles for this address, or 0 if throttle does not exist
-
getThrottleUsageCount
Get the number of Throttles sharing the throttle for a ddcaddress.- Parameters:
address
- number of the loco you want the throttle usage count for.isLongAddress
- indicates whether the address is long or not.- Returns:
- number of throttles for this address, or 0 if throttle does not exist
-
getThrottleUsageCount
Get the number of Throttles sharing the throttle for a ddcaddress.- Parameters:
address
- number of the loco you want the throttle usage count for.- Returns:
- number of throttles for this address, or 0 if throttle does not exist
-
getThrottleUsageCount
Get the number of Throttles sharing the throttle for a ddcaddress.- Parameters:
re
- BasicRosterEntry of the loco you want the throttle usage count for.- Returns:
- number of throttles for this address, or 0 if throttle does not exist
-
dispose
void dispose()Allow to cleanly release the traffic controller in ThrottleManager Tests- remove listeners, if any
- stop timers, is any
-