Package jmri.jmrit.display.layoutEditor

Class LayoutBlock

  • All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.lang.Comparable<NamedBean>, java.util.EventListener, PropertyChangeProvider, NamedBean
    public class LayoutBlock
extends AbstractNamedBean
implements java.beans.PropertyChangeListener
    A LayoutBlock is a group of track segments and turnouts on a LayoutEditor panel corresponding to a 'block'. LayoutBlock is a LayoutEditor specific extension of the JMRI Block object.

    LayoutBlocks may have an occupancy Sensor. The getOccupancy method returns the occupancy state of the LayoutBlock - OCCUPIED, EMPTY, or UNKNOWN. If no occupancy sensor is provided, UNKNOWN is returned. The occupancy sensor if there is one, is the same as the occupancy sensor of the corresponding JMRI Block.

    The name of each Layout Block is the same as that of the corresponding block as defined in Layout Editor. A corresponding JMRI Block object is created when a LayoutBlock is created. The JMRI Block uses the name of the block defined in Layout Editor as its user name and a unique IBnnn system name. The JMRI Block object and its associated Path objects are useful in tracking a train around the layout. Blocks may be viewed in the Block Table.

    A LayoutBlock may have an associated Memory object. This Memory object contains a string representing the current "value" of the corresponding JMRI Block object. If the value contains a train name, for example, displaying Memory objects associated with LayoutBlocks, and displayed near each Layout Block can follow a train around the layout, displaying its name when it is in the LayoutBlock.

    LayoutBlocks are "cross-panel", similar to sensors and turnouts. A LayoutBlock may be used by more than one Layout Editor panel simultaneously. As a consequence, LayoutBlocks are saved with the configuration, not with a panel.

    LayoutBlocks are used by TrackSegments, LevelXings, and LayoutTurnouts. LevelXings carry two LayoutBlock designations, which may be the same. LayoutTurnouts carry LayoutBlock designations also, one per turnout, except for double crossovers and slips which can have up to four.

    LayoutBlocks carry a use count. The use count counts the number of track segments, layout turnouts, and levelcrossings which use the LayoutBlock. Only LayoutBlocks which have a use count greater than zero are saved when the configuration is saved.

    • Constructor Detail

      • LayoutBlock

        public LayoutBlock​(java.lang.String sName,
                   java.lang.String uName)
        Creates a LayoutBlock object. Note: initializeLayoutBlock() must be called to complete the process. They are split so that loading of panel files will be independent of whether LayoutBlocks or Blocks are loaded first.
        Parameters:
        sName - System name of this LayoutBlock
        uName - User name of this LayoutBlock but also the user name of the associated Block

    • Method Detail

      • initializeLayoutBlock

        public void initializeLayoutBlock()
        Completes the creation of a LayoutBlock object by adding a Block to it. The block create process takes into account that the _bean register process considers IB1 and IB01 to be the same name which results in a silent failure.

      • getId

        public java.lang.String getId()

      • addLayoutEditor

        public void addLayoutEditor​(LayoutEditor panel)
        Keep track of LayoutEditor panels that are using this LayoutBlock.
        Parameters:
        panel - to keep track of

      • validateSensor

        public Sensor validateSensor​(java.lang.String sensorName,
                             java.awt.Component openFrame)
        Validate that the supplied occupancy sensor name corresponds to an existing sensor and is unique among all blocks. If valid, returns the sensor and sets the block sensor name in the block. Else returns null, and does nothing to the block.
        Parameters:
        sensorName - to check
        openFrame - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used
        Returns:
        the validated sensor

      • validateMemory

        public Memory validateMemory​(java.lang.String memName,
                             java.awt.Component openFrame)
        Validate that the memory name corresponds to an existing memory. If valid, returns the memory. Else returns null, and notifies the user.
        Parameters:
        memName - the memory name
        openFrame - the frame to display any error dialog in
        Returns:
        the memory

      • getBlockColor

        public java.awt.Color getBlockColor()
        Get the color for drawing items in this block. Returns color based on block occupancy.
        Returns:
        color for block

      • getBlock

        public Block getBlock()
        Get the Block corresponding to this LayoutBlock.
        Returns:
        block

      • getMemoryName

        public java.lang.String getMemoryName()
        Returns Memory name
        Returns:
        name of memory

      • setMemoryName

        public void setMemoryName​(java.lang.String name)
        Add Memory by name.
        Parameters:
        name - for memory

      • getOccupancySensorName

        public java.lang.String getOccupancySensorName()
        Get occupancy Sensor name.
        Returns:
        name of occupancy sensor

      • getOccupancySensor

        public Sensor getOccupancySensor()
        Get occupancy Sensor.

        If a sensor has not been assigned, try getting the sensor from the related block.

        When setting the layout block sensor from the block itself using the OccupancySensorChange event, the automatic assignment has to be disabled for the sensor checking performed by LayoutBlockManager.getBlockWithSensorAssigned(jmri.Sensor)

        Returns:
        occupancy sensor or null

      • setOccupancySensorName

        public void setOccupancySensorName​(java.lang.String name)
        Add occupancy sensor by name.
        Parameters:
        name - for senor to add

      • getOccupiedSense

        public int getOccupiedSense()
        Get occupied sensor state.
        Returns:
        occupied sensor state, defaults to Sensor.ACTIVE

      • setOccupiedSense

        public void setOccupiedSense​(int sense)
        Set occupied sensor state.
        Parameters:
        sense - eg. Sensor.INACTIVE

      • getOccupancy

        public int getOccupancy()
        Test block occupancy.
        Returns:
        occupancy state

      • 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 i)
        Does nothing, do not use.Dummy for completion of NamedBean interface
        Specified by:
        setState in interface NamedBean
        Parameters:
        i - does nothing

      • getMaxConnectedPanel

        public LayoutEditor getMaxConnectedPanel()
        Get the panel with the highest connectivity to this Layout Block.
        Returns:
        panel with most connections to this block

      • updatePaths

        public void updatePaths()
        Check/Update Path objects for the attached Block

        If multiple panels are present, Paths are set according to the panel with the highest connectivity (most LayoutConnectivity objects).

      • updatePathsUsingPanel

        public void updatePathsUsingPanel​(LayoutEditor panel)
        Check/Update Path objects for the attached Block using the connectivity in the specified Layout Editor panel.
        Parameters:
        panel - to extract paths

      • handleBlockChange

        void handleBlockChange​(java.beans.PropertyChangeEvent e)
        Handle tasks when block changes
        Parameters:
        e - propChgEvent

      • setSuppressNameUpdate

        public void setSuppressNameUpdate​(boolean set)
        Set/reset update of memory name when block goes from occupied to unoccupied or vice versa. If set is true, name update is suppressed. If set is false, name update works normally.
        Parameters:
        set - true, update suppress. false, update normal

      • editLayoutBlock

        public void editLayoutBlock​(java.awt.Component callingPane)

      • remove

        void remove()
        Remove this object from display and persistance.

      • isActive

        public boolean isActive()
        "active" is true if the object is still displayed, and should be stored.
        Returns:
        active

      • setBlockMetric

        void setBlockMetric()
        Set the block metric based upon the track segment that the block is associated with if the (200 if Side, 50 if Main). If the block is assigned against multiple track segments all with different types then the highest type will be used. In theory no reason why it couldn't be a compromise.

      • setBlockMetric

        public void setBlockMetric​(int m)
        Set a metric cost against a block, this is used in the calculation of a path between two location on the layout, a lower path cost is always preferred For Layout blocks defined as Mainline the default metric is 50. For Layout blocks defined as a Siding the default metric is 200.
        Parameters:
        m - metric value

      • getBlockMetric

        public int getBlockMetric()
        Get the layout block metric cost
        Returns:
        metric cost of block

      • updateNeighbourPacketFlow

        protected void updateNeighbourPacketFlow​(jmri.jmrit.display.layoutEditor.LayoutBlock.Adjacencies neighbour,
                                         int flow)

      • printValidThroughPaths

        public void printValidThroughPaths()
        Provide an output to the console of all the valid paths through this block.

      • printAdjacencies

        public void printAdjacencies()
        Provide an output to the console of all our neighbouring blocks.

      • printRoutes

        public void printRoutes()
        Provide an output to the console of all the remote blocks reachable from our block.

      • printRoutes

        public void printRoutes​(java.lang.String inBlockName)
        Provide an output to the console of how to reach a specific block from our block.
        Parameters:
        inBlockName - to find in route

      • getNextBlock

        public Block getNextBlock​(Block destBlock,
                          int direction)
        Parameters:
        destBlock - is the destination of the block we are following
        direction - is the direction of travel from the previous block
        Returns:
        next block

      • getNextBlock

        @CheckForNull
