jmri
Class Section

Show UML class diagram

java.lang.Object
  jmri.implementation.AbstractNamedBean
      jmri.Section

All Implemented Interfaces:

Serializable, NamedBean

public class Section
extends AbstractNamedBean
implements Serializable

Sections represent a group of one or more connected Blocks that may be allocated to a train travelling in a given direction.

A Block may be in multiple Sections. All Blocks contained in a given section must be unique. Blocks are kept in order--the first block is connected to the second, the second is connected to the third, etc.

A Block in a Section must be connected to the Block before it (if there is one) and to the Block after it (if there is one), but may not be connected to any other Block in the Section. This restriction is enforced when a Section is created, and checked when a Section is loaded from disk.

A Section has a "direction" defined by the sequence in which Blocks are added to the Section. A train may run through a Section in either the forward direction (from first block to last block) or reverse direction (from last block to first block).

A Section has one or more EntryPoints. Each EntryPoint is a Path of one of the Blocks in the Section that defines a connection to a Block outside of the Section. EntryPoints are grouped into two lists: "forwardEntryPoints" - entry through which will result in a train travelling in the "forward" direction "reverseEntryPoints" - entry through which will result in a train travelling in the "reverse" direction Note that "forwardEntryPoints" are also reverse exit points, and vice versa.

A Section has one of the following states" FREE - available for allocation by a dispatcher FORWARD - allocated for travel in the forward direction REVERSE - allocated for travel in the reverse direction

A Section has an occupancy. A Section is OCCUPIED if any of its Blocks is OCCUPIED. A Section is UNOCCUPIED if all of its Blocks are UNOCCUPIED

A Section of may be allocated to only one train at a time, even if the trains are travelling in the same direction. If a Section has sufficient space for multiple trains travelling in the same direction it should be broken up into multiple Sections so the trains can follow each other through the original Section.

A Section may not contain any reverse loops. The track that is reversed in a reverse loop must be in a separate Section.

Each Section optionally carries two direction sensors, one for the forward direction and one for the reverse direction. These sensors force signals for travel in their respective directions to "RED" when they are active. When the Section is free, both the sensors are Active. These internal sensors follow the state of the Section, permitting signals to function normally in the direction of allocation.

Each Section optionally carries two stopping sensors, one for the forward direction and one for the reverse direction. These sensors change to active when a train traversing the Section triggers its sensing device. Stopping sensors are physical layout sensors, and may be either point sensors or occupancy sensors for short blocks at the end of the Section. A stopping sensor is used during automatic running to stop a train that has reached the end of its allocated Section. This is needed, for example, to allow a train to enter a passing siding and clear the track behind it. When not running automatically, these sensors may be used to light panel lights to notify the dispatcher that the train has reached the end of the Section.

This Section implementation provides for delayed initialization of blocks and direction sensors to be independent of order of items in panel files.

This file is part of JMRI.

JMRI is open source software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

See Also:

Serialized Form

Field Summary

static int	DYNAMICADHOC
static int	FORWARD
static int	FREE
(package private) static org.slf4j.Logger	log
protected NamedBeanHandleManager	nbhm
static int	OCCUPIED Constants representing the occupancy of the Section.
static int	REVERSE
(package private) int	sectionType
static int	SIGNALMASTLOGIC
(package private) String	tempSensorName
static int	UNKNOWN Constants representing the state of the Section.
static int	UNOCCUPIED
static int	USERDEFINED

Fields inherited from class jmri.implementation.AbstractNamedBean

mSystemName, mUserName

Fields inherited from interface jmri.NamedBean

INCONSISTENT

Constructor Summary

Section(String systemName)

Section(String systemName, String userName)

Method Summary

