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}