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