Package jmri.jmrit.dispatcher

Class DispatcherFrame

  • All Implemented Interfaces:
    java.awt.event.ComponentListener, java.awt.event.WindowListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.accessibility.Accessible, javax.swing.RootPaneContainer, javax.swing.WindowConstants, BeanInterface, InstanceManagerAutoDefault, ModifiedFlag, WindowInterface
    public class DispatcherFrame
extends JmriJFrame
implements InstanceManagerAutoDefault
    Dispatcher functionality, working with Sections, Transits and ActiveTrain.

    Dispatcher serves as the manager for ActiveTrains. All allocation of Sections to ActiveTrains is performed here.

    Programming Note: Use the managed instance returned by InstanceManager.getDefault(java.lang.Class) to access the running Dispatcher.

    Dispatcher listens to fast clock minutes to handle all ActiveTrain items tied to fast clock time.

    Delayed start of manual and automatic trains is enforced by not allocating Sections for trains until the fast clock reaches the departure time.

    This file is part of JMRI.

    JMRI is open source 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.

    See Also:
    Serialized Form

    • Method Detail

      • loadAtStartup

        public void loadAtStartup()
        reads thru all the traininfo files found in the dispatcher directory and loads the ones flagged as "loadAtStartup"

      • dispose

        public void dispose()
        Description copied from class: JmriJFrame
        When window is finally destroyed, remove it from the list of windows.

        Subclasses that over-ride this method must invoke this implementation with super.dispose() right before returning.

        Specified by:
        dispose in interface WindowInterface
        Overrides:
        dispose in class JmriJFrame

      • loadTrainFromTrainInfo

        public int loadTrainFromTrainInfo​(java.lang.String traininfoFileName)
        Loads a train into the Dispatcher from a traininfo file
        Parameters:
        traininfoFileName - the file name of a traininfo file.
        Returns:
        0 good, -1 create failure, -2 -3 file errors, -9 bother.

      • loadTrainFromTrainInfo

        public int loadTrainFromTrainInfo​(java.lang.String traininfoFileName,
                                  java.lang.String overRideType,
                                  java.lang.String overRideValue)
        Loads a train into the Dispatcher from a traininfo file, overriding dccaddress
        Parameters:
        traininfoFileName - the file name of a traininfo file.
        overRideType - "NONE", "USER", "ROSTER" or "OPERATIONS"
        overRideValue - "" , dccAddress, RosterEntryName or Operations trainname.
        Returns:
        0 good, -1 create failure, -2 -3 file errors, -9 bother.

      • loadTrainFromTrainInfo

        public int loadTrainFromTrainInfo​(TrainInfo info)
        Loads a train into the Dispatcher
        Parameters:
        info - a completed TrainInfo class.
        Returns:
        0 good, -1 failure

      • loadTrainFromTrainInfo

        public int loadTrainFromTrainInfo​(TrainInfo info,
                                  java.lang.String overRideType,
                                  java.lang.String overRideValue)
        Loads a train into the Dispatcher returns an integer. Messages written to log.
        Parameters:
        info - a completed TrainInfo class.
        overRideType - "NONE", "USER", "ROSTER" or "OPERATIONS"
        overRideValue - "" , dccAddress, RosterEntryName or Operations trainName.
        Returns:
        0 good, -1 failure

      • loadTrainFromTrainInfoThrowsException

        public void loadTrainFromTrainInfoThrowsException​(TrainInfo info,
                                                  java.lang.String overRideType,
                                                  java.lang.String overRideValue)
                                           throws java.lang.IllegalArgumentException
        Loads a train into the Dispatcher throws IllegalArgumentException on errors
        Parameters:
        info - a completed TrainInfo class.
        overRideType - "NONE", "USER", "ROSTER" or "OPERATIONS"
        overRideValue - "" , dccAddress, RosterEntryName or Operations trainName.
        Throws:
        java.lang.IllegalArgumentException - validation errors.

      • getAdHocRoute

        protected java.util.List<LayoutBlock> getAdHocRoute​(Block start,
                                                    Block dest,
                                                    Block via)
        Get a list of LayoutBlock that represent a route
        Parameters:
        start - First Block
        dest - Last Block
        via - Next Block
        Returns:
        null if a route cannot be found, else the list.

      • createTemporaryTransit

        protected Transit createTemporaryTransit​(Block start,
                                         Block dest,
                                         Block via)
        Converts a list of LayoutBlock that represent a route to a transit.
        Parameters:
        start - First Block
        dest - Last Block
        via - Next Block
        Returns:
        null if the transit is valid. Else an AdHoc transit

      • isTrainFree

        protected boolean isTrainFree​(java.lang.String rName)

      • isAddressFree

        public boolean isAddressFree​(int addr)
        Check DCC not already in use
        Parameters:
        addr - DCC address.
        Returns:
        true / false

      • extendActiveTrainsPath

        public boolean extendActiveTrainsPath​(Section s,
                                      ActiveTrain at,
                                      JmriJFrame jFrame)
        Extend the allocation of a section to a active train. Allows a dispatcher to manually route a train to its final destination.
        Parameters:
        s - the section to allocate
        at - the associated train
        jFrame - the window to update
        Returns:
        true if section was allocated; false otherwise

      • cancelRestart

        void cancelRestart​(java.awt.event.ActionEvent e)

      • terminateTrain

        void terminateTrain​(java.awt.event.ActionEvent e)

      • createActiveTrain

        public ActiveTrain createActiveTrain​(java.lang.String transitID,
                                     java.lang.String trainID,
                                     int tSource,
                                     java.lang.String startBlockName,
                                     int startBlockSectionSequenceNumber,
                                     java.lang.String endBlockName,
                                     int endBlockSectionSequenceNumber,
                                     boolean autoRun,
                                     java.lang.String dccAddress,
                                     int priority,
                                     boolean resetWhenDone,
                                     boolean reverseAtEnd,
                                     boolean showErrorMessages,
                                     JmriJFrame frame,
                                     int allocateMethod)
        Creates a new ActiveTrain, and registers it with Dispatcher.
        Parameters:
        transitID - system or user name of a Transit in the Transit Table
        trainID - any text that identifies the train
        tSource - either ROSTER, OPERATIONS, or USER (see ActiveTrain.java)
        startBlockName - system or user name of Block where train currently resides
        startBlockSectionSequenceNumber - sequence number in the Transit of the Section containing the startBlock (if the startBlock is within the Transit), or of the Section the train will enter from the startBlock (if the startBlock is outside the Transit)
        endBlockName - system or user name of Block where train will end up after its transit
        endBlockSectionSequenceNumber - sequence number in the Transit of the Section containing the endBlock.
        autoRun - set to "true" if computer is to run the train automatically, otherwise "false"
        dccAddress - required if "autoRun" is "true", set to null otherwise
        priority - any integer, higher number is higher priority. Used to arbitrate allocation request conflicts
        resetWhenDone - set to "true" if the Active Train is capable of continuous running and the user has requested that it be automatically reset for another run thru its Transit each time it completes running through its Transit.
        reverseAtEnd - true if train should automatically reverse at end of transit; false otherwise
        showErrorMessages - "true" if error message dialogs are to be displayed for detected errors Set to "false" to suppress error message dialogs from this method.
        frame - window request is from, or "null" if not from a window
        allocateMethod - How allocations will be performed. 999 - Allocate as many section from start to finish as it can 0 - Allocate to the next "Safe" section. If it cannot allocate all the way to the next "safe" section it does not allocate any sections. It will not allocate beyond the next safe section until it arrives there. This is useful for bidirectional single track running. Any other positive number (in reality thats 1-150 as the create transit allows a max of 150 sections) allocate the specified number of sections a head.
        Returns:
        a new ActiveTrain or null on failure

      • terminateActiveTrain

        @Deprecated
