Package jmri.jmrix

Class AbstractThrottleManager

java.lang.Object
jmri.jmrix.AbstractThrottleManager
All Implemented Interfaces:
ThrottleManager
Direct Known Subclasses:
BiDiBThrottleManager, CbusThrottleManager, DCCppThrottleManager, DebugThrottleManager, EasyDccThrottleManager, EcosDccThrottleManager, LnPr2ThrottleManager, LnThrottleManager, MarklinThrottleManager, MqttThrottleManager, MrcThrottleManager, Mx1ThrottleManager, 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.

  • Field Details

  • Constructor Details

  • Method Details

    • getUserName

      public String getUserName()
      Get the user name of the system that the programmer is associated with.
      Specified by:
      getUserName in interface ThrottleManager
      Returns:
      the user name for the system

    • getAddressTypes

      public String[] getAddressTypes()
      By default, only DCC in this implementation
      Specified by:
      getAddressTypes in interface ThrottleManager
      Returns:
      the list of supported address protocols

    • getAddressTypeString

      public String getAddressTypeString(LocoAddress.Protocol prot)
      By default, only DCC in this implementation
      Specified by:
      getAddressTypeString in interface ThrottleManager
      Parameters:
      prot - the protocol
      Returns:
      a human-readable, possibly localized, description of the protocol

    • getAddressProtocolTypes

      public LocoAddress.Protocol[] getAddressProtocolTypes()
      Get a list of different protocols supported by the system, to include short vs long or DCC vs Selectrix vs Motorola.
      Specified by:
      getAddressProtocolTypes in interface ThrottleManager
      Returns:
      a list of supported address protocols

    • getAddress

      public LocoAddress getAddress(String value, LocoAddress.Protocol protocol)
      Get the object representing a particular address.
      Specified by:
      getAddress in interface ThrottleManager
      Parameters:
      value - address in protocol-specific format
      protocol - the control protocol
      Returns:
      the address, possibly as a protocol-specific subclass

    • getAddress

      public LocoAddress getAddress(String value, String protocol)
      Get the object representing a particular address.
      Specified by:
      getAddress in interface ThrottleManager
      Parameters:
      value - address in protocol-specific format
      protocol - specific protocol string, see the specific throttle manager for values
      Returns:
      the address, possibly as a protocol-specific subclass

    • getProtocolFromString

      public LocoAddress.Protocol getProtocolFromString(String selection)
      Get a protocol given a description.
      Specified by:
      getProtocolFromString in interface ThrottleManager
      Parameters:
      selection - human-readable, possibly localized, description of the protocol
      Returns:
      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?
      Returns:
      true or false

    • requestThrottle

      public boolean requestThrottle(int address, boolean isLongAddress, 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.
      Specified by:
      requestThrottle in interface ThrottleManager
      Parameters:
      address - desired decoder address
      isLongAddress - true if requesting a DCC long (extended) address
      l - ThrottleListener awaiting notification of a found throttle
      canHandleDecisions - 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

      public boolean requestThrottle(@Nonnull 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.
      Specified by:
      requestThrottle in interface ThrottleManager
      Parameters:
      re - desired RosterEntry
      l - ThrottleListener awaiting notification of a found throttle
      canHandleDecisions - 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

      public boolean requestThrottle(LocoAddress la, 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.
      Specified by:
      requestThrottle in interface ThrottleManager
      Parameters:
      la - desired loco address
      l - ThrottleListener awaiting notification of a found throttle
      canHandleDecisions - 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

      protected boolean requestThrottle(LocoAddress la, BasicRosterEntry re, 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.

      Parameters:
      la - LocoAddress of the decoder desired.
      l - The ThrottleListener awaiting notification of a found throttle.
      re - A BasicRosterEntry can be passed, this is attached to a throttle after creation.
      canHandleDecisions - true if theThrottleListener can make a steal or share decision, 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

      public boolean requestThrottle(int address, ThrottleListener l)
      Request Throttle with no Steal / Share Callbacks 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. 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.

    • requestThrottle

      public 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.

      Specified by:
      requestThrottle in interface ThrottleManager
      Parameters:
      address - desired decoder address
      l - ThrottleListener awaiting notification of a found throttle
      canHandleDecisions - 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

    • 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.
      Parameters:
      a - address
      control - false - read only.

    • 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
      Parameters:
      a - address.

    • cancelThrottleRequest

      public void cancelThrottleRequest(int address, boolean isLong, ThrottleListener l)
      Cancel a request for a throttle.
      Specified by:
      cancelThrottleRequest in interface ThrottleManager
      Parameters:
      address - desired decoder address
      isLong - true if requesting a DCC long (extended) address
      l - ThrottleListener canceling request for a throttle

    • cancelThrottleRequest

      public 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.

      Specified by:
      cancelThrottleRequest in interface ThrottleManager
      Parameters:
      re - desired Roster Entry
      l - ThrottleListener canceling the request for a throttle

    • cancelThrottleRequest

      public void cancelThrottleRequest(LocoAddress la, ThrottleListener l)
      Cancel a request for a throttle.
      Specified by:
      cancelThrottleRequest in interface ThrottleManager
      Parameters:
      la - unwanted Loco address
      l - ThrottleListener canceling 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. 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.

    • responseThrottleDecision

      public 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.

      Specified by:
      responseThrottleDecision in interface ThrottleManager
      Parameters:
      address - desired decoder address
      l - ThrottleListener requesting the throttle steal occur.
      decision - from the ThrottleListener, STEAL or SHARE.

    • responseThrottleDecision

      public 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.

      Specified by:
      responseThrottleDecision in interface ThrottleManager
      Parameters:
      address - desired decoder address
      isLong - true if requesting a DCC long (extended) address
      l - ThrottleListener requesting the throttle steal occur.
      decision - from the ThrottleListener, STEAL or SHARE.

    • responseThrottleDecision

      public void responseThrottleDecision(LocoAddress address, ThrottleListener l, ThrottleListener.DecisionType decision)
      Steal or Share a requested throttle.
      Specified by:
      responseThrottleDecision in interface ThrottleManager
      Parameters:
      address - desired LocoAddress
      l - The ThrottleListener which has made the decision
      decision - from the ThrottleListener, STEAL or SHARE.

    • failedThrottleRequest

      public void failedThrottleRequest(LocoAddress 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 Loco Address that the request failed on.
      reason - A text string passed by the ThrottleManager 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.

      Parameters:
      throttle - throttle object
      addr - address.

    • makeHardwareDecision

      protected void makeHardwareDecision(LocoAddress address, ThrottleListener.DecisionType question)
      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.

      Parameters:
      address - The LocoAddress the steal / share question relates to
      question - The Question to be put to the ThrottleListener

    • notifyDecisionRequest

      protected void notifyDecisionRequest(LocoAddress address, ThrottleListener.DecisionType question)
      When the system-specific ThrottleManager has been unable to create the DCC throttle because it is already in use and must be "stolen" or "shared" to take control, it needs to notify the listener of this situation.

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

      Parameters:
      address - The LocoAddress the steal / share question relates to
      question - The Question to be put to the ThrottleListener

    • 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
      Returns:
      true if dispatch is possible; false otherwise

    • supportedSpeedModes

      public EnumSet<SpeedStepMode> 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
      Returns:
      an XOR of the possible modes specified in the throttle interface

    • enablePrefSilentStealOption

      public boolean enablePrefSilentStealOption()
      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
      Returns:
      true if steal is possible; false otherwise

    • enablePrefSilentShareOption

      public boolean enablePrefSilentShareOption()
      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
      Returns:
      true if steal is possible; false otherwise

    • attachListener

      public 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. 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 - LocoAddress of the loco we wish to monitor
      p - PropertyChangeListener to attach to the throttle

    • removeListener

      public void removeListener(LocoAddress 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.

      The PropertyChangeListener will be notified if it has been removed via a PropertyChange notification.

      Specified by:
      removeListener in interface ThrottleManager
      Parameters:
      la - LocoAddress of the loco we wish to monitor
      p - PropertyChangeListener to remove from the throttle

    • addressStillRequired

      public boolean addressStillRequired(LocoAddress la)
      Specified by:
      addressStillRequired in interface ThrottleManager
      Parameters:
      la - Loco address to test
      Returns:
      true, its still required, false its not.

    • addressStillRequired

      public boolean addressStillRequired(int address, boolean isLongAddress)
      Specified by:
      addressStillRequired in interface ThrottleManager
      Parameters:
      address - Loco number to test.
      isLongAddress - true if long address.
      Returns:
      true, its still required, false its not.

    • addressStillRequired

      public boolean addressStillRequired(int address)
      Specified by:
      addressStillRequired in interface ThrottleManager
      Parameters:
      address - Loco number to test
      Returns:
      true, its still required, false its not.

    • addressStillRequired

      public boolean addressStillRequired(BasicRosterEntry re)
      Specified by:
      addressStillRequired in interface ThrottleManager
      Parameters:
      re - roster entry to test
      Returns:
      true, its still required, false its not.

    • releaseThrottle

      public 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.

      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)
      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.

    • 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

      Parameters:
      la - address release

    • dispatchThrottle

      public 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.

      Specified by:
      dispatchThrottle in interface ThrottleManager
      Parameters:
      t - Throttle being released
      l - Throttle Listener releasing the throttle

    • 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 ThrottleManager

    • getThrottleUsageCount

      public int getThrottleUsageCount(LocoAddress la)
      Get the number of Throttles sharing the throttle for a ddcaddress.
      Specified by:
      getThrottleUsageCount in interface ThrottleManager
      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

      public int getThrottleUsageCount(int address, boolean isLongAddress)
      Get the number of Throttles sharing the throttle for a ddcaddress.
      Specified by:
      getThrottleUsageCount in interface ThrottleManager
      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

      public int getThrottleUsageCount(int address)
      Get the number of Throttles sharing the throttle for a ddcaddress.
      Specified by:
      getThrottleUsageCount in interface ThrottleManager
      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

      public int getThrottleUsageCount(BasicRosterEntry re)
      Get the number of Throttles sharing the throttle for a ddcaddress.
      Specified by:
      getThrottleUsageCount in interface ThrottleManager
      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

    • addressReleased

      protected boolean addressReleased(LocoAddress la, ThrottleListener l)
      Release a Throttle from a ThrottleListener.
      Parameters:
      la - address release
      l - listening object
      Returns:
      True if throttle still has listeners or a positive use count, else False

    • 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

      Parameters:
      la - the Loco Address which has been updated
      numUsers - current number of users

    • getThrottleInfo

      public 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 used 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 - LocoAddress that we wish interrogate
      item - 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.

    • showSessionCancelDialogue

      protected void showSessionCancelDialogue(LocoAddress address)
      If not headless, display a session stolen dialogue box with checkbox to hide notifications for rest of JMRI session
      Parameters:
      address - the LocoAddress of the stolen / cancelled Throttle

    • hideStealNotifications

      public void hideStealNotifications(boolean hide)
      Receive notification from a throttle dialogue to display steal dialogues for rest of the JMRI instance session. False by default to show notifications
      Parameters:
      hide - set True to hide notifications, else False.