Class ConnectivityUtil

java.lang.Object
jmri.jmrit.display.layoutEditor.ConnectivityUtil

public final class ConnectivityUtil
extends 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.

  • Field Details

  • Constructor Details

  • Method Details

    • getTurnoutList

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

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

      Get a list of all anchor point boundaries involving the specified Block.
      Parameters:
      block - the block to get anchor point boundaries for
      Returns:
      a list of anchor point boundaries
    • getLevelCrossingsThisBlock

      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

      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

      Check if specified LayoutTurnout has required signals.
      Parameters:
      t - the LayoutTurnout to check
      Returns:
      true if specified LayoutTurnout has required signal heads; false otherwise
    • getSignalHeadAtAnchor

      Get the SignalHead at the Anchor block boundary.
      Parameters:
      p - the anchor with the signal head
      block - the adjacent block
      facing - true if SignalHead facing towards block should be returned; false if SignalHead facing away from block should be returned
      Returns:
      a SignalHead facing away from or towards block depending on value of facing; may be null
    • getSignalMastAtAnchor

      Get the SignalMast at the Anchor block boundary.
      Parameters:
      p - the anchor with the signal head
      block - the adjacent block
      facing - true if SignalMast facing towards block should be returned; false if SignalMast facing away from block should be returned
      Returns:
      a SignalMast facing away from or towards block depending on value of facing; may be null
    • layoutTurnoutHasSignalMasts

    • getSignalHeadAtLevelXing

      Get the SignalHead at the level crossing.
      Parameters:
      x - the level crossing
      block - the adjacent block
      facing - true if SignalHead facing towards block should be returned; false if SignalHead facing away from block should be returned
      Returns:
      a SignalHead facing away from or towards block depending on value of facing; may be null
    • blockInternalToLevelXing

      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 List<EntryPoint> mForwardEntryPoints, @Nonnull 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 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

      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

      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

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