jmri
Class Block

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

All Implemented Interfaces:

Serializable, NamedBean

Direct Known Subclasses:

OBlock

public class Block
extends AbstractNamedBean

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.

Author:

Bob Jacobsen Copyright (C) 2006, 2008, Dave Duchamp Copywright (C) 2009

See Also:

Serialized Form

Field Summary

static int	GRADUAL
static int	NONE
static int	OCCUPIED
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	addPath(Path p)
String	getBlockSpeed()
int	getCurvature()
int	getDirection()
float	getLengthCm()
float	getLengthIn()
float	getLengthMm()
NamedBeanHandle<Sensor>	getNamedSensor()
List<Path>	getPaths() Get a copy of the list of Paths
boolean	getPermissiveWorking()
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()
int	getWorkingDirection()
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
boolean	isReportingCurrent() Determine if the Block's value is being populated from the current report or from the last report.
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.
void	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.
void	setWorkingDirection(int w)

Methods inherited from class jmri.implementation.AbstractNamedBean

addPropertyChangeListener, addPropertyChangeListener, dispose, firePropertyChange, getComment, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getPropertyChangeListeners, getPropertyKeys, getSystemName, getUserName, 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

Constructor Detail

Block

public Block(String systemName)

Block

public Block(String systemName,
             String userName)

Method Detail

setSensor

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

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.

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

getWorkingDirection

public int getWorkingDirection()

setWorkingDirection

public void setWorkingDirection(int w)

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

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.