Package jmri.jmrit.logix

Class OBlock

  • All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.lang.Comparable<NamedBean>, java.util.EventListener, PropertyChangeProvider, NamedBean, PhysicalLocationReporter
    public class OBlock
extends Block
implements java.beans.PropertyChangeListener
    OBlock extends jmri.Block to be used in Logix Conditionals and Warrants. It is the smallest piece of track that can have occupancy detection. A better name would be Detection Circuit. However, an OBlock can be defined without an occupancy sensor and used to calculate routes.

    Additional states are defined to indicate status of the track and trains to control panels. A jmri.Block has a PropertyChangeListener on the occupancy sensor and the OBlock will pass state changes of the occ.sensor on to its Warrant.

    Entrances (exits when train moves in opposite direction) to OBlocks have Portals. A Portal object is a pair of OBlocks. Each OBlock has a list of its Portals.

    When an OBlock (Detection Circuit) has a Portal whose entrance to the OBlock has a signal, then the OBlock and its chains of adjacent OBlocks up to the next OBlock having an entrance Portal with a signal, can be considered a "Block" in the sense of a prototypical railroad. Preferably all entrances to the "Block" should have entrance Portals with a signal.

    A Portal has a list of paths (OPath objects) for each OBlock it separates. The paths are determined by the turnout settings of the turnouts contained in the block. Paths are contained within the Block boundaries. Names of OPath objects only need be unique within an OBlock.

    • Constructor Detail

      • OBlock

        public OBlock​(@Nonnull
              java.lang.String systemName,
              java.lang.String userName)

    • Method Detail

      • getLocalStatusName

        public static java.lang.String getLocalStatusName​(java.lang.String str)

      • getSystemStatusName

        public static java.lang.String getSystemStatusName​(java.lang.String str)

      • equals

        public boolean equals​(java.lang.Object obj)
        Description copied from class: Block
        Note: this has to make choices about identity values (always the same) and operation values (can change as the block works). Might be missing some identity values.
        Overrides:
        equals in class Block
        Parameters:
        obj - the reference object with which to compare.
        Returns:
        true if this object is the same as the obj argument; false otherwise.

      • setSensor

        public boolean setSensor​(java.lang.String pName)
        Set the sensor by name. Fires propertyChange "OccupancySensorChange" when changed.

        Override to only set an existing sensor and to amend state with not UNDETECTED return true if an existing Sensor is set or sensor is to be removed from block.

        Overrides:
        setSensor in class Block
        Parameters:
        pName - the name of the Sensor to set
        Returns:
        true if a Sensor is set and is not null; false otherwise

      • setNamedSensor

        public void setNamedSensor​(NamedBeanHandle<Sensor> namedSensor)
        Description copied from class: Block
        Set Block Occupancy Sensor. If Sensor set, Adds PCL, sets Block Occupancy Status to Sensor. Block State PropertyChange Event will fire. Does NOT route initial Sensor Status via goingUnknown() / goingActive() etc.

        If Sensor null, removes PCL on previous Sensor, sets Block status to UNDETECTED.

        Overrides:
        setNamedSensor in class Block
        Parameters:
        namedSensor - Handle for Sensor.

      • setErrorSensor

        public boolean setErrorSensor​(java.lang.String pName)
        Parameters:
        pName - name of error sensor
        Returns:
        true if successful

      • propertyChange

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

      • isPathSet

        protected java.lang.String isPathSet​(@Nonnull
                                     java.lang.String path)
        Another block sharing a turnout with this block queries whether turnout is in use.
        Parameters:
        path - that uses a common shared turnout
        Returns:
        If warrant exists and path==pathname, return warrant display name, else null.

      • setState

        public void setState​(int v)
        Update the OBlock status. Override Block because change must come from an OBlock for Web Server to receive it
        Specified by:
        setState in interface NamedBean
        Overrides:
        setState in class Block
        Parameters:
        v - the new state, from OBlock.ALLOCATED etc, named 'status' in JSON Servlet and Web Server

      • setValue

        public void setValue​(java.lang.Object o)
        Set the value retained by this Block. Also used when the Block itself gathers a value from an adjacent Block. This can be overridden in a subclass if e.g. you want to keep track of Blocks elsewhere, but make sure you also eventually invoke the super.setValue() here. Fires propertyChange "value" when changed.
        Overrides:
        setValue in class Block
        Parameters:
        o - The new Object resident in this block, or null if none

      • statusIs

        public boolean statusIs​(java.lang.String statusName)

      • isDark

        public boolean isDark()

      • occupiedBy

        public java.lang.String occupiedBy()

      • isFree

        public boolean isFree()
        Test that block is not occupied and not allocated
        Returns:
        true if not occupied and not allocated

      • allocate

        @CheckForNull
