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