Class Block
- java.lang.Object
-
- jmri.implementation.AbstractNamedBean
-
- jmri.Block
-
- All Implemented Interfaces:
java.lang.Comparable<NamedBean>
,PropertyChangeProvider
,NamedBean
,PhysicalLocationReporter
- Direct Known Subclasses:
OBlock
public class Block extends AbstractNamedBean implements PhysicalLocationReporter
Represents a particular piece of track, more informally a "Block".A Block (at least in this implementation) corresponds exactly to the track covered by at most one sensor. That could be generalized in the future.
As trains move around the layout, a set of Block objects that are attached to sensors can interact to keep track of which train is where, going in which direction. As a result of this, the set of Block objects pass around "token" (value) Objects representing the trains. This could be e.g. a Throttle to control the train, or something else.
A block maintains a "direction" flag that is set from the direction of the incoming train. When an arriving train is detected via the connected sensor and the Block's status information is sufficient to determine that it is arriving via a particular Path, that Path's getFromBlockDirection becomes the direction of the train in this Block.
Optionally, a Block can be associated with a Reporter. In this case, the Reporter will provide the Block with the "token" (value). This could be e.g an RFID reader reading an ID tag attached to a locomotive. Depending on the specific Reporter implementation, either the current reported value or the last reported value will be relevant, this can be configured.
Objects of this class are Named Beans, so can be manipulated through tables, have listeners, etc.
The type letter used in the System Name is 'B' for 'Block'. The default implementation is not system-specific, so a system letter of 'I' is appropriate. This leads to system names like "IB201".
Issues:
- The tracking doesn't handle a train pulling in behind another well:
- When the 2nd train arrives, the Sensor is already active, so the value is unchanged (but the value can only be a single object anyway)
- When the 1st train leaves, the Sensor stays active, so the value remains that of the 1st train
- The assumption is that a train will only go through a set turnout. For example, a train could come into the turnout block from the main even if the turnout is set to the siding. (Ignoring those layouts where this would cause a short; it doesn't do so on all layouts)
- Does not handle closely-following trains where there is only one electrical block per signal. To do this, it probably needs some type of "assume a train doesn't back up" logic. A better solution is to have multiple sensors and Block objects between each signal head.
- If a train reverses in a block and goes back the way it came (e.g. b1 to b2 to b1), the block that's re-entered will get an updated direction, but the direction of this block (b2 in the example) is not updated. In other words, we're not noticing that the train must have reversed to go back out.
Do not assume that a Block object uniquely represents a piece of track. To allow independent development, it must be possible for multiple Block objects to take care of a particular section of track.
Possible state values:
- UNKNOWN - The sensor shows UNKNOWN, so this block doesn't know if it's occupied or not.
- INCONSISTENT - The sensor shows INCONSISTENT, so this block doesn't know if it's occupied or not.
- OCCUPIED - This sensor went active. Note that OCCUPIED will be set even if the logic is unable to figure out which value to take.
- UNOCCUPIED - No content, because the sensor has determined this block is unoccupied.
- UNDETECTED - No sensor configured.
Possible Curvature attributes (optional) User can set the curvature if desired for use in automatic running of trains, to indicate where slow down is required.
- NONE - No curvature in Block track, or Not entered.
- GRADUAL - Gradual curve - no action by engineer is warranted - full speed OK
- TIGHT - Tight curve in Block track - Train should slow down some
- SEVERE - Severe curve in Block track - Train should slow down a lot
The length of the block may also optionally be entered if desired. This attribute is for use in automatic running of trains. Length should be the actual length of model railroad track in the block. It is always stored here in millimeter units. A length of 0.0 indicates no entry of length by the user.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.NamedBean
NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException
-
Nested classes/interfaces inherited from interface jmri.PhysicalLocationReporter
PhysicalLocationReporter.Direction
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
BLOCK_CURVATURE_CHANGE
Property name change fired when the Block Curvature changes.static java.lang.String
BLOCK_LENGTH_CHANGE
Property name change fired when the Block Length changes.static java.lang.String
BLOCK_PERMISSIVE_CHANGE
Property name change fired when the Block Permissive Status changes.static java.lang.String
BLOCK_REPORTER_CHANGE
Property name change fired when a Sensor is set to / removed from a Block.static java.lang.String
BLOCK_REPORTING_CURRENT
Property name change fired when the Block reporting Current flag changes.static java.lang.String
BLOCK_SPEED_CHANGE
Property name change fired when the Block Speed changes.static int
GRADUAL
Gradual Curvature.static int
NONE
No Curvature.static java.lang.String
OCC_SENSOR_CHANGE
Property name change fired when a Sensor is set to / removed from a Block.static int
OCCUPIED
static int
SEVERE
Severe Curvature.static int
TIGHT
Tight Curvature.static int
UNDETECTED
Undetected status, i.e a "Dark" block.static int
UNOCCUPIED
-
Fields inherited from class jmri.implementation.AbstractNamedBean
listenerRefs, mSystemName, register
-
Fields inherited from interface jmri.NamedBean
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addBlockDenyList(java.lang.String pName)
Add to the Block Deny List.void
addBlockDenyList(Block blk)
void
addPath(Path p)
Add a Path to List of Paths.boolean
equals(java.lang.Object obj)
Note: this has to make choices about identity values (always the same) and operation values (can change as the block works).Path
findFromPath()
Find which path this Block became Active, without actually modifying the state of this block.java.lang.String
getBeanType()
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.java.lang.String
getBlockSpeed()
int
getCurvature()
Get Block Curvature Constant.java.util.List<java.lang.String>
getDeniedBlocks()
int
getDirection()
Get Block Direction of Travel.PhysicalLocationReporter.Direction
getDirection(java.lang.String rep)
Parses out a (possibly old) LnReporter-generated report string to extract the direction from within it based on this object's protocol.float
getLengthCm()
Get Block Length in Centimetres.float
getLengthIn()
Get Block Length in Inches.float
getLengthMm()
Get Block Length in Millimetres.LocoAddress
getLocoAddress(java.lang.String rep)
Parse a given string and return the LocoAddress value that is presumed stored within it based on this object's protocol.NamedBeanHandle<Sensor>
getNamedSensor()
java.util.List<Path>
getPaths()
Get a copy of the list of Paths.boolean
getPermissiveWorking()
Get if Block can have permissive working.PhysicalLocation
getPhysicalLocation()
Return this Block's physical location, if it exists.PhysicalLocation
getPhysicalLocation(java.lang.String s)
Return this Block's physical location, if it exists.Reporter
getReporter()
Retrieve the Reporter that is linked to this BlockSensor
getSensor()
Get the Block Occupancy Sensor.float
getSpeedLimit()
int
getState()
Get the Block State.java.util.List<NamedBeanUsageReport>
getUsageReport(NamedBean bean)
Get a list of references for the specified bean.java.lang.Object
getValue()
Get the Block Contents Value.void
goingActive()
Handles Block sensor going ACTIVE: this block is now occupied, figure out from who and copy their value.void
goingInactive()
Handles Block sensor going INACTIVE: this block is emptyvoid
goingInconsistent()
void
goingUnknown()
(package private) void
handleReporterChange(java.beans.PropertyChangeEvent e)
Handle change in Reporter value.(package private) void
handleSensorChange(java.beans.PropertyChangeEvent e)
Handle change in sensor state.int
hashCode()
boolean
hasPath(Path p)
Check if Block has a particular Path.boolean
isBlockDenied(java.lang.String deny)
boolean
isBlockDenied(Block deny)
boolean
isReportingCurrent()
Determine if the Block's value is being populated from thecurrent report
or from thelast report
.void
removeBlockDenyList(java.lang.String blk)
void
removeBlockDenyList(Block blk)
void
removePath(Path p)
Remove a Path from the Block.(package private) void
resetCandidateEntrancePaths()
void
setAllocated(java.lang.Boolean boo)
This allows the layout block to inform any listeners to the block that the higher level layout block has been set to "useExtraColor" which is an indication that it has been allocated to a section by the AutoDispatcher.(package private) boolean
setAsEntryBlockIfPossible(Block b)
void
setBlockSpeed(java.lang.String s)
Set the Block Speed, preferred method.void
setBlockSpeedName(java.lang.String s)
Set the Block Speed Name.void
setCurvature(int c)
Set Block Curvature Constant.void
setDirection(int direction)
Set Block Direction of Travel.void
setLength(float l)
Set length in millimeters.void
setNamedSensor(NamedBeanHandle<Sensor> s)
Set Block Occupancy Sensor.void
setPermissiveWorking(boolean w)
Set Block as permissive.void
setReporter(Reporter reporter)
Set the Reporter that should provide the data value for this block.void
setReportingCurrent(boolean reportingCurrent)
Define if the Block's value should be populated from thecurrent report
or from thelast report
.boolean
setSensor(java.lang.String pName)
Set the sensor by name.void
setState(int v)
Provide a general method for updating the report.void
setValue(java.lang.Object value)
Set the value retained by this Block.java.lang.String
toDebugString()
Create a Debug String, this should only be used for debugging...void
vetoableChange(java.beans.PropertyChangeEvent evt)
-
Methods inherited from class jmri.implementation.AbstractNamedBean
addPropertyChangeListener, addPropertyChangeListener, addPropertyChangeListener, addPropertyChangeListener, compareSystemNameSuffix, describeState, dispose, firePropertyChange, getComment, getDisplayName, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getPropertyChangeListeners, getPropertyChangeListenersByReference, getPropertyKeys, getSystemName, getUserName, removeProperty, removePropertyChangeListener, removePropertyChangeListener, setComment, setProperty, setUserName, toString, toStringSuffix, updateListenerRef
-
-
-
-
Field Detail
-
OCCUPIED
public static final int OCCUPIED
- See Also:
- Constant Field Values
-
UNOCCUPIED
public static final int UNOCCUPIED
- See Also:
- Constant Field Values
-
UNDETECTED
public static final int UNDETECTED
Undetected status, i.e a "Dark" block. A Block with unknown status could be waiting on feedback from a Sensor, hence undetected may be more appropriate if no Sensor.OBlocks use this constant in combination with other OBlock status flags. Block uses this constant as initial status, also when a Sensor is unset from the block.
- See Also:
- Constant Field Values
-
NONE
public static final int NONE
No Curvature.- See Also:
- Constant Field Values
-
GRADUAL
public static final int GRADUAL
Gradual Curvature.- See Also:
- Constant Field Values
-
TIGHT
public static final int TIGHT
Tight Curvature.- See Also:
- Constant Field Values
-
SEVERE
public static final int SEVERE
Severe Curvature.- See Also:
- Constant Field Values
-
OCC_SENSOR_CHANGE
public static final java.lang.String OCC_SENSOR_CHANGE
Property name change fired when a Sensor is set to / removed from a Block. The fired event includes old value: Sensor Bean Object if previously set, else null new value: Sensor Bean Object if being set, may be null if Sensor removed.- See Also:
- Constant Field Values
-
BLOCK_REPORTER_CHANGE
public static final java.lang.String BLOCK_REPORTER_CHANGE
Property name change fired when a Sensor is set to / removed from a Block. The fired event includes old value: Sensor Bean Object if previously set, else null new value: Sensor Bean Object if being set, may be null if Sensor removed.- See Also:
- Constant Field Values
-
BLOCK_REPORTING_CURRENT
public static final java.lang.String BLOCK_REPORTING_CURRENT
Property name change fired when the Block reporting Current flag changes. The fired event includes old value: previous value, Boolean. new value: new value, Boolean.- See Also:
- Constant Field Values
-
BLOCK_PERMISSIVE_CHANGE
public static final java.lang.String BLOCK_PERMISSIVE_CHANGE
Property name change fired when the Block Permissive Status changes. The fired event includes old value: previous permissive status. new value: new permissive status.- See Also:
- Constant Field Values
-
BLOCK_SPEED_CHANGE
public static final java.lang.String BLOCK_SPEED_CHANGE
Property name change fired when the Block Speed changes. The fired event includes old value: previous speed String. new value: new speed String.- See Also:
- Constant Field Values
-
BLOCK_CURVATURE_CHANGE
public static final java.lang.String BLOCK_CURVATURE_CHANGE
Property name change fired when the Block Curvature changes. The fired event includes old value: previous Block Curvature Constant. new value: new Block Curvature Constant.- See Also:
- Constant Field Values
-
BLOCK_LENGTH_CHANGE
public static final java.lang.String BLOCK_LENGTH_CHANGE
Property name change fired when the Block Length changes. The fired event includes old value: previous float length (mm). new value: new float length (mm).- See Also:
- Constant Field Values
-
-
Method Detail
-
toDebugString
public java.lang.String toDebugString()
Create a Debug String, this should only be used for debugging...- Returns:
- Block User name, System name, current state as string value.
-
setSensor
public boolean setSensor(java.lang.String pName)
Set the sensor by name. Fires propertyChange "OccupancySensorChange" when changed.- 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> s)
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.
- Parameters:
s
- Handle for Sensor.
-
getSensor
public Sensor getSensor()
Get the Block Occupancy Sensor.- Returns:
- Sensor if one attached to Block, may be null.
-
getNamedSensor
public NamedBeanHandle<Sensor> getNamedSensor()
-
setReporter
public void setReporter(Reporter reporter)
Set the Reporter that should provide the data value for this block. Fires propertyChange "BlockReporterChange" when changed.- Parameters:
reporter
- Reporter object to link, or null to clear- See Also:
Reporter
-
getReporter
public Reporter getReporter()
Retrieve the Reporter that is linked to this Block- Returns:
- linked Reporter object, or null if not linked
- See Also:
Reporter
-
setReportingCurrent
public void setReportingCurrent(boolean reportingCurrent)
Define if the Block's value should be populated from thecurrent report
or from thelast report
. Fires propertyChange "BlockReportingCurrent" when changed.- Parameters:
reportingCurrent
- true if to use current report; false if to use last report- See Also:
Reporter
-
isReportingCurrent
public boolean isReportingCurrent()
Determine if the Block's value is being populated from thecurrent report
or from thelast report
.- Returns:
- true if populated by
current report
; false if fromlast report
. - See Also:
Reporter
-
getState
public int getState()
Get the Block State. OBlocks may well return a combination of states, Blocks will return a single State.
-
addPath
public void addPath(@Nonnull Path p)
Add a Path to List of Paths.- Parameters:
p
- Path to add, not null.
-
removePath
public void removePath(Path p)
Remove a Path from the Block.- Parameters:
p
- Path to remove.
-
hasPath
public boolean hasPath(Path p)
Check if Block has a particular Path.- Parameters:
p
- Path to test against.- Returns:
- true if Block has the Path, else false.
-
getPaths
@Nonnull public java.util.List<Path> getPaths()
Get a copy of the list of Paths.- Returns:
- the paths or an empty list
-
setState
public void setState(int v)
Provide a general method for updating the report. Fires propertyChange "state" when called.
-
setValue
public void setValue(java.lang.Object value)
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.- Parameters:
value
- The new Object resident in this block, or null if none
-
getValue
public java.lang.Object getValue()
Get the Block Contents Value.- Returns:
- object with current value, could be null.
-
setDirection
public void setDirection(int direction)
Set Block Direction of Travel. Fires propertyChange "direction" when changed.- Parameters:
direction
- Path Constant form, seePath.java
-
getDirection
public int getDirection()
Get Block Direction of Travel.- Returns:
- direction in Path Constant form, see
Path.java
-
addBlockDenyList
public void addBlockDenyList(@Nonnull java.lang.String pName)
Add to the Block Deny List. The block deny list, is used by higher level code, to determine if traffic/trains should be allowed to enter from an attached block, the list only deals with blocks that access should be denied from.If we want to prevent traffic from following from this Block to another, then this Block must be added to the deny list of the other Block. By default no Block is barred, so traffic flow is bi-directional.
- Parameters:
pName
- name of the block to add, which must exist
-
addBlockDenyList
public void addBlockDenyList(Block blk)
-
removeBlockDenyList
public void removeBlockDenyList(java.lang.String blk)
-
removeBlockDenyList
public void removeBlockDenyList(Block blk)
-
getDeniedBlocks
public java.util.List<java.lang.String> getDeniedBlocks()
-
isBlockDenied
public boolean isBlockDenied(java.lang.String deny)
-
isBlockDenied
public boolean isBlockDenied(Block deny)
-
getPermissiveWorking
public boolean getPermissiveWorking()
Get if Block can have permissive working. Blocks default to non-permissive, i.e. false.- Returns:
- true if permissive, else false.
-
setPermissiveWorking
public void setPermissiveWorking(boolean w)
Set Block as permissive. Fires propertyChange "BlockPermissiveWorking" when changed.- Parameters:
w
- true permissive, false NOT permissive
-
getSpeedLimit
public float getSpeedLimit()
-
getBlockSpeed
public java.lang.String getBlockSpeed()
-
setBlockSpeedName
public void setBlockSpeedName(java.lang.String s)
Set the Block Speed Name.Does not perform name validity checking. Does not send Property Change Event.
- Parameters:
s
- new Speed Name String.
-
setBlockSpeed
public void setBlockSpeed(java.lang.String s) throws JmriException
Set the Block Speed, preferred method.Fires propertyChange "BlockSpeedChange" when changed.
- Parameters:
s
- Speed String- Throws:
JmriException
- if Value of requested block speed is not valid.
-
setCurvature
public void setCurvature(int c)
Set Block Curvature Constant. Valid values : Block.NONE, Block.GRADUAL, Block.TIGHT, Block.SEVERE Fires propertyChange "BlockCurvatureChange" when changed.- Parameters:
c
- Constant, e.g. Block.GRADUAL
-
getCurvature
public int getCurvature()
Get Block Curvature Constant. Defaults to Block.NONE- Returns:
- constant, e.g. Block.TIGHT
-
setLength
public void setLength(float l)
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.
- Parameters:
l
- length in millimeters
-
getLengthMm
public float getLengthMm()
Get Block Length in Millimetres. Default 0.0f.- Returns:
- length in mm.
-
getLengthCm
public float getLengthCm()
Get Block Length in Centimetres. Courtesy method using result from getLengthMm.- Returns:
- length in centimetres.
-
getLengthIn
public float getLengthIn()
Get Block Length in Inches. Courtesy method using result from getLengthMm.- Returns:
- length in inches.
-
equals
public boolean equals(java.lang.Object obj)
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 classAbstractNamedBean
- 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 classAbstractNamedBean
- Returns:
- hash code value is based on the system name.
-
resetCandidateEntrancePaths
void resetCandidateEntrancePaths()
-
setAsEntryBlockIfPossible
boolean setAsEntryBlockIfPossible(Block b)
-
handleSensorChange
void handleSensorChange(java.beans.PropertyChangeEvent e)
Handle change in sensor state.Defers real work to goingActive, goingInactive methods.
- Parameters:
e
- the event
-
goingUnknown
public void goingUnknown()
-
goingInconsistent
public void goingInconsistent()
-
handleReporterChange
void handleReporterChange(java.beans.PropertyChangeEvent e)
Handle change in Reporter value.- Parameters:
e
- PropertyChangeEvent
-
goingInactive
public void goingInactive()
Handles Block sensor going INACTIVE: this block is empty
-
goingActive
public void goingActive()
Handles Block sensor going ACTIVE: this block is now occupied, figure out from who and copy their value.
-
findFromPath
public Path findFromPath()
Find which path this Block became Active, without actually modifying the state of this block.(this is largely a copy of the 'Search' part of the logic from goingActive())
- Returns:
- the next path
-
setAllocated
public void setAllocated(java.lang.Boolean boo)
This allows the layout block to inform any listeners to the block that the higher level layout block has been set to "useExtraColor" which is an indication that it has been allocated to a section by the AutoDispatcher. The value set is not retained in any form by the block, it is purely to trigger a propertyChangeEvent.- Parameters:
boo
- Allocation status
-
getLocoAddress
public LocoAddress getLocoAddress(java.lang.String rep)
Parse a given string and return the LocoAddress value that is presumed stored within it based on this object's protocol. The Class Block implementation defers to its associated Reporter, if it exists.- Specified by:
getLocoAddress
in interfacePhysicalLocationReporter
- Parameters:
rep
- String to be parsed- Returns:
- LocoAddress address parsed from string, or null if this Block isn't associated with a Reporter, or is associated with a Reporter that is not also a PhysicalLocationReporter
-
getDirection
public PhysicalLocationReporter.Direction getDirection(java.lang.String rep)
Parses out a (possibly old) LnReporter-generated report string to extract the direction from within it based on this object's protocol. The Class Block implementation defers to its associated Reporter, if it exists.- Specified by:
getDirection
in interfacePhysicalLocationReporter
- Parameters:
rep
- String to be parsed- Returns:
- PhysicalLocationReporter.Direction direction parsed from string, or null if this Block isn't associated with a Reporter, or is associated with a Reporter that is not also a PhysicalLocationReporter
-
getPhysicalLocation
public PhysicalLocation getPhysicalLocation()
Return this Block's physical location, if it exists. Defers actual work to the helper methods in class PhysicalLocation.- Specified by:
getPhysicalLocation
in interfacePhysicalLocationReporter
- Returns:
- PhysicalLocation : this Block's location.
-
getPhysicalLocation
public PhysicalLocation getPhysicalLocation(java.lang.String s)
Return this Block's physical location, if it exists. Does not use the parameter s. Defers actual work to the helper methods in class PhysicalLocation- Specified by:
getPhysicalLocation
in interfacePhysicalLocationReporter
- Parameters:
s
- (this parameter is ignored)- Returns:
- PhysicalLocation : this Block's location.
-
vetoableChange
public void vetoableChange(java.beans.PropertyChangeEvent evt) throws java.beans.PropertyVetoException
Description copied from class:AbstractNamedBean
- Specified by:
vetoableChange
in interfaceNamedBean
- Overrides:
vetoableChange
in classAbstractNamedBean
- Throws:
java.beans.PropertyVetoException
-
getUsageReport
public java.util.List<NamedBeanUsageReport> getUsageReport(NamedBean bean)
Description copied from interface:NamedBean
Get a list of references for the specified bean.- Specified by:
getUsageReport
in interfaceNamedBean
- Parameters:
bean
- The bean to be checked.- Returns:
- a list of NamedBeanUsageReports or an empty ArrayList.
-
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 interfaceNamedBean
- Returns:
- a string of the bean type, eg Turnout, Sensor etc
-
-