Package jmri.jmrix

Class AbstractThrottleManager

    • Method Detail

      • getUserName

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

      • getAddress

        public LocoAddress getAddress​(java.lang.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​(java.lang.String value,
                              java.lang.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

      • 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​(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,
                                     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.

      • failedThrottleRequest

        public void failedThrottleRequest​(LocoAddress address,
                                  java.lang.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 java.util.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

      • attachListener

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

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

        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​(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.

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

        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.