jmri
Class Section

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 one or more trains 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 two 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 sufficient length may be allocated to more than one train provided the trains are travelling in the same direction. There must be at least one block between trains travelling in the same direction in a 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.

Author:

Dave Duchamp Copyright (C) 2008

See Also:

Serialized Form

Field Summary

static int	FORWARD
static int	FREE
static int	OCCUPIED Constants representing the occupancy of the Section.
static int	REVERSE
static int	UNKNOWN Constants representing the state of the Section.
static int	UNOCCUPIED

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.
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)
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";
Block	getNextBlock()
int	getOccupancy() Query the occupancy of a section
Sensor	getReverseBlockingSensor()
String	getReverseBlockingSensorName()
List<EntryPoint>	getReverseEntryPointList()
Sensor	getReverseStoppingSensor()
String	getReverseStoppingSensorName()
int	getState() Query the state of 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)
Sensor	setForwardBlockingSensorName(String forwardSensor)
Sensor	setForwardStoppingSensorName(String forwardSensor)
Sensor	setReverseBlockingSensorName(String reverseSensor)
Sensor	setReverseStoppingSensorName(String reverseSensor)
void	setState(int state) Set the state of the Section
String	validate(LayoutEditor lePanel) Validate the Section.

Methods inherited from class jmri.implementation.AbstractNamedBean

addPropertyChangeListener, dispose, firePropertyChange, getComment, getDisplayName, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getSystemName, getUserName, removePropertyChangeListener, setComment, setProperty, setUserName

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

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)

getBlockList

public ArrayList<Block> getBlockList()

Get a Copy of this Section's Block List

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.