Package jmri.jmrit.logix

Class Warrant

  • All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.lang.Comparable<NamedBean>, java.util.EventListener, PropertyChangeProvider, NamedBean, ThrottleListener
    Direct Known Subclasses:
    SCWarrant
    public class Warrant
extends AbstractNamedBean
implements ThrottleListener, java.beans.PropertyChangeListener
    A Warrant contains the operating permissions and directives needed for a train to proceed from an Origin to a Destination. There are three modes that a Warrant may execute;

    MODE_LEARN - Warrant is created or edited in WarrantFrame and then launched from WarrantFrame who records throttle commands from "_student" throttle. Warrant fires PropertyChanges for WarrantFrame to record when blocks are entered. "_engineer" thread is null.

    MODE_RUN - Warrant may be launched from several places. An array of BlockOrders, _savedOrders, and corresponding _throttleCommands allow an "_engineer" thread to execute the throttle commands. The blockOrders establish the route for the Warrant to acquire and reserve OBlocks. The Warrant monitors block activity (entrances and exits, signals, rogue occupancy etc) and modifies speed as needed.

    MODE_MANUAL - Warrant may be launched from several places. The Warrant to acquires and reserves the route from the array of BlockOrders. Throttle commands are done by a human operator. "_engineer" and "_throttleCommands" are not used. Warrant monitors block activity but does not set _stoppingBlock or _protectSignal since it cannot control speed. It does attempt to realign the route as needed, but can be thwarted.

    Version 1.11 - remove setting of SignalHeads

    • Constructor Detail

      • Warrant

        public Warrant​(java.lang.String sName,
               java.lang.String uName)
        Create an object with no route defined. The list of BlockOrders is the route from an Origin to a Destination
        Parameters:
        sName - system name
        uName - user name

    • Method Detail

      • setNXWarrant

        protected void setNXWarrant​(boolean set)

      • getState

        public int getState()
        Description copied from interface: NamedBean
        Provide generic access to internal state.

        This generally shouldn't be used by Java code; use the class-specific form instead (e.g. getCommandedState in Turnout). This is provided to make scripts easier to read.

        Specified by:
        getState in interface NamedBean
        Returns:
        the state

      • setState

        public void setState​(int state)
        Description copied from interface: NamedBean
        Provide generic access to internal state.

        This generally shouldn't be used by Java code; use the class-specific form instead (e.g. setCommandedState in Turnout). This is provided to make scripts access easier to read.

        Specified by:
        setState in interface NamedBean
        Parameters:
        state - the state

      • addBlockOrder

        public void addBlockOrder​(BlockOrder order)
        Add permanently saved BlockOrder.
        Parameters:
        order - block order

      • getLastOrder

        public BlockOrder getLastOrder()
        Return permanently saved Destination.
        Returns:
        destination block order

      • getViaOrder

        public BlockOrder getViaOrder()
        Return permanently saved BlockOrder that must be included in the route.
        Returns:
        via block order

      • getCurrentOrderIndex

        public final int getCurrentOrderIndex()
        Returns:
        index of block order currently at the train position

      • getIndexOfBlockAfter

        protected int getIndexOfBlockAfter​(OBlock block,
                                   int idx)
        Find index of a block AFTER BlockOrder index.
        Parameters:
        block - used by the warrant
        idx - start index of search
        Returns:
        index of block after of block order index, -1 if not found

      • getIndexOfBlockBefore

        protected int getIndexOfBlockBefore​(int idx,
                                    OBlock block)
        Find index of block BEFORE BlockOrder index.
        Parameters:
        idx - start index of search
        block - used by the warrant
        Returns:
        index of block before of block order index, -1 if not found

      • getBlockOrderAt

        protected BlockOrder getBlockOrderAt​(int index)
        Call is only valid when in MODE_LEARN and MODE_RUN.
        Parameters:
        index - index of block order
        Returns:
        block order or null if not found

      • getBlockAt

        protected OBlock getBlockAt​(int idx)
        Call is only valid when in MODE_LEARN and MODE_RUN.
        Parameters:
        idx - index of block order
        Returns:
        block of the block order

      • getCurrentBlockName

        public java.lang.String getCurrentBlockName()
        Call is only valid when in MODE_LEARN and MODE_RUN.
        Returns:
        Name of OBlock currently occupied

      • setNoRamp

        public void setNoRamp​(boolean set)

      • setTrainName

        public void setTrainName​(java.lang.String name)

      • setRunBlind

        public void setRunBlind​(boolean runBlind)

      • fireRunStatus

        protected void fireRunStatus​(java.lang.String property,
                             java.lang.Object old,
                             java.lang.Object status)

      • isAllocated

        public boolean isAllocated()
        Returns:
        true if listeners are installed enough to run

      • isTotalAllocated

        public boolean isTotalAllocated()
        Returns:
        true if listeners are installed for entire route

      • hasRouteSet

        public boolean hasRouteSet()
        Turnouts are set for the route
        Returns:
        true if turnouts are set

      • routeIsFree

        public boolean routeIsFree()
        Test if the permanent saved blocks of this warrant are free (unoccupied and unallocated)
        Returns:
        true if route is free

      • routeIsOccupied

        public boolean routeIsOccupied()
        Test if the permanent saved blocks of this warrant are occupied
        Returns:
        true if any block is occupied

      • getMessage

        public java.lang.String getMessage()

      • getRunMode

        public int getRunMode()
        Returns:
        ID of run mode

      • stopWarrant

        public void stopWarrant​(boolean abort,
                        boolean turnOffFunctions)

      • setRunMode

        public java.lang.String setRunMode​(int mode,
                                   DccLocoAddress address,
                                   LearnThrottleFrame student,
                                   java.util.List<ThrottleSetting> commands,
                                   boolean runBlind)
        Sets up recording and playing back throttle commands - also cleans up afterwards. MODE_LEARN and MODE_RUN sessions must end by calling again with MODE_NONE. It is important that the route be deAllocated (remove listeners).

        Rule for (auto) MODE_RUN: 1. At least the Origin block must be owned (allocated) by this warrant. (block._warrant == this) and path set for Run Mode Rule for (auto) LEARN_RUN: 2. Entire Route must be allocated and Route Set for Learn Mode. i.e. this warrant has listeners on all block sensors in the route. Rule for MODE_MANUAL The Origin block must be allocated to this warrant and path set for the route

        Parameters:
        mode - run mode
        address - DCC loco address
        student - throttle frame for learn mode parameters
        commands - list of throttle commands
        runBlind - true if occupancy should be ignored
        Returns:
        error message, if any

      • notifyDecisionRequired

        public void notifyDecisionRequired​(LocoAddress address,
                                   ThrottleListener.DecisionType question)
        No steal or share decisions made locally

        Get notification that a throttle request is in use by another device, and a "steal", "share", or "steal/share" decision may be required.

        Specified by:
        notifyDecisionRequired in interface ThrottleListener
        Parameters:
        address - The LocoAddress that needs the decision.
        question - The question being asked, steal / cancel, share / cancel, steal / share / cancel

      • abortWarrant

        protected void abortWarrant​(java.lang.String msg)

      • controlRunTrain

        public boolean controlRunTrain​(int idx)
        Pause and resume auto-running train or abort any allocation state User issued overriding commands during run time of warrant _engineer.abort() calls setRunMode(MODE_NONE,...) which calls deallocate all.
        Parameters:
        idx - index of control command
        Returns:
        false if command cannot be given

      • allocateRoute

        public java.lang.String allocateRoute​(boolean show,
                                      java.util.List<BlockOrder> orders)
        Allocate as many blocks as possible from the start of the warrant. The first block must be allocated and all blocks of the route must be in service. Otherwise partial success is OK. Installs listeners for the entire route. If occupation by another train is detected, a message will be posted to the Warrant List Window. Note that warrants sharing their clearance only allocate and set paths one block in advance.
        Parameters:
        orders - list of block orders
        show - _message for use ONLY to display a temporary route) continues to allocate skipping over blocks occupied or owned by another warrant.
        Returns:
        error message, if unable to allocate first block or if any block is OUT_OF_SERVICE

      • deAllocate

        public void deAllocate()
        Deallocates blocks from the current BlockOrder list

      • runWarrant

        public void runWarrant​(int mode)
        Convenience routine to use from Python to start a warrant.
        Parameters:
        mode - run mode

      • setRoute

        public java.lang.String setRoute​(boolean show,
                                 java.util.List<BlockOrder> orders)
        Set the route paths and turnouts for the warrant. Only the first block must be allocated and have its path set. Partial success is OK. A message of the first subsequent block that fails allocation or path setting is written to a field that is displayed in the Warrant List window. When running with block detection, occupation by another train or block 'not in use' or Signals denying movement are reasons for such a message, otherwise only allocation to another warrant prevents total success. Note that warrants sharing their clearance only allocate and set paths one block in advance.
        Parameters:
        show - If true allocateRoute returns messages for display.
        orders - BlockOrder list of route. If null, use permanent warrant copy.
        Returns:
        message if the first block fails allocation, otherwise null

      • checkStartBlock

        public java.lang.String checkStartBlock()
        Check start block for occupied for start of run
        Returns:
        error message, if any

      • checkRoute

        public java.lang.String checkRoute()
        Report any occupied blocks in the route
        Returns:
        String

      • propertyChange

        public void propertyChange​(java.beans.PropertyChangeEvent evt)
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener

      • goingActive

        @InvokeOnLayoutThread