public void terminateActiveTrain​(ActiveTrain at)
        Deprecated.
        Terminate an Active Train and remove it from the Dispatcher. The ActiveTrain object should not be used again after this method is called.
        Parameters:
        at - the train to terminate

      • terminateActiveTrain

        public void terminateActiveTrain​(ActiveTrain at,
                                 boolean terminateNow,
                                 boolean runNextTrain)
        Terminate an Active Train and remove it from the Dispatcher. The ActiveTrain object should not be used again after this method is called.
        Parameters:
        at - the train to terminate
        terminateNow - TRue if doing a full terminate, not just an end of transit.
        runNextTrain - if false the next traininfo is not run.

      • requestAllocation

        protected boolean requestAllocation​(ActiveTrain activeTrain,
                                    Section section,
                                    int direction,
                                    int seqNumber,
                                    boolean showErrorMessages,
                                    JmriJFrame frame,
                                    boolean firstAllocation)
        Creates an Allocation Request, and registers it with Dispatcher

        Required input entries:

        Parameters:
        activeTrain - ActiveTrain requesting the allocation
        section - Section to be allocated
        direction - direction of travel in the allocated Section
        seqNumber - sequence number of the Section in the Transit of the ActiveTrain. If the requested Section is not in the Transit, a sequence number of -99 should be entered.
        showErrorMessages - "true" if error message dialogs are to be displayed for detected errors Set to "false" to suppress error message dialogs from this method.
        frame - window request is from, or "null" if not from a window
        firstAllocation - True if first allocation
        Returns:
        true if successful; false otherwise

      • allocateSection

        public AllocatedSection allocateSection​(@Nonnull
                                        AllocationRequest ar,
                                        Section ns)
        Allocates a Section to an Active Train according to the information in an AllocationRequest.

        If successful, returns an AllocatedSection and removes the AllocationRequest from the queue. If not successful, returns null and leaves the AllocationRequest in the queue.

        To be allocatable, a Section must be FREE and UNOCCUPIED. If a Section is OCCUPIED, the allocation is rejected unless the dispatcher chooses to override this restriction. To be allocatable, the Active Train must not be waiting for its start time. If the start time has not been reached, the allocation is rejected, unless the dispatcher chooses to override the start time.

        Parameters:
        ar - the request containing the section to allocate
        ns - the next section; use null to allow the next section to be automatically determined, if the next section is the last section, of if an extra section is being allocated
        Returns:
        the allocated section or null if not successful

      • hasTrainAnOccupiedSection

        protected boolean hasTrainAnOccupiedSection​(ActiveTrain at)
        Check an active train has an occupied section
        Parameters:
        at - ActiveTRain object
        Returns:
        true / false

      • checkForBlockInAllocatedSection

        protected boolean checkForBlockInAllocatedSection​(Block b,
                                                  Section ignoreSection)
        Checks for a block in allocated section, except one
        Parameters:
        b - - The Block
        ignoreSection - - ignore this section, can be null
        Returns:
        true is The Block is being used in a section.

      • checkAutoRelease

        protected void checkAutoRelease()
        Check if any allocation requests need to be allocated, or if any allocated sections need to be released

      • releaseAllocatedSection

        public void releaseAllocatedSection​(AllocatedSection as,
                                    boolean terminatingTrain)
        Releases an allocated Section, and removes it from the Dispatcher Input.
        Parameters:
        as - the section to release
        terminatingTrain - true if the associated train is being terminated; false otherwise

      • sectionOccupancyChanged

        public void sectionOccupancyChanged()
        Updates display when occupancy of an allocated section changes Also drives auto release if it is selected

      • newFastClockMinute

        protected void newFastClockMinute()
        Handle activity that is triggered by the fast clock

      • isFastClockTimeGE

        public boolean isFastClockTimeGE​(int hr,
                                 int min)
        This method tests time
        Parameters:
        hr - the hour to test against (0-23)
        min - the minute to test against (0-59)
        Returns:
        true if fast clock time and tested time are the same

      • showTableHeaderPopup

        protected void showTableHeaderPopup​(JmriMouseEvent e,
                                    javax.swing.JTable table)
        Process the column header click
        Parameters:
        e - the evnt data
        table - the JTable

      • addMouseListenerToHeader

        protected void addMouseListenerToHeader​(javax.swing.JTable table)
        Adds the column header pop listener to a JTable using XTableColumnModel
        Parameters:
        table - The JTable effected.