001package jmri;
002
003import java.util.List;
004
005import javax.annotation.CheckForNull;
006import javax.annotation.Nonnull;
007
008import jmri.jmrit.display.layoutEditor.LayoutEditor;
009
010/**
011 *
012 * @author Kevin Dickerson Copyright (C) 2011
013 */
014public interface SignalMastLogicManager extends Manager<SignalMastLogic> {
015
016    /**
017     * String constant for Property Change auto Signal mast generate start.
018     */
019    String PROPERTY_AUTO_SIGNALMAST_GENERATE_START = "autoSignalMastGenerateStart";
020
021    /**
022     * String constant for Property Change auto signal mast generate complete.
023     */
024    String PROPERTY_AUTO_SIGNALMAST_GENERATE_COMPLETE = "autoSignalMastGenerateComplete";
025
026    /**
027     * String constant for property change auto generate update.
028     */
029    String PROPERTY_AUTO_GENERATE_UPDATE = "autoGenerateUpdate";
030
031    /**
032     * String constant for property change auto generate complete.
033     */
034    String PROPERTY_AUTO_GENERATE_COMPLETE = "autoGenerateComplete";
035
036    /*void addDestinationMastToLogic(SignalMastLogic src, SignalMast destination);*/
037    /**
038     * Replace all instances of an old SignalMast (either source or destination)
039     * with the new signal mast instance. This is for use with such tools as the
040     * Layout Editor where a signal mast at a certain location can be replaced
041     * with another, while the remainder of the configuration stays the same.
042     *
043     * @param oldMast Current Signal Mast
044     * @param newMast Replacement (new) Signal Mast
045     */
046    void replaceSignalMast(@Nonnull SignalMast oldMast, @Nonnull SignalMast newMast);
047
048    /**
049     * Discover all possible valid source + destination signal mast pairs on all
050     * Layout Editor Panels and create the corresponding SMLs.
051     *
052     * @throws jmri.JmriException if there is an error discovering signaling
053     *                            pairs
054     */
055    void automaticallyDiscoverSignallingPairs() throws JmriException;
056
057    /**
058     * Discover valid destination signal masts for a given source Signal Mast on
059     * a given Layout Editor Panel.
060     *
061     * @param source Source Signal Mast
062     * @param layout Layout Editor panel to check
063     * @throws jmri.JmriException if there is an error discovering signaling
064     *                            destinations
065     */
066    void discoverSignallingDest(@Nonnull SignalMast source, @Nonnull LayoutEditor layout) throws JmriException;
067
068    /**
069     * Remove references to and from this object, so that it can eventually be
070     * garbage-collected.
071     */
072    @Override
073    void dispose();
074
075    /**
076     * Gather a list of all the Signal Mast Logics, by destination Signal Mast.
077     *
078     * @param destination The destination Signal Mast
079     * @return a list of logics for destination or an empty list if none
080     */
081    @Nonnull
082    List<SignalMastLogic> getLogicsByDestination(@Nonnull SignalMast destination);
083
084    /**
085     * Return the Signal Mast Logic for a specific Source Signal Mast.
086     *
087     * @param source The Source Signal Mast
088     * @return The Signal Mast Logic for that mast
089     */
090    @CheckForNull
091    SignalMastLogic getSignalMastLogic(@Nonnull SignalMast source);
092
093    /**
094     * Return a list of all existing Signal Mast Logics
095     *
096     * @return An List of all Signal Mast Logics
097     */
098    @Nonnull
099    List<SignalMastLogic> getSignalMastLogicList();
100
101    /**
102     * Initialise all the Signal Mast Logics. Primarily used after loading a
103     * configuration.
104     */
105    void initialise();
106
107    /**
108     * Create a new Signal Mast Logic for a source Signal Mast.
109     *
110     * @param source The source Signal Mast
111     * @return source The new SML instance
112     * @throws IllegalArgumentException when needed
113     */
114    @Nonnull
115    SignalMastLogic newSignalMastLogic(@Nonnull SignalMast source) throws IllegalArgumentException;
116
117    /**
118     * Remove a destination Signal Mast and its settings from a Signal Mast
119     * Logic.
120     *
121     * @param sml  The Signal Mast Logic
122     * @param dest The destination mast
123     */
124    void removeSignalMastLogic(@Nonnull SignalMastLogic sml, @Nonnull SignalMast dest);
125
126    /**
127     * Completely remove a specific Signal Mast Logic by name.
128     *
129     * @param sml The Signal Mast Logic to be removed
130     */
131    void removeSignalMastLogic(@Nonnull SignalMastLogic sml);
132
133    /**
134     * Completely remove a Signal Mast from all the SMLs that use it.
135     *
136     * @param mast The Signal Mast to be removed
137     */
138    void removeSignalMast(@Nonnull SignalMast mast);
139
140    /**
141     * Disable the use of info from the Layout Editor Panels to configure a
142     * Signal Mast Logic for a specific Signal Mast.
143     *
144     * @param mast The Signal Mast for which LE info is to be disabled
145     */
146    void disableLayoutEditorUse(@Nonnull SignalMast mast);
147
148    /**
149     * Replace the complete Signal Mast Logic configurations between two Source
150     * Signal Masts.
151     *
152     * @param mastA Signal Mast A
153     * @param mastB Signal Mast B
154     */
155    void swapSignalMasts(@Nonnull SignalMast mastA, @Nonnull SignalMast mastB);
156
157    /**
158     * Check if a Signal Mast is in use as either a Source or Destination mast
159     * in any Signal Mast Logic
160     *
161     * @param mast the signal mast to check
162     * @return true if mast is used by at least one Signal Mast Logic
163     */
164    boolean isSignalMastUsed(@Nonnull SignalMast mast);
165
166    /**
167     * @return characteristic delay time in msec, used to control roughly
168     *          when signal system computations are done. (Some are half this, some twice)
169     */
170    int getSignalLogicDelay();
171
172    /**
173     * @param l characteristic delay time in msec, used to control roughly
174     *          when signal system computations are done. (Some are half this, some twice)
175     */
176    void setSignalLogicDelay(int l);
177
178    /**
179     * Iterate over the signal masts setting up direction Section sensors.
180     * @return error count
181     */
182    int setupSignalMastsDirectionSensors();
183
184    /**
185     * Iterate over the signal masts setting up direction Section sensors.
186     */
187    void removeSignalMastsDirectionSensors();
188
189}