Package jmri.jmrit.display.layoutEditor

Class ConnectivityUtil

  • public final class ConnectivityUtil
extends java.lang.Object
    ConnectivityUtil provides methods supporting use of layout connectivity available in Layout Editor panels. These tools allow outside classes to inquire into connectivity information contained in a specified Layout Editor panel.

    Connectivity information is stored in the track diagram of a Layout Editor panel. The "connectivity graph" of the layout consists of nodes (LayoutTurnouts, LevelXings, and PositionablePoints) connected by lines (TrackSegments). These methods extract information from the connection graph and make it available. Each instance of ConnectivityUtil is associated with a specific Layout Editor panel, and is accessed via that LayoutEditor panel's 'getConnectivityUtil' method.

    The methods in this module do not modify the Layout in any way, or change the state of items on the layout. They only provide information to allow other modules to do so as appropriate. For example, the "getTurnoutList" method provides information about the turnouts in a block, but does not test the state, or change the state, of any turnout.

    The methods in this module are accessed via direct calls from the inquiring method.

    A single object of this type, obtained via LayoutEditor.getConnectivityUtil() is shared across all instances of LayoutBlock.

    • Method Detail

      • getTurnoutList

        @Nonnull
public java.util.List<LayoutTrackExpectedState<LayoutTurnout>> getTurnoutList​(@CheckForNull
                                                                              Block currBlock,
                                                                              @CheckForNull
                                                                              Block prevBlock,
                                                                              @CheckForNull
                                                                              Block nextBlock)
        Provide a list of LayoutTurnouts in the specified Block, in order, beginning at the connection to the specified previous Block and continuing to the specified next Block. Also compiles a companion list of how the turnout should be set for the specified connectivity. The companion list can be accessed by "getTurnoutSettingList" immediately after this method returns.
        Parameters:
        currBlock - the block to list LayoutTurnouts in
        prevBlock - the previous block
        nextBlock - the following block
        Returns:
        the list of all turnouts in the block if prevBlock or nextBlock are null or the list of all turnouts required to transit currBlock between prevBlock and nextBlock; returns an empty list if prevBlock and nextBlock are not null and are not connected

      • getTurnoutList

        @Nonnull
public java.util.List<LayoutTrackExpectedState<LayoutTurnout>> getTurnoutList​(@CheckForNull
                                                                              Block currBlock,
                                                                              @CheckForNull
                                                                              Block prevBlock,
                                                                              @CheckForNull
                                                                              Block nextBlock,
                                                                              boolean suppress)
        Provide a list of LayoutTurnouts in the specified Block, in order, beginning at the connection to the specified previous Block and continuing to the specified next Block. Also compiles a companion list of how the turnout should be set for the specified connectivity. The companion list can be accessed by "getTurnoutSettingList" immediately after this method returns.
        Parameters:
        currBlock - the block to list LayoutTurnouts in
        prevBlock - the previous block
        nextBlock - the following block
        suppress - true to prevent errors from being logged; false otherwise
        Returns:
        the list of all turnouts in the block if prevBlock or nextBlock are null or the list of all turnouts required to transit currBlock between prevBlock and nextBlock; returns an empty list if prevBlock and nextBlock are not null and are not connected

      • getConnectedBlocks

        @Nonnull
public java.util.List<Block> getConnectedBlocks​(@Nonnull
                                                Block block)
        Get a list of all Blocks connected to a specified Block.
        Parameters:
        block - the block to get connections for
        Returns:
        connected blocks or an empty list if none

      • getLevelCrossingsThisBlock

        @Nonnull
public java.util.List<LevelXing> getLevelCrossingsThisBlock​(@Nonnull
                                                            Block block)
        Get a list of all LevelXings involving the specified Block. To be listed, a LevelXing must have all its four connections and all blocks must be assigned. If any connection is missing, or if a block assignment is missing, an error message is printed and the level crossing is not added to the list.
        Parameters:
        block - the block to check
        Returns:
        a list of all complete LevelXings

      • getLayoutTurnoutsThisBlock

        @Nonnull
