001package jmri; 002 003/** 004 * Represent a single signal, either in {@link SignalHead} or {@link SignalMast} 005 * form. 006 * <p> 007 * This interface defines two bound parameters: 008 * <dl> 009 * <dt>Lit 010 * <dd>Whether the signal's lamps are lit or left dark. 011 * <p> 012 * This differs from the DARK color or all-off appearance. Lit is intended to 013 * allow you to extinguish a signal for approach lighting, while still allowing 014 * it to be set to a definite appearance or aspect for e.g. display on a panel 015 * or evaluation in higher level logic. 016 * <dt>Held 017 * <dd>Whether the signal's lamps should be forced to a specific appearance or 018 * aspect, e.g. RED or STOP, in higher-level logic. 019 * <p> 020 * For use in signaling systems, this is a convenient way of storing whether a 021 * higher-level of control (e.g. non-vital system or dispatcher) has "held" the 022 * signal at stop. It does not effect how this signal actually works; any 023 * appearance can be set and will be displayed even when "held" is set. 024 * </dl> 025 * <p> 026 * The following can be relied on: 027 * <ul> 028 * <li>isCleared() && isAtStop() is false: they are disjoint. 029 * <li>isAtStop() && isShowingRestricting() is false: they are disjoint. 030 * <li>isShowingRestricting() && isCleared() is false: they are 031 * disjoint. 032 * <li>isAtStop() || isShowingRestricting() || isCleared() is usually true, but 033 * it can be false; the three methods do not cover all cases 034 * </ul> 035 * <hr> 036 * This file is part of JMRI. 037 * <p> 038 * JMRI is free software; you can redistribute it and/or modify it under the 039 * terms of version 2 of the GNU General Public License as published by the Free 040 * Software Foundation. See the "COPYING" file for a copy of this license. 041 * <p> 042 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 043 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 044 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 045 * 046 * @author Bob Jacobsen Copyright (C) 2002, 2008, 2017 047 */ 048public interface Signal extends NamedBean { 049 050 /** 051 * Determine whether this signal shows an aspect or appearance that allows 052 * travel past it, e.g. it's "been cleared". This might be a yellow or green 053 * appearance, or an Approach or Clear aspect. 054 * 055 * @return true if the signal is showing a clear indication; false otherwise 056 */ 057 boolean isCleared(); 058 059 /** 060 * Determine whether this signal shows an aspect or appearance that allows 061 * travel past it only at restricted speed. This might be a flashing red 062 * appearance, or a Restricting aspect. 063 * 064 * @return true if the signal is showing a restricting indication; false 065 * otherwise 066 */ 067 boolean isShowingRestricting(); 068 069 /** 070 * Determine whether this signal shows an aspect or appearance that forbid 071 * travel past it. This might be a red appearance, or a Stop aspect. 072 * Stop-and-Proceed or Restricting would return false here. 073 * 074 * @return true if the signal is showing a stop indication; false otherwise 075 */ 076 boolean isAtStop(); 077 078 /** 079 * Get whether the signal is lit or dark. Changes to this value can be 080 * listened to using the {@literal Lit} property. 081 * 082 * @return true if lit; false if dark 083 */ 084 boolean getLit(); 085 086 void setLit(boolean newLit); 087 088 /** 089 * Get whether the signal is held. Changes to this value can be listened to 090 * using the {@literal Held} property. It controls what mechanisms can 091 * control the signal's appearance. The actual semantics are defined by 092 * those external mechanisms. 093 * 094 * @return true if held; false otherwise 095 */ 096 boolean getHeld(); 097 098 void setHeld(boolean newHeld); 099 100}