001package jmri.jmrit.logixng;
002
003import java.io.PrintWriter;
004import java.util.Locale;
005
006import jmri.Manager;
007import jmri.jmrit.logixng.Base.PrintTreeSettings;
008
009import org.apache.commons.lang3.mutable.MutableInt;
010
011/**
012 * Manager for LogixNG
013 *
014 * @author Dave Duchamp       Copyright (C) 2007
015 * @author Daniel Bergqvist   Copyright (C) 2018
016 */
017public interface LogixNG_Manager extends Manager<LogixNG> {
018
019    /**
020     * Create a new LogixNG if the LogixNG does not exist.
021     *
022     * @param systemName the system name
023     * @param userName   the user name
024     * @return a new LogixNG or null if unable to create
025     */
026    LogixNG createLogixNG(String systemName, String userName)
027            throws IllegalArgumentException;
028
029    /**
030     * Create a new LogixNG if the LogixNG does not exist.
031     *
032     * @param systemName the system name
033     * @param userName   the user name
034     * @param inline     true if this LogixNG is an inline LogixNG
035     * @return a new LogixNG or null if unable to create
036     */
037    LogixNG createLogixNG(String systemName, String userName, boolean inline)
038            throws IllegalArgumentException;
039
040    /**
041     * For use with User GUI, to allow the auto generation of systemNames, where
042     * the user can optionally supply a username.
043     *
044     * @param userName the user name
045     * @return a new LogixNG or null if unable to create
046     */
047    LogixNG createLogixNG(String userName)
048            throws IllegalArgumentException;
049
050    /**
051     * For use with User GUI, to allow the auto generation of systemNames, where
052     * the user can optionally supply a username.
053     *
054     * @param userName  the user name
055     * @param inline    true if this LogixNG is an inline LogixNG
056     * @return a new LogixNG or null if unable to create
057     */
058    LogixNG createLogixNG(String userName, boolean inline)
059            throws IllegalArgumentException;
060
061    /**
062     * Locate via user name, then system name if needed. Does not create a new
063     * one if nothing found
064     *
065     * @param name User name or system name to match
066     * @return null if no match found
067     */
068    LogixNG getLogixNG(String name);
069
070    /** {@inheritDoc} */
071    @Override
072    LogixNG getByUserName(String name);
073
074    /** {@inheritDoc} */
075    @Override
076    LogixNG getBySystemName(String name);
077
078    /**
079     * Create a new system name for a LogixNG.
080     * @return a new system name
081     */
082    String getAutoSystemName();
083
084    /**
085     * Should the LogixNGs be disabled when the configuration file is loaded?
086     * @param value true if they should be disabled, false otherwise.
087     */
088    void setLoadDisabled(boolean value);
089
090    /**
091     * Should the LogixNGs be started when the configuration file is loaded?
092     * @param value true if they should be started, false otherwise.
093     */
094    void startLogixNGsOnLoad(boolean value);
095
096    /**
097     * Should the LogixNGs not be started when the configuration file is loaded?
098     * @return true if they should be started, false otherwise.
099     */
100    boolean isStartLogixNGsOnLoad();
101
102    /**
103     * Setup all LogixNGs. This method is called after a configuration file is
104     * loaded.
105     */
106    void setupAllLogixNGs();
107
108    /**
109     * Activate all LogixNGs, starts LogixNG processing by connecting all
110     * inputs that are included the ConditionalNGs in this LogixNG.
111     * <p>
112     * A LogixNG must be activated before it will calculate any of its
113     * ConditionalNGs.
114     */
115    void activateAllLogixNGs();
116
117    /**
118     * Activate all LogixNGs, starts LogixNG processing by connecting all
119     * inputs that are included the ConditionalNGs in this LogixNG.
120     * <p>
121     * A LogixNG must be activated before it will calculate any of its
122     * ConditionalNGs.
123     *
124     * @param runDelayed true if execute() should run on LogixNG thread delayed,
125     *                   false otherwise.
126     * @param runOnSeparateThread true if the activation should run on a
127     *                            separate thread, false otherwise
128     */
129    void activateAllLogixNGs(boolean runDelayed, boolean runOnSeparateThread);
130
131    /**
132     * DeActivate all LogixNGs, stops LogixNG processing by disconnecting all
133     * inputs that are included the ConditionalNGs in this LogixNG.
134     * <p>
135     * A LogixNG must be activated before it will calculate any of its
136     * ConditionalNGs.
137     */
138    void deActivateAllLogixNGs();
139
140    /**
141     * Is LogixNGs active?
142     * @return true if LogixNGs are active, false otherwise
143     */
144    boolean isActive();
145
146    /**
147     * Delete LogixNG by removing it from the manager. The LogixNG must first
148     * be deactivated so it stops processing.
149     *
150     * @param x the LogixNG to delete
151     */
152    void deleteLogixNG(LogixNG x);
153
154    /**
155     * Print the tree to a stream.
156     *
157     * @param writer the stream to print the tree to
158     * @param indent the indentation of each level
159     * @param lineNumber the line number
160     */
161    default void printTree(
162            PrintWriter writer,
163            String indent,
164            MutableInt lineNumber) {
165
166        printTree(new PrintTreeSettings(), writer, indent, lineNumber);
167    }
168
169    /**
170     * Print the tree to a stream.
171     *
172     * @param settings settings for what to print
173     * @param writer the stream to print the tree to
174     * @param indent the indentation of each level
175     * @param lineNumber the line number
176     */
177    void printTree(
178            PrintTreeSettings settings,
179            PrintWriter writer,
180            String indent,
181            MutableInt lineNumber);
182
183    /**
184     * Print the tree to a stream.
185     *
186     * @param locale The locale to be used
187     * @param writer the stream to print the tree to
188     * @param indent the indentation of each level
189     * @param lineNumber the line number
190     */
191    default void printTree(
192            Locale locale,
193            PrintWriter writer,
194            String indent,
195            MutableInt lineNumber) {
196
197        printTree(new PrintTreeSettings(), locale, writer, indent, lineNumber);
198    }
199
200    /**
201     * Print the tree to a stream.
202     *
203     * @param settings settings for what to print
204     * @param locale The locale to be used
205     * @param writer the stream to print the tree to
206     * @param indent the indentation of each level
207     * @param lineNumber the line number
208     */
209    void printTree(
210            PrintTreeSettings settings,
211            Locale locale,
212            PrintWriter writer,
213            String indent,
214            MutableInt lineNumber);
215
216    /**
217     * Test if parameter is a properly formatted system name.
218     * <P>
219     * This method should only be used by the managers of the LogixNG system.
220     *
221     * @param subSystemNamePrefix the sub system prefix
222     * @param systemName the system name
223     * @return enum indicating current validity, which might be just as a prefix
224     */
225    static NameValidity validSystemNameFormat(String subSystemNamePrefix, String systemName) {
226        // System names with digits. :AUTO: is generated system names
227        if (systemName.matches(subSystemNamePrefix+"(:AUTO:)?\\d+")) {
228            return NameValidity.VALID;
229
230        // System names with dollar sign allow any characters in the name
231        } else if (systemName.matches(subSystemNamePrefix+"\\$.+")) {
232            return NameValidity.VALID;
233
234        // System names with :JMRI: belongs to JMRI itself
235        } else if (systemName.matches(subSystemNamePrefix+":JMRI:.+")) {
236            return NameValidity.VALID;
237
238        // System names with :JMRI-LIB: belongs to software that uses JMRI as a lib
239        } else if (systemName.matches(subSystemNamePrefix+":JMRI-LIB:.+")) {
240            return NameValidity.VALID;
241
242        // Other system names are not valid
243        } else {
244//            LoggerFactory.getLogger(LogixNG_Manager.class)
245//                    .warn("system name {} is invalid for sub system prefix {}",
246//                            systemName, subSystemNamePrefix);
247            return NameValidity.INVALID;
248        }
249    }
250
251    /**
252     * Get the clipboard
253     * @return the clipboard
254     */
255    Clipboard getClipboard();
256
257    /**
258     * Register a manager for later retrieval by getManager()
259     * @param manager the manager
260     */
261    void registerManager(Manager<? extends MaleSocket> manager);
262
263    /**
264     * Get manager by class name
265     * @param className the class name of the manager
266     * @return the manager
267     */
268    Manager<? extends MaleSocket> getManager(String className);
269
270    /**
271     * Register a task to be run when setup LogixNGs
272     * @param task the task
273     */
274    void registerSetupTask(Runnable task);
275
276}