Package jmri.jmrit.logix

Class OBlock

java.lang.Object
jmri.implementation.AbstractNamedBean
jmri.Block
jmri.jmrit.logix.OBlock
All Implemented Interfaces:
PropertyChangeListener, Comparable<NamedBean>, EventListener, PropertyChangeProvider, NamedBean, PhysicalLocationReporter
public class OBlock extends Block implements 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.

  • Field Details

  • Constructor Details

  • Method Details

    • getLocalStatusName

      public static String getLocalStatusName(String str)

    • getSystemStatusName

      public static String getSystemStatusName(String str)

    • equals

      public boolean equals(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.

    • hashCode

      public int hashCode()
      Description copied from class: AbstractNamedBean
      Overrides:
      hashCode in class Block
      Returns:
      hash code value is based on the system name.

    • setSensor

      public boolean setSensor(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(@CheckForNull 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(@CheckForNull String pName)
      Parameters:
      pName - name of error sensor
      Returns:
      true if successful

    • getErrorSensor

      @CheckForNull public Sensor getErrorSensor()

    • getNamedErrorSensor

      @CheckForNull public NamedBeanHandle<Sensor> getNamedErrorSensor()

    • propertyChange

      public void propertyChange(PropertyChangeEvent evt)
      Specified by:
      propertyChange in interface PropertyChangeListener

    • isPathSet

      @CheckForNull protected String isPathSet(@Nonnull 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.

    • getWarrant

      @CheckForNull public Warrant getWarrant()

    • isAllocatedTo

      public boolean isAllocatedTo(@CheckForNull Warrant warrant)

    • getAllocatedPathName

      public String getAllocatedPathName()

    • setMetricUnits

      public void setMetricUnits(boolean type)

    • isMetric

      public boolean isMetric()

    • setMarkerForeground

      public void setMarkerForeground(Color c)

    • getMarkerForeground

      public Color getMarkerForeground()

    • setMarkerBackground

      public void setMarkerBackground(Color c)

    • getMarkerBackground

      public Color getMarkerBackground()

    • setMarkerFont

      public void setMarkerFont(Font f)

    • getMarkerFont

      public Font getMarkerFont()

    • 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(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(String statusName)

    • isDark

      public boolean isDark()

    • isOccupied

      public boolean isOccupied()

    • occupiedBy

      @CheckForNull public 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 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

    • showAllocated

      protected void showAllocated(Warrant warrant, String pathName)

    • allocatePath

      @CheckForNull public String allocatePath(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

    • getAllocatingWarrantName

      public String getAllocatingWarrantName()

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

    • setOutOfService

      public void setOutOfService(boolean set)

    • 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

    • getPortalByName

      public Portal getPortalByName(String name)

    • getPortals

      @Nonnull public List<Portal> getPortals()

    • setPortals

      public void setPortals(ArrayList<Portal> portals)

    • getPathByName

      public OPath getPathByName(String name)

    • 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

    • removeOPath

      public boolean removeOPath(OPath path)

    • setPath

      protected String setPath(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

    • getPath

      protected OPath getPath()

    • pseudoPropertyChange

      public void pseudoPropertyChange(String propName, Object old, 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

    • goingUnknown

      public void goingUnknown()
      Overrides:
      goingUnknown in class Block

    • goingInconsistent

      public void goingInconsistent()
      Overrides:
      goingInconsistent 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

    • getDescription

      public String getDescription()

    • getUsageReport

      public List<NamedBeanUsageReport> getUsageReport(NamedBean bean)
      Description copied from interface: NamedBean
      Get a list of references for the specified bean.
      Specified by:
      getUsageReport in interface NamedBean
      Overrides:
      getUsageReport in class Block
      Parameters:
      bean - The bean to be checked.
      Returns:
      a list of NamedBeanUsageReports or an empty ArrayList.

    • getBeanType

      @Nonnull public 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