boolean	addBlock(Block b) Add a Block to the Section Block and sequence number must be unique within the Section.
void	addToForwardList(EntryPoint ep) Access methods for EntryPoints within the Section
void	addToReverseList(EntryPoint ep)
boolean	checkSignals(JmriJFrame frame, LayoutEditor panel) Checks that there are Signal Heads at all Entry Points to this Section.
void	clearNameInUnoccupiedBlocks() This function clears the string in the memories associated with unoccupied blocks in this section.
boolean	connectsToBlock(Block b)
boolean	containsBlock(Block b)
void	delayedAddBlock(String blockName)
void	delayedSetForwardBlockingSensorName(String forwardSensor)
void	delayedSetForwardStoppingSensorName(String forwardSensor)
void	delayedSetReverseBlockingSensorName(String reverseSensor)
void	delayedSetReverseStoppingSensorName(String reverseSensor)
int	getActualLength() Gets the actual length of the Seciton in mm without any scaling
String	getBeginBlockName() Access methods for beginning and ending block names
Block	getBlockBySequenceNumber(int seqNumber) Get Block by its Sequence number in the Block list Blocks are numbered 0 to size-1;
ArrayList<Block>	getBlockList() Get a Copy of this Section's Block List
int	getBlockSequenceNumber(Block b) Get the sequence number of a Block Returns -1 if Block is not in the Section
String	getEndBlockName()
Block	getEntryBlock()
EntryPoint	getEntryPointFromBlock(Block b, int dir) Returns the EntryPoint for entry from specified Block for travel in specified direction Returns 'null' if not found.
EntryPoint	getEntryPointFromSection(Section s, int dir) Returns the EntryPoint for entry from specified Section for travel in specified direction Returns 'null' if not found.
List<EntryPoint>	getEntryPointList()
EntryPoint	getExitPointToBlock(Block b, int dir) Returns the EntryPoint for exit to specified Block for travel in specified direction Returns 'null' if not found.
EntryPoint	getExitPointToSection(Section s, int dir) Returns the EntryPoint for exit to specified Section for travel in specified direction Returns 'null' if not found.
Sensor	getForwardBlockingSensor()
String	getForwardBlockingSensorName() Access methods for forward and reverse blocking sensors The set methods return a Sensor object if successful, or else they return "null";
List<EntryPoint>	getForwardEntryPointList()
Sensor	getForwardStoppingSensor()
String	getForwardStoppingSensorName() Access methods for forward and reverse stopping sensors The set methods return a Sensor object if successful, or else they return "null";
float	getLengthF(boolean meters, int scale) Gets length of Section in scale feet or scale meters.
int	getLengthI(boolean meters, int scale)
Block	getNextBlock()
int	getNumBlocks() Gets the number of Blocks in this Section
int	getOccupancy() Query the occupancy of a section
Sensor	getReverseBlockingSensor()
String	getReverseBlockingSensorName()
List<EntryPoint>	getReverseEntryPointList()
Sensor	getReverseStoppingSensor()
String	getReverseStoppingSensorName()
int	getSectionType()
int	getState() Query the state of the Section
(package private) void	handleBlockChange(PropertyChangeEvent e) Handle change in occupancy of a Block in the Section
boolean	isForwardEntryPoint(EntryPoint ep)
boolean	isReverseEntryPoint(EntryPoint ep)
int	placeDirectionSensors(LayoutEditor panel) Places direction sensors in SSL for all Signal Heads in this Section if the Sensors are not already present in the SSL.
void	removeAllBlocksFromSection() Remove all Blocks, Block Listeners, and Entry Points
void	removeEntryPoint(EntryPoint ep)
void	setAlternateColor(boolean set) This function sets/resets the display to use alternate color for unoccupied blocks in this section.
void	setAlternateColorFromActiveBlock(boolean set) This function sets/resets the display to use alternate color for unoccupied blocks in this section.
Sensor	setForwardBlockingSensorName(String forwardSensor)
Sensor	setForwardStoppingSensorName(String forwardSensor)
void	setNameFromActiveBlock(Object value)
void	setNameInBlocks(Object value) This function sets an object in the memories associated with blocks in this section.
void	setNameInBlocks(String name) This function sets a string in the memories associated with blocks in this section.
Sensor	setReverseBlockingSensorName(String reverseSensor)
Sensor	setReverseStoppingSensorName(String reverseSensor)
void	setSectionType(int type)
void	setState(int state) Set the state of the Section
void	suppressNameUpdate(boolean set) This function suppresses the update of a memory variable when a block goes to unoccupied, so the text set above doesn't get wiped out.
String	validate(LayoutEditor lePanel) Validate the Section.

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

UNKNOWN

public static final int UNKNOWN

Constants representing the state of the Section. A Section can be either FREE - available for allocation, FORWARD - allocated for travel in the forward direction, or REVERSE - allocated for travel in the REVERSE direction.

See Also:

Constant Field Values

FREE

public static final int FREE

See Also:

Constant Field Values

FORWARD

public static final int FORWARD

See Also:

Constant Field Values

REVERSE

public static final int REVERSE

See Also:

Constant Field Values

OCCUPIED

public static final int OCCUPIED

Constants representing the occupancy of the Section. A Section is OCCUPIED if any of its Blocks are OCCUPIED. If all of its Blocks are UNOCCUPIED, a Section is UNOCCUPIED.

See Also:

Constant Field Values

UNOCCUPIED

public static final int UNOCCUPIED

See Also:

Constant Field Values

nbhm

