jmri
Class Block

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

All Implemented Interfaces:

Serializable, NamedBean

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.

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 interface jmri.NamedBean

INCONSISTENT, UNKNOWN

Constructor Summary

Block(String systemName)

Block(String systemName, String userName)

Method Summary

void	addPath(Path p)
int	getCurvature()
int	getDirection()
float	getLengthCm()
float	getLengthIn()
float	getLengthMm()
List<Path>	getPaths() Get a copy of the list of Paths
Sensor	getSensor()
int	getState() Provide generic access to internal state.
Object	getValue()
void	removePath(Path p)
void	setCurvature(int c)
void	setDirection(int direction)
void	setLength(float l)
void	setSensor(Sensor sensor)
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, dispose, firePropertyChange, getComment, getNumPropertyChangeListeners, getSystemName, getUserName, removePropertyChangeListener, setComment, setUserName

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

getSensor

public Sensor getSensor()

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

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