protected void goingActive​(OBlock block)
        Check if this is the next block of the train moving under the warrant Learn mode assumes route is set and clear. Run mode update conditions.

        Must be called on Layout thread.

        Parameters:
        block - Block in the route is going active.

      • dispose

        public void dispose()
        Description copied from class: AbstractNamedBean
        Deactivate this object, so that it releases as many resources as possible and no longer effects others.

        For example, if this object has listeners, after a call to this method it should no longer notify those listeners. Any native or system-wide resources it maintains should be released, including threads, files, etc.

        It is an error to invoke any other methods on this object once dispose() has been called. Note, however, that there is no guarantee about behavior in that case.

        Afterwards, references to this object may still exist elsewhere, preventing its garbage collection. But it's formally dead, and shouldn't be keeping any other objects alive. Therefore, this method should null out any references to other objects that this NamedBean contained.

        Specified by:
        dispose in interface NamedBean
        Overrides:
        dispose in class AbstractNamedBean

      • getBeanType

        public java.lang.String getBeanType()
        Description copied from interface: NamedBean
        For instances in the code where we are dealing with just a bean and a message needs to be passed to the user or in a log.
        Specified by:
        getBeanType in interface NamedBean
        Returns:
        a string of the bean type, eg Turnout, Sensor etc

      • downRampBegun

        protected void downRampBegun​(int endBlockIdx)

      • downRampDone

        protected void downRampDone​(boolean stop,
                            boolean halted,
                            java.lang.String speedType,
                            int endBlockIdx)

      • equals

        public boolean equals​(java.lang.Object obj)

        This implementation tests that NamedBean.getSystemName() is equal for this and obj.

        This implementation tests that NamedBean.getSystemName() is equal for this and obj. To allow a warrant to run with sections, DccLocoAddress is included to test equality

        Overrides:
        equals in class AbstractNamedBean
        Parameters:
        obj - the reference object with which to compare.
        Returns:
        true if this object is the same as the obj argument; false otherwise.