protected NamedBeanHandleManager nbhm

tempSensorName

String tempSensorName

USERDEFINED

public static final int USERDEFINED

See Also:

Constant Field Values

SIGNALMASTLOGIC

public static final int SIGNALMASTLOGIC

See Also:

Constant Field Values

DYNAMICADHOC

public static final int DYNAMICADHOC

See Also:

Constant Field Values

sectionType

int sectionType

log

static final org.slf4j.Logger log

Constructor Detail

Section

public Section(String systemName,
               String userName)

Section

public Section(String systemName)

Method Detail

getState

public int getState()

Query the state of the Section

Specified by:

getState in interface NamedBean

setState

public void setState(int state)

Set the state of the Section

Specified by:

setState in interface NamedBean

getOccupancy

public int getOccupancy()

Query the occupancy of a section

getForwardBlockingSensorName

public String getForwardBlockingSensorName()

Access methods for forward and reverse blocking sensors The set methods return a Sensor object if successful, or else they return "null";

getForwardBlockingSensor

public Sensor getForwardBlockingSensor()

setForwardBlockingSensorName

public Sensor setForwardBlockingSensorName(String forwardSensor)

delayedSetForwardBlockingSensorName

public void delayedSetForwardBlockingSensorName(String forwardSensor)

getReverseBlockingSensorName

public String getReverseBlockingSensorName()

setReverseBlockingSensorName

public Sensor setReverseBlockingSensorName(String reverseSensor)

delayedSetReverseBlockingSensorName

public void delayedSetReverseBlockingSensorName(String reverseSensor)

getReverseBlockingSensor

public Sensor getReverseBlockingSensor()

getForwardStoppingSensorName

public String getForwardStoppingSensorName()

Access methods for forward and reverse stopping sensors The set methods return a Sensor object if successful, or else they return "null";

getForwardStoppingSensor

public Sensor getForwardStoppingSensor()

setForwardStoppingSensorName

public Sensor setForwardStoppingSensorName(String forwardSensor)

delayedSetForwardStoppingSensorName

public void delayedSetForwardStoppingSensorName(String forwardSensor)

getReverseStoppingSensorName

public String getReverseStoppingSensorName()

setReverseStoppingSensorName

public Sensor setReverseStoppingSensorName(String reverseSensor)

delayedSetReverseStoppingSensorName

public void delayedSetReverseStoppingSensorName(String reverseSensor)

getReverseStoppingSensor

public Sensor getReverseStoppingSensor()

addBlock

public boolean addBlock(Block b)

Add a Block to the Section Block and sequence number must be unique within the Section. Block sequence numnbers are set automatically as blocks are added. Returns "true" if Block was added. Returns "false" if Block does not connect to the current Block, or the Block is not unique.

delayedAddBlock

public void delayedAddBlock(String blockName)

handleBlockChange

void handleBlockChange(PropertyChangeEvent e)

Handle change in occupancy of a Block in the Section

getBlockList

public ArrayList<Block> getBlockList()

Get a Copy of this Section's Block List

getNumBlocks

public int getNumBlocks()

Gets the number of Blocks in this Section

getLengthF

public float getLengthF(boolean meters,
                        int scale)

Gets length of Section in scale feet or scale meters. Length of the Section is calculated by summing the lengths of all Blocks in the section. If all Block lengths have not been entered, length will not be correct. If meters = true, units of returned length is scale meters If meters = false, units of returned length is scale feet scale = layout scale according to definitions in jmri.Scale.java

getLengthI

public int getLengthI(boolean meters,
                      int scale)

getActualLength

public int getActualLength()

Gets the actual length of the Seciton in mm without any scaling

getBlockBySequenceNumber

public Block getBlockBySequenceNumber(int seqNumber)

Get Block by its Sequence number in the Block list Blocks are numbered 0 to size-1;

getBlockSequenceNumber

public int getBlockSequenceNumber(Block b)

Get the sequence number of a Block Returns -1 if Block is not in the Section

removeAllBlocksFromSection

public void removeAllBlocksFromSection()

Remove all Blocks, Block Listeners, and Entry Points

getEntryBlock

public Block getEntryBlock()

getNextBlock

public Block getNextBlock()

containsBlock

public boolean containsBlock(Block b)

connectsToBlock

public boolean connectsToBlock(Block b)

getBeginBlockName

public String getBeginBlockName()

Access methods for beginning and ending block names

getEndBlockName

public String getEndBlockName()

addToForwardList

public void addToForwardList(EntryPoint ep)

Access methods for EntryPoints within the Section

addToReverseList

public void addToReverseList(EntryPoint ep)

