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}