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    public 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    public 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    public 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    public 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    public LogixNG getLogixNG(String name);
069
070    /** {@inheritDoc} */
071    @Override
072    public LogixNG getByUserName(String name);
073
074    /** {@inheritDoc} */
075    @Override
076    public LogixNG getBySystemName(String name);
077
078    /**
079     * Create a new system name for a LogixNG.
080     * @return a new system name
081     */
082    public String getAutoSystemName();
083
084    /**
085     * Setup all LogixNGs. This method is called after a configuration file is
086     * loaded.
087     */
088    public void setupAllLogixNGs();
089
090    /**
091     * Activate all LogixNGs, starts LogixNG processing by connecting all
092     * inputs that are included the ConditionalNGs in this LogixNG.
093     * <p>
094     * A LogixNG must be activated before it will calculate any of its
095     * ConditionalNGs.
096     */
097    public void activateAllLogixNGs();
098
099    /**
100     * Activate all LogixNGs, starts LogixNG processing by connecting all
101     * inputs that are included the ConditionalNGs in this LogixNG.
102     * <p>
103     * A LogixNG must be activated before it will calculate any of its
104     * ConditionalNGs.
105     *
106     * @param runDelayed true if execute() should run on LogixNG thread delayed,
107     *                   false otherwise.
108     * @param runOnSeparateThread true if the activation should run on a
109     *                            separate thread, false otherwise
110     */
111    public void activateAllLogixNGs(boolean runDelayed, boolean runOnSeparateThread);
112
113    /**
114     * DeActivate all LogixNGs, stops LogixNG processing by disconnecting all
115     * inputs that are included the ConditionalNGs in this LogixNG.
116     * <p>
117     * A LogixNG must be activated before it will calculate any of its
118     * ConditionalNGs.
119     */
120    public void deActivateAllLogixNGs();
121
122    /**
123     * Is LogixNGs active?
124     * @return true if LogixNGs are active, false otherwise
125     */
126    public boolean isActive();
127
128    /**
129     * Delete LogixNG by removing it from the manager. The LogixNG must first
130     * be deactivated so it stops processing.
131     *
132     * @param x the LogixNG to delete
133     */
134    void deleteLogixNG(LogixNG x);
135
136    /**
137     * Support for loading LogixNGs in a disabled state
138     *
139     * @param s true if LogixNG should be disabled when loaded
140     */
141    public void setLoadDisabled(boolean s);
142
143    /**
144     * Print the tree to a stream.
145     *
146     * @param writer the stream to print the tree to
147     * @param indent the indentation of each level
148     * @param lineNumber the line number
149     */
150    public default void printTree(
151            PrintWriter writer,
152            String indent,
153            MutableInt lineNumber) {
154
155        printTree(new PrintTreeSettings(), writer, indent, lineNumber);
156    }
157
158    /**
159     * Print the tree to a stream.
160     *
161     * @param settings settings for what to print
162     * @param writer the stream to print the tree to
163     * @param indent the indentation of each level
164     * @param lineNumber the line number
165     */
166    public void printTree(
167            PrintTreeSettings settings,
168            PrintWriter writer,
169            String indent,
170            MutableInt lineNumber);
171
172    /**
173     * Print the tree to a stream.
174     *
175     * @param locale The locale to be used
176     * @param writer the stream to print the tree to
177     * @param indent the indentation of each level
178     * @param lineNumber the line number
179     */
180    public default void printTree(
181            Locale locale,
182            PrintWriter writer,
183            String indent,
184            MutableInt lineNumber) {
185
186        printTree(new PrintTreeSettings(), locale, writer, indent, lineNumber);
187    }
188
189    /**
190     * Print the tree to a stream.
191     *
192     * @param settings settings for what to print
193     * @param locale The locale to be used
194     * @param writer the stream to print the tree to
195     * @param indent the indentation of each level
196     * @param lineNumber the line number
197     */
198    public void printTree(
199            PrintTreeSettings settings,
200            Locale locale,
201            PrintWriter writer,
202            String indent,
203            MutableInt lineNumber);
204
205    /**
206     * Test if parameter is a properly formatted system name.
207     * <P>
208     * This method should only be used by the managers of the LogixNG system.
209     *
210     * @param subSystemNamePrefix the sub system prefix
211     * @param systemName the system name
212     * @return enum indicating current validity, which might be just as a prefix
213     */
214    public static NameValidity validSystemNameFormat(String subSystemNamePrefix, String systemName) {
215        // System names with digits. :AUTO: is generated system names
216        if (systemName.matches(subSystemNamePrefix+"(:AUTO:)?\\d+")) {
217            return NameValidity.VALID;
218
219        // System names with dollar sign allow any characters in the name
220        } else if (systemName.matches(subSystemNamePrefix+"\\$.+")) {
221            return NameValidity.VALID;
222
223        // System names with :JMRI: belongs to JMRI itself
224        } else if (systemName.matches(subSystemNamePrefix+":JMRI:.+")) {
225            return NameValidity.VALID;
226
227        // System names with :JMRI-LIB: belongs to software that uses JMRI as a lib
228        } else if (systemName.matches(subSystemNamePrefix+":JMRI-LIB:.+")) {
229            return NameValidity.VALID;
230
231        // Other system names are not valid
232        } else {
233//            LoggerFactory.getLogger(LogixNG_Manager.class)
234//                    .warn("system name {} is invalid for sub system prefix {}",
235//                            systemName, subSystemNamePrefix);
236            return NameValidity.INVALID;
237        }
238    }
239
240    /**
241     * Get the clipboard
242     * @return the clipboard
243     */
244    public Clipboard getClipboard();
245
246    /**
247     * Register a manager for later retrieval by getManager()
248     * @param manager the manager
249     */
250    public void registerManager(Manager<? extends MaleSocket> manager);
251
252    /**
253     * Get manager by class name
254     * @param className the class name of the manager
255     * @return the manager
256     */
257    public Manager<? extends MaleSocket> getManager(String className);
258
259    /**
260     * Register a task to be run when setup LogixNGs
261     * @param task the task
262     */
263    public void registerSetupTask(Runnable task);
264
265}