public Block getNextBlock​(Block previousBlock,
                          Block destBlock)
        Used if we already know the block prior to our block, and the destination block. direction, is optional and is used where the previousBlock is equal to our block.
        Parameters:
        previousBlock - start block
        destBlock - finish block
        Returns:
        next block

      • getNextBestBlock

        public int getNextBestBlock​(Block previousBlock,
                            Block destBlock,
                            java.util.List<java.lang.Integer> excludeBlock,
                            LayoutBlockConnectivityTools.Metric routingMethod)
        last index - the index of the last block we returned ie we last returned index 10, so we don't want to return it again. The block returned will have a hopcount or metric equal to or greater than the one of the last block returned. if the exclude block list is empty this is the first time, it has been used. The parameters for the best last block are based upon the last entry in the excludedBlock list.
        Parameters:
        previousBlock - starting block
        destBlock - finish block
        excludeBlock - blocks to skip
        routingMethod - value to match metric
        Returns:
        next block

      • propertyChange

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

      • getValidRoute

        @CheckForNull
jmri.jmrit.display.layoutEditor.LayoutBlock.Routes getValidRoute​(Block nxtBlock,
                                                                 Block dstBlock)
        Get valid Routes, based upon the next block and destination block
        Parameters:
        nxtBlock - next block
        dstBlock - final block
        Returns:
        routes that fit, or null

      • isRouteToDestValid

        public boolean isRouteToDestValid​(Block protecting,
                                  Block destination)
        Is the route to the destination block, going via our neighbouring block valid. ie Does the block have a route registered via neighbour "protecting" to the destination block.
        Parameters:
        protecting - neighbour block that might protect
        destination - block
        Returns:
        true if we have valid path to block

      • getDestRoutes

        java.util.List<jmri.jmrit.display.layoutEditor.LayoutBlock.Routes> getDestRoutes​(Block dstBlock)
        Get a list of valid Routes to our destination block
        Parameters:
        dstBlock - target to find
        Returns:
        routes between this and dstBlock

      • getNextRoutes

        java.util.List<jmri.jmrit.display.layoutEditor.LayoutBlock.Routes> getNextRoutes​(Block nxtBlock)
        Get a list of valid Routes via our next block
        Parameters:
        nxtBlock - target block
        Returns:
        list of routes to target block

      • updateRoutingInfo

        void updateRoutingInfo​(jmri.jmrit.display.layoutEditor.LayoutBlock.Routes route)

      • updateRoutesToNeighbours

        void updateRoutesToNeighbours​(java.util.List<Block> messageRecipients,
                              jmri.jmrit.display.layoutEditor.LayoutBlock.Routes ro,
                              jmri.jmrit.display.layoutEditor.LayoutBlock.RoutingPacket update)

      • addRouteToNeighbours

        void addRouteToNeighbours​(jmri.jmrit.display.layoutEditor.LayoutBlock.Routes ro)

      • getNeighbourDirection

        public int getNeighbourDirection​(LayoutBlock neigh)
        Get the direction of travel to our neighbouring block.
        Parameters:
        neigh - neighbor block
        Returns:
        direction to get to neighbor block

      • getAdjacency

        jmri.jmrit.display.layoutEditor.LayoutBlock.Adjacencies getAdjacency​(Block blk)

      • getNumberOfNeighbours

        public int getNumberOfNeighbours()
        Get the number of neighbor blocks attached to this block.
        Returns:
        count of neighbor

      • getNeighbourAtIndex

        public Block getNeighbourAtIndex​(int i)
        Get the neighboring block at index i.
        Parameters:
        i - index to neighbor
        Returns:
        neighbor block

      • getNeighbourDirection

        public int getNeighbourDirection​(int i)
        Get the direction of travel to neighbouring block at index i.
        Parameters:
        i - index in neighbors
        Returns:
        neighbor block

      • getNeighbourMetric

        public int getNeighbourMetric​(int i)
        Get the metric/cost to neighbouring block at index i.
        Parameters:
        i - index in neighbors
        Returns:
        metric of neighbor

      • getNeighbourPacketFlowAsString

        public java.lang.String getNeighbourPacketFlowAsString​(int i)
        Get the flow of traffic to and from neighbouring block at index i RXTX - Means Traffic can flow both ways between the blocks RXONLY - Means we can only receive traffic from our neighbour, we can not send traffic to it TXONLY - Means we do not receive traffic from our neighbour, but can send traffic to it.
        Parameters:
        i - index in neighbors
        Returns:
        direction of traffic

      • isNeighbourMutual

        public boolean isNeighbourMutual​(int i)
        Is our neighbouring block at index i a mutual neighbour, ie both blocks have each other registered as neighbours and are exchanging information.
        Parameters:
        i - index of neighbor
        Returns:
        true if both are mutual neighbors

      • getNeighbourIndex

        int getNeighbourIndex​(jmri.jmrit.display.layoutEditor.LayoutBlock.Adjacencies adj)

      • getNumberOfRoutes

        public int getNumberOfRoutes()
        Get the number of routes that the block has registered.
        Returns:
        count of routes

      • getRouteDirectionAtIndex

        public int getRouteDirectionAtIndex​(int i)
        Get the direction of route i.
        Parameters:
        i - index in routes
        Returns:
        direction

      • getRouteDestBlockAtIndex

        public Block getRouteDestBlockAtIndex​(int i)
        Get the destination block at route i
        Parameters:
        i - index in routes
        Returns:
        dest block from route

      • getRouteNextBlockAtIndex

        public Block getRouteNextBlockAtIndex​(int i)
        Get the next block at route i
        Parameters:
        i - index in routes
        Returns:
        next block from route

      • getRouteHopCountAtIndex

        public int getRouteHopCountAtIndex​(int i)
        Get the hop count of route i.
        The Hop count is the number of other blocks that we traverse to get to the destination
        Parameters:
        i - index in routes
        Returns:
        hop count

      • getRouteLengthAtIndex

        public float getRouteLengthAtIndex​(int i)
        Get the length of route i.
        The length is the combined length of all the blocks that we traverse to get to the destination
        Parameters:
        i - index in routes
        Returns:
        length of block in route

      • getRouteMetric

        public int getRouteMetric​(int i)
        Get the metric/cost at route i
        Parameters:
        i - index in routes
        Returns:
        metric

      • getRouteState

        public int getRouteState​(int i)
        Get the state (Occupied, unoccupied) of the destination layout block at index i
        Parameters:
        i - index in routes
        Returns:
        state of block

      • getRouteValid

        public boolean getRouteValid​(int i)
        Is the route to the destination potentially valid from our block.
        Parameters:
        i - index in route
        Returns:
        true if route is valid

      • getRouteStateAsString

        public java.lang.String getRouteStateAsString​(int i)
        Get the state of the destination layout block at index i as a string.
        Parameters:
        i - index in routes
        Returns:
        dest status

      • getRouteIndex

        int getRouteIndex​(jmri.jmrit.display.layoutEditor.LayoutBlock.Routes r)

      • getBlockHopCount

        public int getBlockHopCount​(Block destination,
                            Block nextBlock)
        Get the number of layout blocks to our desintation block going from the next directly connected block. If the destination block and nextblock are the same and the block is also registered as a neighbour then 1 is returned. If no valid route to the destination block can be found via the next block then -1 is returned. If more than one route exists to the destination then the route with the lowest count is returned.
        Parameters:
        destination - final block
        nextBlock - adjcent block
        Returns:
        hop count to final, -1 if not available

      • getBlockMetric

        public int getBlockMetric​(Block destination,
                          Block nextBlock)
        Get the metric to our desintation block going from the next directly connected block. If the destination block and nextblock are the same and the block is also registered as a neighbour then 1 is returned. If no valid route to the destination block can be found via the next block then -1 is returned. If more than one route exists to the destination then the route with the lowest count is returned.
        Parameters:
        destination - final block
        nextBlock - adjcent block
        Returns:
        metric to final block, -1 if not available

      • getBlockLength

        public float getBlockLength​(Block destination,
                            Block nextBlock)
        Get the distance to our desintation block going from the next directly connected block. If the destination block and nextblock are the same and the block is also registered as a neighbour then 1 is returned. If no valid route to the destination block can be found via the next block then -1 is returned. If more than one route exists to the destination then the route with the lowest count is returned.
        Parameters:
        destination - final block
        nextBlock - adjcent block
        Returns:
        lenght to final, -1 if not viable

      • getNumberOfThroughPaths

        public int getNumberOfThroughPaths()
        Get the number of valid through paths on this block.
        Returns:
        count of paths through this block

      • getThroughPathSource

        public Block getThroughPathSource​(int i)
        Get the source block at index i
        Parameters:
        i - index in throughPaths
        Returns:
        source block

      • getThroughPathDestination

        public Block getThroughPathDestination​(int i)
        Get the destination block at index i
        Parameters:
        i - index in throughPaths
        Returns:
        final block

      • isThroughPathActive

        public java.lang.Boolean isThroughPathActive​(int i)
        Is the through path at index i active?
        Parameters:
        i - index in path
        Returns:
        active or not

      • checkIsRouteOnValidThroughPath

        boolean checkIsRouteOnValidThroughPath​(jmri.jmrit.display.layoutEditor.LayoutBlock.Routes r)
        When a route is created, check to see if the through path that this route relates to is active.
        Parameters:
        r - The route to check
        Returns:
        true if that route is active

      • refreshValidRoutes

        public void refreshValidRoutes()
        Go through all the routes and refresh the valid flag.

      • updateActiveThroughPaths

        void updateActiveThroughPaths​(jmri.jmrit.display.layoutEditor.LayoutBlock.ThroughPaths tp,
                              boolean active)

      • setRoutesValid

        void setRoutesValid​(Block nxtHopActive,
                    boolean state)
        Set the valid flag for routes that are on a valid through path.
        Parameters:
        nxtHopActive - the start of the route
        state - the state to set into the valid flag

      • 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