001package jmri;
002
003import java.util.Vector;
004import javax.annotation.CheckForNull;
005import javax.annotation.Nonnull;
006
007/**
008 * Represent a signal mast. A signal mast is one or more signal heads that are
009 * treated as a single signal. (Imagine several heads attached to a single mast,
010 * though other implementations are possible)
011 * <p>
012 * A mast presents an Aspect, as that's a composite of the appearance(s) of the
013 * entire signal.
014 * <p>
015 * This class has three bound parameters:
016 * <DL>
017 * <DT>Aspect<DD>The specific aspect being shown.
018 * <p>
019 * Aspects are named by a user defined String name.
020 * <DT>Lit<DD>Whether the mast's lamps are lit or left dark.
021 * This differs from the DARK color defined for the appearance parameter, in
022 * that it's independent of that. Lit is intended to allow you to extinguish a
023 * signal mast for approach lighting, while still allowing its color to be set
024 * to a definite value for e.g. display on a panel or evaluation in higher level
025 * logic.
026 * <DT>Held<DD>Whether the mast's lamps should be forced to a specific aspect,
027 * e.g. Stop, in higher-level logic.
028 * <p>
029 * For use in signaling systems, this is a convenient way of storing whether a
030 * higher-level of control (e.g. non-vital system or dispatcher) has "held" the
031 * signal at stop. It does not effect how this signal mast actually works; any
032 * appearance can be set and will be displayed even when "held" is set.
033 * </dl>
034 * The integer state (getState(), setState()) is the index of the current aspect
035 * in the list of all defined aspects.
036 * <hr>
037 * This file is part of JMRI.
038 * <p>
039 * JMRI is free software; you can redistribute it and/or modify it under the
040 * terms of version 2 of the GNU General Public License as published by the Free
041 * Software Foundation. See the "COPYING" file for a copy of this license.
042 * <p>
043 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
044 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
045 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
046 *
047 * @author Bob Jacobsen Copyright (C) 2002, 2008
048 * @author Pete Cressman Copyright (C) 2009
049 */
050public interface SignalMast extends Signal {
051
052    /**
053     * Constant property for aspect.
054     */
055    String PROPERTY_ASPECT = "Aspect";
056
057    /**
058     * Constant property for permissive SML disabled.
059     */
060    String PROPERTY_PERMISSIVE_SML_DISABLED = "PermissiveSmlDisabled";
061
062    /**
063     * Constant property for aspect disabled.
064     */
065    String PROPERTY_ASPECT_DISABLED = "aspectDisabled";
066
067    /**
068     * Constant for property aspect enabled.
069     */
070    String PROPERTY_ASPECT_ENABLED = "aspectEnabled";
071
072    /**
073     * Set aspect to a valid name in the current signal system definition.
074     *
075     * @param aspect the new aspect shown
076     * @throws IllegalArgumentException if not a valid aspect name
077     */
078    void setAspect(@Nonnull String aspect);
079
080    /**
081     * Get current aspect name. Changes to this property can be listened to
082     * using the property {@literal Aspect}.
083     *
084     * @return the current aspect or null if not set
085     */
086    @CheckForNull
087    String getAspect();
088
089    /**
090     * Get an alphabetically sorted list of valid aspects that have not been disabled.
091     *
092     * @return sorted list of valid aspects; may be empty
093     */
094    @Nonnull
095    Vector<String> getValidAspects();
096
097    SignalSystem getSignalSystem();
098
099    SignalAppearanceMap getAppearanceMap();
100
101    /**
102     * Set the specific mast type for this mast.
103     * This is the
104     * type that appears in the SystemName and filename, i.e. "SL-3-high"
105     * for the
106     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
107     * definition.
108     * @param type mast type.
109     */
110    void setMastType(@Nonnull String type);
111
112    /**
113     * Get the specific mast type for this mast.
114     * This is the
115     * type that appears in the SystemName and filename, i.e. "SL-3-high"
116     * for the
117     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
118     * definition.
119     * @return mast type.
120     */
121    String getMastType();
122
123    /**
124     * Get if signal mast is lit or dark. Changes to this property can be
125     * listened to using the property {@literal Lit}.
126     *
127     * @return true if lit; false if dark
128     */
129    @Override
130    boolean getLit();
131
132    @Override
133    void setLit(boolean newLit);
134
135    /**
136     * Get the held state of the signal mast. It controls what mechanisms can
137     * control the mast's appearance. The actual semantics are defined by those
138     * external mechanisms. Changes to this property can be listened to using
139     * the property {@literal Held}.
140     *
141     * @return true if held; false otherwise
142     */
143    @Override
144    boolean getHeld();
145
146    @Override
147    void setHeld(boolean newHeld);
148
149    /**
150     * Determine if the permissive SML logic should be disabled.  The default will be
151     * false which means that automatic permissive processing is allowed.  Prototypical
152     * CTC designs frequently require an additional action, such as Call-On, to enable permissive aspects.
153     * @return true if permissive SML is disabled.
154     */
155    boolean isPermissiveSmlDisabled();
156
157    void setPermissiveSmlDisabled(boolean disabled);
158
159    boolean isAspectDisabled(String aspect);
160
161    /**
162     * Sets whether the Signal Mast is allowed or configured to show an unlit
163     * aspect, or if it is always lit.
164     *
165     * @param boo Set true to allow the UnLit to be used, set false it is not
166     *            supported or allowed.
167     */
168    void setAllowUnLit(boolean boo);
169
170    boolean allowUnLit();
171}