Package jmri

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
Interface for allocating 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 Details

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

      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 address
      l - 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 false
      address - desired decoder address
      l - 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 address
      isLong - 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

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

    • 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 Entry
      l - 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 address
      l - 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 address
      isLong - true if requesting a DCC long (extended) address
      l - ThrottleListener canceling request for a throttle

    • cancelThrottleRequest

      void cancelThrottleRequest​(LocoAddress address, ThrottleListener l)
      Cancel a request for a throttle.
      Parameters:
      address - unwanted Loco address
      l - 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 address
      l - 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 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

      void responseThrottleDecision​(LocoAddress address, ThrottleListener l, ThrottleListener.DecisionType decision)
      Steal or Share a requested throttle.
      Parameters:
      address - desired LocoAddress
      l - The ThrottleListener which has made the decision
      decision - 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

      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

      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​(String selection)
      Get a protocol given a description.
      Parameters:
      selection - human-readable, possibly localized, description of the protocol
      Returns:
      the protocol

    • getAddress

      LocoAddress getAddress​(String value, String protocol)
      Get the object representing a particular address.
      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

    • getAddress

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

    • supportedSpeedModes

      EnumSet<SpeedStepMode> supportedSpeedModes()
      Get the supported speed modes.
      Returns:
      an XOR of the possible modes specified in the throttle interface

    • getThrottleInfo

      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

      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.

    • 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 released
      l - Throttle Listener releasing the throttle

    • disposeThrottle

      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.

      Parameters:
      t - Throttle being released
      l - 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 released
      l - Throttle Listener releasing the throttle

    • attachListener

      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.

      Parameters:
      la - LocoAddress of the loco we wish to monitor
      p - PropertyChangeListener to attach to the throttle

    • removeListener

      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.

      Parameters:
      la - LocoAddress of the loco we wish to monitor
      p - PropertyChangeListener to remove from the throttle

    • getUserName

      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