001package jmri;
002
003import javax.annotation.CheckForNull;
004
005/**
006 * A Logix is a group of Conditionals that monitor one or more conditions
007 * (internal or on the layout). It services these Conditionals by installing and
008 * deinstalling the proper listeners for their variables.
009 * <p>
010 * A Logix can be enabled or not. It passes this attribute to its Conditionals.
011 * By default it is enabled. When not enabled, a Conditional will still respond
012 * to callbacks from its listeners and calculate its state, however it will not
013 * execute its actions. Enabled is a bound property of a Logix.
014 * <p>
015 * A Logix can be deactivated or not. When deactivated, the listeners of the
016 * Conditional variables are deinstalled.
017 * <p>
018 * A Logix does not have a "state", however, each of its Conditionals does.
019 *
020 * <hr>
021 * This file is part of JMRI.
022 * <p>
023 * JMRI is free software; you can redistribute it and/or modify it under the
024 * terms of version 2 of the GNU General Public License as published by the Free
025 * Software Foundation. See the "COPYING" file for a copy of this license.
026 * <p>
027 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
028 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
029 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
030 *
031 * @author Dave Duchamp Copyright (C) 2007
032 * @author Additional modifications Pete Cressman 2009
033 */
034public interface Logix extends NamedBean {
035
036    int LISTENER_TYPE_SENSOR = 1;
037    int LISTENER_TYPE_TURNOUT = 2;
038    int LISTENER_TYPE_LIGHT = 3;
039    int LISTENER_TYPE_CONDITIONAL = 4;
040    int LISTENER_TYPE_SIGNALHEAD = 5;
041    int LISTENER_TYPE_MEMORY = 6;
042    int LISTENER_TYPE_FASTCLOCK = 7;
043    int LISTENER_TYPE_WARRANT = 8;
044    int LISTENER_TYPE_SIGNALMAST = 9;
045    int LISTENER_TYPE_OBLOCK = 10;
046    int LISTENER_TYPE_ENTRYEXIT = 11;
047
048    /**
049     * Set enabled status. Enabled is a bound property All conditionals are set
050     * to UNKNOWN state and recalculated when the Logix is enabled, provided the
051     * Logix has been previously activated.
052     *
053     * @param state true if Logix should be enabled; false otherwise
054     */
055    void setEnabled(boolean state);
056
057    /**
058     * Get enabled status.
059     *
060     * @return true if enabled; false otherwise
061     */
062    boolean getEnabled();
063
064    /**
065     * Get number of Conditionals for this Logix.
066     *
067     * @return the number of conditionals
068     */
069    int getNumConditionals();
070
071    /**
072     * Move 'row' to 'nextInOrder' and shift all between 'nextInOrder' and 'row'
073     * up one position. Requires {@code row > nextInOrder}.
074     *
075     * @param nextInOrder target order for Conditional at row
076     * @param row         position of Conditional to move
077     */
078    void swapConditional(int nextInOrder, int row);
079
080    /**
081     * Returns the system name of the conditional that will calculate in the
082     * specified order. This is also the order the Conditional is listed in the
083     * Add/Edit Logix dialog. If 'order' is greater than the number of
084     * Conditionals for this Logix, null is returned.
085     *
086     * @param order order in which the Conditional calculates
087     * @return system name of conditional or an empty String
088     */
089    @CheckForNull
090    String getConditionalByNumberOrder(int order);
091
092    /**
093     * Add a Conditional name and sequence number to this Logix.
094     *
095     * @param systemName The Conditional system name
096     * @param order      the order this conditional should calculate in if
097     *                   order is negative, the conditional is added at the end
098     *                   of current group of conditionals
099     */
100    void addConditional(String systemName, int order);
101
102    /**
103     * Add a child Conditional to the parent Logix.
104     *
105     * @since 4.7.4
106     * @param systemName The system name for the Conditional object.
107     * @param conditional The Conditional object.
108     * @return true if the Conditional was added, false otherwise.
109     */
110    boolean addConditional(String systemName, Conditional conditional);
111
112    /**
113     * Get a Conditional belonging to this Logix.
114     *
115     * @since 4.7.4
116     * @param systemName The name of the Conditional object.
117     * @return the Conditional object or null if not found.
118     */
119    @CheckForNull
120    Conditional getConditional(String systemName);
121
122    /**
123     * Delete a Conditional from this Logix.
124     * <p>
125     * Note: Since each Logix must have at least one Conditional, the last
126     * Conditional will not be deleted.
127     * <p>
128     * Returns An array of names used in an error message explaining why
129     * Conditional should not be deleted.
130     *
131     * @param systemName The Conditional system name
132     * @return names of objects blocking deletion or null; note that null does
133     *         not exclusively indicate successful deletion
134     */
135    String[] deleteConditional(String systemName);
136
137    /**
138     * Calculate all Conditionals, triggering action if the user specified
139     * conditions are met, and the Logix is enabled.
140     */
141    void calculateConditionals();
142
143    /**
144     * Activate the Logix, starts Logix processing by connecting all inputs that
145     * are included the Conditionals in this Logix.
146     * <p>
147     * A Logix must be activated before it will calculate any of its
148     * Conditionals.
149     */
150    void activateLogix();
151
152    /**
153     * Deactivate the Logix. This method disconnects the Logix from all input
154     * objects and stops it from being triggered to calculate.
155     * <p>
156     * A Logix must be deactivated before its Conditionals are changed.
157     */
158    void deActivateLogix();
159
160    /**
161     * ConditionalVariables only have a single name field.  For user interface purposes
162     * a gui name is used for the referenced conditional user name.  This is not used
163     * for other object types.
164     * <p>
165     * In addition to setting the GUI name, any state variable references are changed to
166     * conditional system names.  This converts the XML system/user name field to the system name
167     * for conditional references.  It does not affect other objects such as sensors, turnouts, etc.
168     * @since 4.7.4
169     */
170    void setGuiNames();
171
172    /**
173     * Assemble a list of state variables that both trigger the Logix, and are
174     * changed by it. Returns true if any such variables were found. Returns
175     * false otherwise.
176     */
177    //boolean checkLoopCondition();
178    /**
179     * Assembles a string listing state variables that might result in a loop.
180     * Returns an empty string if there are none, probably because
181     * "checkLoopConditioncheckLoopCondition" was not invoked before the call,
182     * or returned false.
183     */
184    //ArrayList <String[]> getLoopGremlins();
185    /**
186     * Assembles and returns a list of state variables that are used by
187     * conditionals of this Logix including the number of occurances of each
188     * variable that trigger a calculation, and the number of occurances where
189     * the triggering has been suppressed. The main use of this method is to
190     * return information that can be used to test for inconsistency in
191     * suppressing triggering of a calculation among multiple occurances of the
192     * same state variable. Caller provides an ArrayList of the variables to
193     * check and an empty Array list to return the counts for triggering or
194     * suppressing calculation. The first index is a count that the
195     * correspondeing variable triggers calculation and second is a count that
196     * the correspondeing variable suppresses Calculation. Note this method must
197     * not modify the supplied variable list in any way.
198     */
199    //void getStateVariableList(ArrayList <ConditionalVariable> varList, ArrayList <int[]> triggerPair);
200    
201}