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     */
113    @Nonnull
114    SignalMastLogic newSignalMastLogic(@Nonnull SignalMast source) throws IllegalArgumentException;
115
116    /**
117     * Remove a destination Signal Mast and its settings from a Signal Mast
118     * Logic.
119     *
120     * @param sml  The Signal Mast Logic
121     * @param dest The destination mast
122     */
123    void removeSignalMastLogic(@Nonnull SignalMastLogic sml, @Nonnull SignalMast dest);
124
125    /**
126     * Completely remove a specific Signal Mast Logic by name.
127     *
128     * @param sml The Signal Mast Logic to be removed
129     */
130    void removeSignalMastLogic(@Nonnull SignalMastLogic sml);
131
132    /**
133     * Completely remove a Signal Mast from all the SMLs that use it.
134     *
135     * @param mast The Signal Mast to be removed
136     */
137    void removeSignalMast(@Nonnull SignalMast mast);
138
139    /**
140     * Disable the use of info from the Layout Editor Panels to configure a
141     * Signal Mast Logic for a specific Signal Mast.
142     *
143     * @param mast The Signal Mast for which LE info is to be disabled
144     */
145    void disableLayoutEditorUse(@Nonnull SignalMast mast);
146
147    /**
148     * Replace the complete Signal Mast Logic configurations between two Source
149     * Signal Masts.
150     *
151     * @param mastA Signal Mast A
152     * @param mastB Signal Mast B
153     */
154    void swapSignalMasts(@Nonnull SignalMast mastA, @Nonnull SignalMast mastB);
155
156    /**
157     * Check if a Signal Mast is in use as either a Source or Destination mast
158     * in any Signal Mast Logic
159     *
160     * @param mast the signal mast to check
161     * @return true if mast is used by at least one Signal Mast Logic
162     */
163    boolean isSignalMastUsed(@Nonnull SignalMast mast);
164
165    /**
166     * @return characteristic delay time in msec, used to control roughly
167     *          when signal system computations are done. (Some are half this, some twice)
168     */
169    int getSignalLogicDelay();
170
171    /**
172     * @param l characteristic delay time in msec, used to control roughly
173     *          when signal system computations are done. (Some are half this, some twice)
174     */
175    void setSignalLogicDelay(int l);
176
177    /**
178     * Iterate over the signal masts setting up direction Section sensors.
179     * @return error count
180     */
181    int setupSignalMastsDirectionSensors();
182
183    /**
184     * Iterate over the signal masts setting up direction Section sensors.
185     */
186    void removeSignalMastsDirectionSensors();
187
188}