public java.lang.String allocate​(Warrant warrant)
        Allocate (reserves) the block for the Warrant Note the block may be OCCUPIED by a non-warranted train, but the allocation is permitted.
        Parameters:
        warrant - the Warrant
        Returns:
        message with if block is already allocated to another warrant or block is OUT_OF_SERVICE

      • allocatePath

        @CheckForNull
public java.lang.String allocatePath​(java.lang.String pathName)
        Note path name may be set if block is not allocated to a warrant. For use by CircuitBuilder Only. (test paths for editCircuitPaths)
        Parameters:
        pathName - name of a path
        Returns:
        error message, otherwise null

      • deAllocate

        public boolean deAllocate​(Warrant warrant)
        Remove allocation state // maybe restore this? Remove listener regardless of ownership
        Parameters:
        warrant - warrant that has reserved this block. null is allowed for Conditionals and CircuitBuilder to reset the block. Otherwise, null should not be used.
        Returns:
        true if warrant deallocated.

      • setError

        public void setError​(boolean set)

      • addPortal

        public void addPortal​(Portal portal)
        Enforce unique portal names. Portals are now managed beans since 2014. This enforces unique names.
        Parameters:
        portal - the Portal to add

      • removePortal

        protected void removePortal​(@CheckForNull
                            Portal portal)
        Remove portal from OBlock and stub all paths using this portal to be dead end spurs.
        Parameters:
        portal - the Portal to remove

      • setLength

        public void setLength​(float len)
        Description copied from class: Block
        Set length in millimeters. Paths will inherit this length, if their length is not specifically set. This length is the maximum length of any Path in the block. Path lengths exceeding this will be set to the default length.

        Fires propertyChange "BlockLengthChange" when changed, float values in mm.

        Overrides:
        setLength in class Block
        Parameters:
        len - length in millimeters

      • addPath

        public boolean addPath​(OPath path)
        Enforce unique path names within OBlock, but allow a duplicate name of an OPath from another OBlock to be checked if it is in one of the OBlock's Portals.
        Parameters:
        path - the OPath to add
        Returns:
        true if path was added to OBlock

      • setPath

        protected java.lang.String setPath​(java.lang.String pathName,
                                   Warrant warrant)
        Set Turnouts for the path.

        Called by warrants to set turnouts for a train it is able to run. The warrant parameter verifies that the block is indeed allocated to the warrant. If the block is unwarranted then the block is allocated to the calling warrant. A logix conditional may also call this method with a null warrant parameter for manual logix control. If the block is under a different warrant the call will be rejected.

        Parameters:
        pathName - name of the path
        warrant - warrant the block is allocated to
        Returns:
        error message if the call fails. null if the call succeeds

      • pseudoPropertyChange

        public void pseudoPropertyChange​(java.lang.String propName,
                                 java.lang.Object old,
                                 java.lang.Object n)

      • goingInactive

        public void goingInactive()
        (Override) Handles Block sensor going INACTIVE: this block is empty. Called by handleSensorChange
        Overrides:
        goingInactive in class Block

      • goingActive

        public void goingActive()
        (Override) Handles Block sensor going ACTIVE: this block is now occupied, figure out from who and copy their value. Called by handleSensorChange
        Overrides:
        goingActive in class Block

      • 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

        @Nonnull
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
        Overrides:
        getBeanType in class Block
        Returns:
        a string of the bean type, eg Turnout, Sensor etc