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() &amp;&amp; isAtStop() is false: they are disjoint.
029 * <li>isAtStop() &amp;&amp; isShowingRestricting() is false: they are disjoint.
030 * <li>isShowingRestricting() &amp;&amp; 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}