public java.util.List<LayoutTurnout> getLayoutTurnoutsThisBlock​(@Nonnull
                                                                Block block)
        Get a list of all layout turnouts involving the specified Block.
        Parameters:
        block - the Block to get layout turnouts for
        Returns:
        the list of associated layout turnouts or an empty list if none

      • layoutTurnoutHasRequiredSignals

        public boolean layoutTurnoutHasRequiredSignals​(@Nonnull
                                               LayoutTurnout t)
        Check if specified LayoutTurnout has required signals.
        Parameters:
        t - the LayoutTurnout to check
        Returns:
        true if specified LayoutTurnout has required signal heads; false otherwise

      • blockInternalToLevelXing

        public boolean blockInternalToLevelXing​(@CheckForNull
                                        LevelXing x,
                                        @CheckForNull
                                        Block block)
        Check if block is internal to a level crossing.
        Parameters:
        x - the level crossing to check
        block - the block to check
        Returns:
        true if block is internal to x; false if block is external or contains a connecting track segment

      • getDirectionFromAnchor

        public int getDirectionFromAnchor​(@Nonnull
                                  java.util.List<EntryPoint> mForwardEntryPoints,
                                  @Nonnull
                                  java.util.List<EntryPoint> mReverseEntryPoints,
                                  @Nonnull
                                  PositionablePoint p)
        Get the direction of the block boundary anchor point p. If EntryPoint.UNKNOWN is returned, it indicates that p is entirely internal or external to the Section.
        Parameters:
        mForwardEntryPoints - list of forward entry points
        mReverseEntryPoints - list of reverse entry points
        p - anchor point to match against one of the points in the specified lists
        Returns:
        the direction specified in the matching entry point or EntryPoint.UNKNOWN

      • isInternalLevelXingAC

        public boolean isInternalLevelXingAC​(@Nonnull
                                     LevelXing x,
                                     @Nonnull
                                     Block block)
        Check if the AC track of a Level Crossing and its two connecting Track Segments are internal to the specified block.

        Note: if two connecting track segments are in the block, but the internal connecting track is not, that is an error in the Layout Editor panel. If found, an error message is generated and this method returns false.

        Parameters:
        x - the level crossing to check
        block - the block to check
        Returns:
        true if the A and C track segments of LevelXing x is in Block block; false otherwise

      • isInternalLevelXingBD

        public boolean isInternalLevelXingBD​(@Nonnull
                                     LevelXing x,
                                     @Nonnull
                                     Block block)
        Check if the BD track of a Level Crossing and its two connecting Track Segments are internal to the specified block.

        Note: if two connecting track segments are in the block, but the internal connecting track is not, that is an error in the Layout Editor panel. If found, an error message is generated and this method returns false.

        Parameters:
        x - the level crossing to check
        block - the block to check
        Returns:
        true if the B and D track segments of LevelXing x is in Block block; false otherwise

      • addSensorToSignalHeadLogic

        public boolean addSensorToSignalHeadLogic​(@CheckForNull
                                          java.lang.String name,
                                          @CheckForNull
                                          SignalHead sh,
                                          int where)
        Add the specified sensor ('name') to the SSL for the specified signal head 'name' should be the system name for the sensor.

        If the SSL has not been set up yet, the sensor is not added, an error message is output and 'false' is returned.

        Parameters:
        name - sensor name
        sh - signal head
        where - should be one of DIVERGING if the sensor is being added to the diverging (second) part of a facing mode SSL, CONTINUING if the sensor is being added to the continuing (first) part of a facing mode SSL, OVERALL if the sensor is being added to the overall sensor list of a facing mode SSL. 'where' is ignored if not a facing mode SSL
        Returns:
        'true' if the sensor was already in the signal head SSL or if it has been added successfully; 'false' and logs an error if not.

      • removeSensorsFromSignalHeadLogic

        public boolean removeSensorsFromSignalHeadLogic​(@CheckForNull
                                                java.util.List<java.lang.String> names,
                                                @CheckForNull
                                                SignalHead sh)
        Remove the specified sensors from the SSL for the specified signal head if any of the sensors is currently in the SSL.
        Parameters:
        names - the names of the sensors to remove
        sh - the signal head to remove the sensors from
        Returns:
        true if successful; false otherwise

      • getNextNode

        @CheckReturnValue
@CheckForNull
public TrackNode getNextNode​(@CheckForNull
                             TrackNode currentNode,
                             int currentNodeType)
        Get the next TrackNode following the specified TrackNode.
        Parameters:
        currentNode - the current node
        currentNodeType - the possible path to follow (for example, if the current node is a turnout entered at its throat, the path could be the thrown or closed path)
        Returns:
        the next TrackNode following currentNode for the given state or null if unable to follow the track

      • getTrackNode

        @CheckReturnValue
@CheckForNull
public TrackNode getTrackNode​(@Nonnull
                              LayoutTrack currentNode,
                              HitPointType currentNodeType,
                              @CheckForNull
                              TrackSegment currentTrackSegment,
                              int currentNodeState)
        Get the next TrackNode following the specified TrackNode, assuming that TrackNode was reached via the specified TrackSegment.

        If the specified track node can lead to different paths to the next node, for example, if the specified track node is a turnout entered at its throat, then "currentNodeType" must be specified to choose between the possible paths. If currentNodeType = 0, the search will follow the 'continuing' track; if currentNodeType = 1, the search will follow the 'diverging' track; if currentNodeType = 2 (3-way turnouts only), the search will follow the second 'diverging' track.

        In determining which track is the 'continuing' track for RH, LH, and WYE turnouts, this search routine uses the layout turnout's 'continuingState'.

        When following track, this method skips over anchor points that are not block boundaries.

        When following track, this method treats a modeled 3-way turnout as a single turnout. It also treats two THROAT_TO_THROAT turnouts as a single turnout, but with each turnout having a continuing sense.

        Parameters:
        currentNode - the current node
        currentNodeType - the type of node
        currentTrackSegment - the followed track segment
        currentNodeState - the possible path to follow (for example, if the current node is a turnout entered at its throat, the path could be the thrown or closed path)
        Returns:
        the next TrackNode following currentNode for the given state if a node or end_of-track is reached or null if unable to follow the track

      • getExitBlockForTrackNode

        @CheckReturnValue
@CheckForNull
public Block getExitBlockForTrackNode​(@CheckForNull
                                      TrackNode node,
                                      @CheckForNull
                                      Block excludedBlock)
        Get an "exit block" for the specified track node if there is one, else returns null. An "exit block" must be different from the block of the track segment in the node. If the node is a PositionablePoint, it is assumed to be a block boundary anchor point.
        Parameters:
        node - the node to get the exit block for
        excludedBlock - blocks not to be considered as exit blocks
        Returns:
        the exit block for node or null if none exists

      • isTurnoutConnectivityComplete

        public boolean isTurnoutConnectivityComplete()
        Check if the connectivity of the turnouts has been completed in the block after calling getTurnoutList().
        Returns:
        true if turnout connectivity is complete; otherwise false