removeEntryPoint

public void removeEntryPoint(EntryPoint ep)

getForwardEntryPointList

public List<EntryPoint> getForwardEntryPointList()

getReverseEntryPointList

public List<EntryPoint> getReverseEntryPointList()

getEntryPointList

public List<EntryPoint> getEntryPointList()

isForwardEntryPoint

public boolean isForwardEntryPoint(EntryPoint ep)

isReverseEntryPoint

public boolean isReverseEntryPoint(EntryPoint ep)

getEntryPointFromSection

public EntryPoint getEntryPointFromSection(Section s,
                                           int dir)

Returns the EntryPoint for entry from specified Section for travel in specified direction Returns 'null' if not found.

getExitPointToSection

public EntryPoint getExitPointToSection(Section s,
                                        int dir)

Returns the EntryPoint for exit to specified Section for travel in specified direction Returns 'null' if not found.

getEntryPointFromBlock

public EntryPoint getEntryPointFromBlock(Block b,
                                         int dir)

Returns the EntryPoint for entry from specified Block for travel in specified direction Returns 'null' if not found.

getExitPointToBlock

public EntryPoint getExitPointToBlock(Block b,
                                      int dir)

Returns the EntryPoint for exit to specified Block for travel in specified direction Returns 'null' if not found.

placeDirectionSensors

public int placeDirectionSensors(LayoutEditor panel)

Places direction sensors in SSL for all Signal Heads in this Section if the Sensors are not already present in the SSL. Only anchor point block boundaries that have assigned signals are considered. Only turnouts that have assigned signals are considered. Only level crossings that have assigned signals are considered. Turnouts and anchor points without signals are counted, and reported in warning messages during this procedure, if there are any missing signals. If this method has trouble, an error message is placed in the log describing the trouble. If a direction sensor has not been defined for this Section, a message to that effect is issued to the log, and an error count of 1 is returned. Returns an an error count of 0, if no errors occurred.

checkSignals

public boolean checkSignals(JmriJFrame frame,
                            LayoutEditor panel)

Checks that there are Signal Heads at all Entry Points to this Section. This method will warn if it finds unsignalled internal turnouts, but will continue checking. Unsignalled entry points except for those at unsignalled internal turnouts will be considered errors, and will be reported to the user. This method stops searching when it find the first missing Signal Head. Returns 'true' if successful, 'false' otherwise.

validate

public String validate(LayoutEditor lePanel)

Validate the Section. This checks block connectivity, warns of redundant EntryPoints, and otherwise checks internal consistency of the Section. An appropriate error message is logged if a problem is found. This method assumes that Block Paths are correctly initialized. If a Layout Editor panel is available, lePanel!=null, the initialization of Blocks is checked. Returns an empty string "", if everything checks out. Returns a string describing the error if an error is found.

setAlternateColor

public void setAlternateColor(boolean set)

This function sets/resets the display to use alternate color for unoccupied blocks in this section. If 'set' is true, the alternate unoccupied color will be used. If 'set' is false, the unoccupied color will be used. If Layout Editor panel is not present, Layout Blocks will not be present, and nothing will be set.

setAlternateColorFromActiveBlock

public void setAlternateColorFromActiveBlock(boolean set)

This function sets/resets the display to use alternate color for unoccupied blocks in this section. If the section already contains an active block, then the alternative colour will be set from the active block, if no active block is found or we are clearing the alternative colour then all the blocks in the section will be set. If 'set' is true, the alternate unoccupied color will be used. If 'set' is false, the unoccupied color will be used. If Layout Editor panel is not present, Layout Blocks will not be present, and nothing will be set.

setNameInBlocks

public void setNameInBlocks(String name)

This function sets a string in the memories associated with blocks in this section. If Layout Editor panel is not present, Layout Blocks will not be present, and nothing will be set.

setNameInBlocks

public void setNameInBlocks(Object value)

This function sets an object in the memories associated with blocks in this section. If Layout Editor panel is not present, Layout Blocks will not be present, and nothing will be set.

setNameFromActiveBlock

public void setNameFromActiveBlock(Object value)

clearNameInUnoccupiedBlocks

public void clearNameInUnoccupiedBlocks()

This function clears the string in the memories associated with unoccupied blocks in this section. If Layout Editor panel is not present, Layout Blocks will not be present, and nothing will be set.

suppressNameUpdate

public void suppressNameUpdate(boolean set)

This function suppresses the update of a memory variable when a block goes to unoccupied, so the text set above doesn't get wiped out.

setSectionType

public void setSectionType(int type)

getSectionType

public int getSectionType()