Package jmri

Interface ThrottleManager

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

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

      • 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 format
        protocol - 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 format
        protocol - 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 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.

      • 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,
                    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 monitor
        p - 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 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

        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