jmri
Class Block

Show UML class diagram

java.lang.Object
  jmri.implementation.AbstractNamedBean
      jmri.Block

All Implemented Interfaces:

Serializable, NamedBean, PhysicalLocationReporter

Direct Known Subclasses:

OBlock

public class Block
extends AbstractNamedBean
implements PhysicalLocationReporter

Represents a particular piece of track, more informally a "Block". As trains move around the layout, a set of Block objects 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 (at least in this implementation) corresponds exactly to the track covered by a single sensor. That should be generalized in the future.

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.

There is no functional requirement for a type letter in the System Name, but by convention we use '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".

The direction of a Block is set from the direction of the incoming train. When a train is found to be coming in on a particular Path, that Path's getFromBlockDirection becomes the direction of the train in this Block.

Issues:

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

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.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface jmri.PhysicalLocationReporter

PhysicalLocationReporter.Direction

Field Summary

(package private) ArrayList<NamedBeanHandle<Block>>	blockDenyList
static int	GRADUAL
(package private) static org.slf4j.Logger	log
static int	NONE
static int	OCCUPIED
(package private) ArrayList<Path>	paths
static int	SEVERE
static int	TIGHT
static int	UNOCCUPIED

Fields inherited from class jmri.implementation.AbstractNamedBean

mSystemName, mUserName

Fields inherited from interface jmri.NamedBean

INCONSISTENT, UNKNOWN

Constructor Summary

Block(String systemName)

Block(String systemName, String userName)

Method Summary

void	addBlockDenyList(Block blk)
void	addBlockDenyList(String pName) 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.
void	addPath(Path p)
Path	findFromPath() Find which path this Block became Active, without actually modifying the state of this block.
String	getBlockSpeed()
int	getCurvature()
List<String>	getDeniedBlocks()
int	getDirection()
PhysicalLocationReporter.Direction	getDirection(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()
float	getLengthIn()
float	getLengthMm()
LocoAddress	getLocoAddress(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()
List<Path>	getPaths() Get a copy of the list of Paths
boolean	getPermissiveWorking()
PhysicalLocation	getPhysicalLocation() Return this Block's physical location, if it exists.
PhysicalLocation	getPhysicalLocation(String s) Return this Block's physical location, if it exists.
Reporter	getReporter() Retrieve the Reporter that is linked to this Block
Sensor	getSensor()
float	getSpeedLimit()
int	getState() Provide generic access to internal state.
Object	getValue()
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 empty
(package private) void	handleReporterChange(PropertyChangeEvent e) Handle change in Reporter value.
(package private) void	handleSensorChange(PropertyChangeEvent e) Handle change in sensor state.
boolean	isBlockDenied(Block deny)
boolean	isBlockDenied(String deny)
boolean	isReportingCurrent() Determine if the Block's value is being populated from the current report or from the last report.
void	removeBlockDenyList(Block blk)
void	removeBlockDenyList(String blk)
void	removePath(Path p)
void	setBlockSpeed(String s)
void	setCurvature(int c)
void	setDirection(int direction)
void	setLength(float l)
void	setNamedSensor(NamedBeanHandle<Sensor> s)
void	setPermissiveWorking(boolean w)
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 the current report or from the last report.
boolean	setSensor(String pName)
void	setState(int v) Provide a general method for updating the report.
void	setValue(Object value) Set the value retained by this Block.

Methods inherited from class jmri.implementation.AbstractNamedBean

addPropertyChangeListener, addPropertyChangeListener, dispose, firePropertyChange, getComment, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getPropertyChangeListeners, getPropertyKeys, getSystemName, getUserName, removeProperty, removePropertyChangeListener, setComment, setProperty, setUserName, updateListenerRef

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

OCCUPIED

public static final int OCCUPIED

See Also:

Constant Field Values

UNOCCUPIED

public static final int UNOCCUPIED

See Also:

Constant Field Values

NONE

public static final int NONE

See Also:

Constant Field Values

GRADUAL

public static final int GRADUAL

See Also:

Constant Field Values

TIGHT

public static final int TIGHT

See Also:

Constant Field Values

SEVERE

public static final int SEVERE

See Also:

Constant Field Values

paths

ArrayList<Path> paths

blockDenyList

ArrayList<NamedBeanHandle<Block>> blockDenyList

log

static org.slf4j.Logger log

Constructor Detail

Block

public Block(String systemName)

Block

public Block(String systemName,
             String userName)

Method Detail

setSensor

public boolean setSensor(String pName)

setNamedSensor

public void setNamedSensor(NamedBeanHandle<Sensor> s)

getSensor

public Sensor getSensor()

getNamedSensor

public NamedBeanHandle<Sensor> getNamedSensor()

setReporter

public void setReporter(Reporter reporter)

Set the Reporter that should provide the data value for this block.

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 the current report or from the last report.

Parameters:

reportingCurrent -

See Also:

Reporter

isReportingCurrent

public boolean isReportingCurrent()

Determine if the Block's value is being populated from the current report or from the last report.

Returns:

true if populated by current report; false if from last report.

See Also:

Reporter

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 provided to make Jython script access easier to read.

Specified by:

getState in interface NamedBean

addPath

public void addPath(Path p)

removePath

public void removePath(Path p)

getPaths

public List<Path> getPaths()

Get a copy of the list of Paths

setState

public void setState(int v)

Provide a general method for updating the report.

Specified by:

setState in interface NamedBean

setValue

public void setValue(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.

Parameters:

value - The new Object resident in this block, or null if none.

getValue

public Object getValue()

setDirection

public void setDirection(int direction)

getDirection

public int getDirection()

addBlockDenyList

public void addBlockDenyList(String pName)

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.

addBlockDenyList

public void addBlockDenyList(Block blk)

removeBlockDenyList

public void removeBlockDenyList(String blk)

removeBlockDenyList

public void removeBlockDenyList(Block blk)

getDeniedBlocks

public List<String> getDeniedBlocks()

isBlockDenied

public boolean isBlockDenied(String deny)

isBlockDenied

public boolean isBlockDenied(Block deny)

getPermissiveWorking

public boolean getPermissiveWorking()

setPermissiveWorking

public void setPermissiveWorking(boolean w)

getSpeedLimit

public float getSpeedLimit()

getBlockSpeed

public String getBlockSpeed()

setBlockSpeed

public void setBlockSpeed(String s)
                   throws JmriException

Throws:

JmriException

setCurvature

public void setCurvature(int c)

getCurvature

public int getCurvature()

setLength

public void setLength(float l)

getLengthMm

public float getLengthMm()

getLengthCm

public float getLengthCm()

getLengthIn

public float getLengthIn()

handleSensorChange

void handleSensorChange(PropertyChangeEvent e)

Handle change in sensor state.

Defers real work to goingActive, goingInactive methods

handleReporterChange

void handleReporterChange(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())

getLocoAddress

public LocoAddress getLocoAddress(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 implementationd defers to its associated Reporter, if it exists.

Specified by:

getLocoAddress in interface PhysicalLocationReporter

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(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 implementationd defers to its associated Reporter, if it exists.

Specified by:

getDirection in interface PhysicalLocationReporter

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

Returns:

PhysicalLocation : this Block's location.

getPhysicalLocation

public PhysicalLocation getPhysicalLocation(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 interface PhysicalLocationReporter

Parameters:

s - (this parameter is ignored)

Returns:

PhysicalLocation : this Block's location.