Interface ThrottleManager
-
- All Known Implementing Classes:
AbstractThrottleManager
,BiDiBThrottleManager
,CbusThrottleManager
,DCCppThrottleManager
,DebugThrottleManager
,EasyDccThrottleManager
,EcosDccThrottleManager
,EliteXNetThrottleManager
,Ib1ThrottleManager
,Ib2ThrottleManager
,LnPr2ThrottleManager
,LnThrottleManager
,MarklinThrottleManager
,MqttThrottleManager
,MrcThrottleManager
,Mx1ThrottleManager
,NceThrottleManager
,OlcbThrottleManager
,RocoXNetThrottleManager
,SerialThrottleManager
,SprogCSThrottleManager
,SprogThrottleManager
,SRCPThrottleManager
,TamsThrottleManager
,ThrottleManager
,UhlenbrockLnThrottleManager
,XNetThrottleManager
,XpaThrottleManager
,Z21XNetThrottleManager
public interface ThrottleManager
Interface for allocatingThrottle
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
All Methods Instance Methods Abstract Methods 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, java.beans.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(java.lang.String value, java.lang.String protocol)
Get the object representing a particular address.LocoAddress
getAddress(java.lang.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.java.lang.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.java.lang.String
getAddressTypeString(LocoAddress.Protocol prot)
Get a string value for a given protocol value.LocoAddress.Protocol
getProtocolFromString(java.lang.String selection)
Get a protocol given a description.java.lang.Object
getThrottleInfo(LocoAddress la, java.lang.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.java.lang.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, java.beans.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, 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, boolean canHandleDecisions)
Request a throttle from a given RosterEntry.boolean
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.java.util.EnumSet<SpeedStepMode>
supportedSpeedModes()
Get the supported speed modes.
-
-
-
Method Detail
-
requestThrottle
boolean requestThrottle(BasicRosterEntry re, ThrottleListener l, boolean canHandleDecisions)
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
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, 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
boolean requestThrottle(int address, ThrottleListener l, boolean canHandleDecisions)
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
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
boolean requestThrottle(LocoAddress address, ThrottleListener l, boolean canHandleDecisions)
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
void cancelThrottleRequest(BasicRosterEntry re, 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.
- Parameters:
re
- desired Roster Entryl
- ThrottleListener canceling the request for a throttle
-
cancelThrottleRequest
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.
- Parameters:
address
- desired decoder addressl
- ThrottleListener canceling request for a throttle
-
cancelThrottleRequest
void cancelThrottleRequest(int address, boolean isLong, ThrottleListener l)
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
void cancelThrottleRequest(LocoAddress address, ThrottleListener l)
Cancel a request for a throttle.- Parameters:
address
- unwanted Loco addressl
- ThrottleListener canceling request for a throttle
-
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
boolean canBeLongAddress(int address)
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
boolean canBeShortAddress(int address)
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
java.lang.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.- Returns:
- the list of supported address protocols
-
getAddressTypeString
java.lang.String getAddressTypeString(LocoAddress.Protocol prot)
Get a string value for a given protocol value.- Parameters:
prot
- the protocol- Returns:
- a human-readable, possibly localized, description of the protocol
-
getAddressProtocolTypes
LocoAddress.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
LocoAddress.Protocol getProtocolFromString(java.lang.String selection)
Get a protocol given a description.- Parameters:
selection
- human-readable, possibly localized, description of the protocol- Returns:
- the protocol
-
getAddress
LocoAddress getAddress(java.lang.String value, java.lang.String protocol)
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
LocoAddress getAddress(java.lang.String value, LocoAddress.Protocol protocol)
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
java.util.EnumSet<SpeedStepMode> supportedSpeedModes()
Get the supported speed modes.- Returns:
- an XOR of the possible modes specified in the throttle interface
-
getThrottleInfo
java.lang.Object getThrottleInfo(LocoAddress la, java.lang.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.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
boolean addressStillRequired(LocoAddress la)
- Parameters:
la
- Loco address to test- Returns:
- true, its still required, false its not.
-
addressStillRequired
boolean addressStillRequired(int address, boolean addressIsLong)
- Parameters:
address
- Loco number to test.addressIsLong
- true if long address.- Returns:
- true, its still required, false its not.
-
addressStillRequired
boolean addressStillRequired(int address)
- Parameters:
address
- Loco number to test- Returns:
- true, its still required, false its not.
-
addressStillRequired
boolean addressStillRequired(BasicRosterEntry re)
- Parameters:
re
- roster entry to test- Returns:
- true, its still required, false its not.
-
releaseThrottle
void releaseThrottle(DccThrottle t, ThrottleListener l)
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
boolean disposeThrottle(DccThrottle t, ThrottleListener l)
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
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. 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
void attachListener(LocoAddress la, java.beans.PropertyChangeListener p)
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
void removeListener(LocoAddress la, java.beans.PropertyChangeListener p)
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
java.lang.String getUserName()
Get the user name of the system that the programmer is associated with.- Returns:
- the user name for the system
-
getThrottleUsageCount
int getThrottleUsageCount(LocoAddress la)
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
int getThrottleUsageCount(int address, boolean isLongAddress)
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
int getThrottleUsageCount(int address)
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
int getThrottleUsageCount(BasicRosterEntry re)
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
-
-