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    public static final int LISTENER_TYPE_SENSOR = 1;
035    public static final int LISTENER_TYPE_TURNOUT = 2;
036    public static final int LISTENER_TYPE_LIGHT = 3;
037    public static final int LISTENER_TYPE_CONDITIONAL = 4;
038    public static final int LISTENER_TYPE_SIGNALHEAD = 5;
039    public static final int LISTENER_TYPE_MEMORY = 6;
040    public static final int LISTENER_TYPE_FASTCLOCK = 7;
041    public static final int LISTENER_TYPE_WARRANT = 8;
042    public static final int LISTENER_TYPE_SIGNALMAST = 9;
043    public static final int LISTENER_TYPE_OBLOCK = 10;
044    public static final 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    public void setEnabled(boolean state);
054
055    /**
056     * Get enabled status.
057     *
058     * @return true if enabled; false otherwise
059     */
060    public boolean getEnabled();
061
062    /**
063     * Get number of Conditionals for this Logix.
064     *
065     * @return the number of conditionals
066     */
067    public 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    public 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    public 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     * @return true if the Conditional was added, false otherwise (most likely
097     *         false indicates that maximum number of Conditionals was exceeded)
098     */
099    public boolean addConditional(String systemName, int order);
100
101    /**
102     * Add a child Conditional to the parent Logix.
103     *
104     * @since 4.7.4
105     * @param systemName The system name for the Conditional object.
106     * @param conditional The Conditional object.
107     * @return true if the Conditional was added, false otherwise.
108     */
109    public boolean addConditional(String systemName, Conditional conditional);
110
111    /**
112     * Get a Conditional belonging to this Logix.
113     *
114     * @since 4.7.4
115     * @param systemName The name of the Conditional object.
116     * @return the Conditional object or null if not found.
117     */
118    public Conditional getConditional(String systemName);
119
120    /**
121     * Delete a Conditional from this Logix.
122     * <p>
123     * Note: Since each Logix must have at least one Conditional, the last
124     * Conditional will not be deleted.
125     * <p>
126     * Returns An array of names used in an error message explaining why
127     * Conditional should not be deleted.
128     *
129     * @param systemName The Conditional system name
130     * @return names of objects blocking deletion or null; note that null does
131     *         not exclusively indicate successful deletion
132     */
133    public String[] deleteConditional(String systemName);
134
135    /**
136     * Calculate all Conditionals, triggering action if the user specified
137     * conditions are met, and the Logix is enabled.
138     */
139    public void calculateConditionals();
140
141    /**
142     * Activate the Logix, starts Logix processing by connecting all inputs that
143     * are included the Conditionals in this Logix.
144     * <p>
145     * A Logix must be activated before it will calculate any of its
146     * Conditionals.
147     */
148    public void activateLogix();
149
150    /**
151     * Deactivate the Logix. This method disconnects the Logix from all input
152     * objects and stops it from being triggered to calculate.
153     * <p>
154     * A Logix must be deactivated before its Conditionals are changed.
155     */
156    public void deActivateLogix();
157
158    /**
159     * ConditionalVariables only have a single name field.  For user interface purposes
160     * a gui name is used for the referenced conditional user name.  This is not used
161     * for other object types.
162     * <p>
163     * In addition to setting the GUI name, any state variable references are changed to
164     * conditional system names.  This converts the XML system/user name field to the system name
165     * for conditional references.  It does not affect other objects such as sensors, turnouts, etc.
166     * @since 4.7.4
167     */
168    public void setGuiNames();
169
170    /**
171     * Assemble a list of state variables that both trigger the Logix, and are
172     * changed by it. Returns true if any such variables were found. Returns
173     * false otherwise.
174     */
175    //public boolean checkLoopCondition();
176    /**
177     * Assembles a string listing state variables that might result in a loop.
178     * Returns an empty string if there are none, probably because
179     * "checkLoopConditioncheckLoopCondition" was not invoked before the call,
180     * or returned false.
181     */
182    //public ArrayList <String[]> getLoopGremlins();
183    /**
184     * Assembles and returns a list of state variables that are used by
185     * conditionals of this Logix including the number of occurances of each
186     * variable that trigger a calculation, and the number of occurances where
187     * the triggering has been suppressed. The main use of this method is to
188     * return information that can be used to test for inconsistency in
189     * suppressing triggering of a calculation among multiple occurances of the
190     * same state variable. Caller provides an ArrayList of the variables to
191     * check and an empty Array list to return the counts for triggering or
192     * suppressing calculation. The first index is a count that the
193     * correspondeing variable triggers calculation and second is a count that
194     * the correspondeing variable suppresses Calculation. Note this method must
195     * not modify the supplied variable list in any way.
196     */
197    //public void getStateVariableList(ArrayList <ConditionalVariable> varList, ArrayList <int[]> triggerPair);
198    
199}