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     * Set aspect to a valid name in the current signal system definition.
054     *
055     * @param aspect the new aspect shown
056     * @throws IllegalArgumentException if not a valid aspect name
057     */
058    void setAspect(@Nonnull String aspect);
059
060    /**
061     * Get current aspect name. Changes to this property can be listened to
062     * using the property {@literal Aspect}.
063     *
064     * @return the current aspect or null if not set
065     */
066    @CheckForNull
067    String getAspect();
068
069    /**
070     * Get an alphabetically sorted list of valid aspects that have not been disabled.
071     *
072     * @return sorted list of valid aspects; may be empty
073     */
074    @Nonnull
075    Vector<String> getValidAspects();
076
077    SignalSystem getSignalSystem();
078
079    SignalAppearanceMap getAppearanceMap();
080
081    /**
082     * Set the specific mast type for this mast.
083     * This is the
084     * type that appears in the SystemName and filename, i.e. "SL-3-high"
085     * for the
086     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
087     * definition.
088     * @param type mast type.
089     */
090    void setMastType(@Nonnull String type);
091
092    /**
093     * Get the specific mast type for this mast.
094     * This is the
095     * type that appears in the SystemName and filename, i.e. "SL-3-high"
096     * for the
097     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
098     * definition.
099     * @return mast type.
100     */
101    String getMastType();
102
103    /**
104     * Get if signal mast is lit or dark. Changes to this property can be
105     * listened to using the property {@literal Lit}.
106     *
107     * @return true if lit; false if dark
108     */
109    @Override
110    boolean getLit();
111
112    @Override
113    void setLit(boolean newLit);
114
115    /**
116     * Get the held state of the signal mast. It controls what mechanisms can
117     * control the mast's appearance. The actual semantics are defined by those
118     * external mechanisms. Changes to this property can be listened to using
119     * the property {@literal Held}.
120     *
121     * @return true if held; false otherwise
122     */
123    @Override
124    boolean getHeld();
125
126    @Override
127    void setHeld(boolean newHeld);
128
129    /**
130     * Determine if the permissive SML logic should be disabled.  The default will be
131     * false which means that automatic permissive processing is allowed.  Prototypical
132     * CTC designs frequently require an additional action, such as Call-On, to enable permissive aspects.
133     * @return true if permissive SML is disabled.
134     */
135    boolean isPermissiveSmlDisabled();
136
137    void setPermissiveSmlDisabled(boolean disabled);
138
139    boolean isAspectDisabled(String aspect);
140
141    /**
142     * Sets whether the Signal Mast is allowed or configured to show an unlit
143     * aspect, or if it is always lit.
144     *
145     * @param boo Set true to allow the UnLit to be used, set false it is not
146     *            supported or allowed.
147     */
148    void setAllowUnLit(boolean boo);
149
150    boolean allowUnLit();
151}