001package jmri.jmrit.logixng; 002 003import java.io.PrintWriter; 004import java.util.Locale; 005 006import jmri.Manager; 007import jmri.jmrit.logixng.Base.PrintTreeSettings; 008 009import org.apache.commons.lang3.mutable.MutableInt; 010 011/** 012 * Manager for LogixNG 013 * 014 * @author Dave Duchamp Copyright (C) 2007 015 * @author Daniel Bergqvist Copyright (C) 2018 016 */ 017public interface LogixNG_Manager extends Manager<LogixNG> { 018 019 /** 020 * Create a new LogixNG if the LogixNG does not exist. 021 * 022 * @param systemName the system name 023 * @param userName the user name 024 * @return a new LogixNG or null if unable to create 025 */ 026 LogixNG createLogixNG(String systemName, String userName) 027 throws IllegalArgumentException; 028 029 /** 030 * Create a new LogixNG if the LogixNG does not exist. 031 * 032 * @param systemName the system name 033 * @param userName the user name 034 * @param inline true if this LogixNG is an inline LogixNG 035 * @return a new LogixNG or null if unable to create 036 */ 037 LogixNG createLogixNG(String systemName, String userName, boolean inline) 038 throws IllegalArgumentException; 039 040 /** 041 * For use with User GUI, to allow the auto generation of systemNames, where 042 * the user can optionally supply a username. 043 * 044 * @param userName the user name 045 * @return a new LogixNG or null if unable to create 046 */ 047 LogixNG createLogixNG(String userName) 048 throws IllegalArgumentException; 049 050 /** 051 * For use with User GUI, to allow the auto generation of systemNames, where 052 * the user can optionally supply a username. 053 * 054 * @param userName the user name 055 * @param inline true if this LogixNG is an inline LogixNG 056 * @return a new LogixNG or null if unable to create 057 */ 058 LogixNG createLogixNG(String userName, boolean inline) 059 throws IllegalArgumentException; 060 061 /** 062 * Locate via user name, then system name if needed. Does not create a new 063 * one if nothing found 064 * 065 * @param name User name or system name to match 066 * @return null if no match found 067 */ 068 LogixNG getLogixNG(String name); 069 070 /** {@inheritDoc} */ 071 @Override 072 LogixNG getByUserName(String name); 073 074 /** {@inheritDoc} */ 075 @Override 076 LogixNG getBySystemName(String name); 077 078 /** 079 * Create a new system name for a LogixNG. 080 * @return a new system name 081 */ 082 String getAutoSystemName(); 083 084 /** 085 * Should the LogixNGs be disabled when the configuration file is loaded? 086 * @param value true if they should be disabled, false otherwise. 087 */ 088 void setLoadDisabled(boolean value); 089 090 /** 091 * Should the LogixNGs be started when the configuration file is loaded? 092 * @param value true if they should be started, false otherwise. 093 */ 094 void startLogixNGsOnLoad(boolean value); 095 096 /** 097 * Should the LogixNGs not be started when the configuration file is loaded? 098 * @return true if they should be started, false otherwise. 099 */ 100 boolean isStartLogixNGsOnLoad(); 101 102 /** 103 * Setup all LogixNGs. This method is called after a configuration file is 104 * loaded. 105 */ 106 void setupAllLogixNGs(); 107 108 /** 109 * Activate all LogixNGs, starts LogixNG processing by connecting all 110 * inputs that are included the ConditionalNGs in this LogixNG. 111 * <p> 112 * A LogixNG must be activated before it will calculate any of its 113 * ConditionalNGs. 114 */ 115 void activateAllLogixNGs(); 116 117 /** 118 * Activate all LogixNGs, starts LogixNG processing by connecting all 119 * inputs that are included the ConditionalNGs in this LogixNG. 120 * <p> 121 * A LogixNG must be activated before it will calculate any of its 122 * ConditionalNGs. 123 * 124 * @param runDelayed true if execute() should run on LogixNG thread delayed, 125 * false otherwise. 126 * @param runOnSeparateThread true if the activation should run on a 127 * separate thread, false otherwise 128 */ 129 void activateAllLogixNGs(boolean runDelayed, boolean runOnSeparateThread); 130 131 /** 132 * DeActivate all LogixNGs, stops LogixNG processing by disconnecting all 133 * inputs that are included the ConditionalNGs in this LogixNG. 134 * <p> 135 * A LogixNG must be activated before it will calculate any of its 136 * ConditionalNGs. 137 */ 138 void deActivateAllLogixNGs(); 139 140 /** 141 * Is LogixNGs active? 142 * @return true if LogixNGs are active, false otherwise 143 */ 144 boolean isActive(); 145 146 /** 147 * Delete LogixNG by removing it from the manager. The LogixNG must first 148 * be deactivated so it stops processing. 149 * 150 * @param x the LogixNG to delete 151 */ 152 void deleteLogixNG(LogixNG x); 153 154 /** 155 * Print the tree to a stream. 156 * 157 * @param writer the stream to print the tree to 158 * @param indent the indentation of each level 159 * @param lineNumber the line number 160 */ 161 default void printTree( 162 PrintWriter writer, 163 String indent, 164 MutableInt lineNumber) { 165 166 printTree(new PrintTreeSettings(), writer, indent, lineNumber); 167 } 168 169 /** 170 * Print the tree to a stream. 171 * 172 * @param settings settings for what to print 173 * @param writer the stream to print the tree to 174 * @param indent the indentation of each level 175 * @param lineNumber the line number 176 */ 177 void printTree( 178 PrintTreeSettings settings, 179 PrintWriter writer, 180 String indent, 181 MutableInt lineNumber); 182 183 /** 184 * Print the tree to a stream. 185 * 186 * @param locale The locale to be used 187 * @param writer the stream to print the tree to 188 * @param indent the indentation of each level 189 * @param lineNumber the line number 190 */ 191 default void printTree( 192 Locale locale, 193 PrintWriter writer, 194 String indent, 195 MutableInt lineNumber) { 196 197 printTree(new PrintTreeSettings(), locale, writer, indent, lineNumber); 198 } 199 200 /** 201 * Print the tree to a stream. 202 * 203 * @param settings settings for what to print 204 * @param locale The locale to be used 205 * @param writer the stream to print the tree to 206 * @param indent the indentation of each level 207 * @param lineNumber the line number 208 */ 209 void printTree( 210 PrintTreeSettings settings, 211 Locale locale, 212 PrintWriter writer, 213 String indent, 214 MutableInt lineNumber); 215 216 /** 217 * Test if parameter is a properly formatted system name. 218 * <P> 219 * This method should only be used by the managers of the LogixNG system. 220 * 221 * @param subSystemNamePrefix the sub system prefix 222 * @param systemName the system name 223 * @return enum indicating current validity, which might be just as a prefix 224 */ 225 static NameValidity validSystemNameFormat(String subSystemNamePrefix, String systemName) { 226 // System names with digits. :AUTO: is generated system names 227 if (systemName.matches(subSystemNamePrefix+"(:AUTO:)?\\d+")) { 228 return NameValidity.VALID; 229 230 // System names with dollar sign allow any characters in the name 231 } else if (systemName.matches(subSystemNamePrefix+"\\$.+")) { 232 return NameValidity.VALID; 233 234 // System names with :JMRI: belongs to JMRI itself 235 } else if (systemName.matches(subSystemNamePrefix+":JMRI:.+")) { 236 return NameValidity.VALID; 237 238 // System names with :JMRI-LIB: belongs to software that uses JMRI as a lib 239 } else if (systemName.matches(subSystemNamePrefix+":JMRI-LIB:.+")) { 240 return NameValidity.VALID; 241 242 // Other system names are not valid 243 } else { 244// LoggerFactory.getLogger(LogixNG_Manager.class) 245// .warn("system name {} is invalid for sub system prefix {}", 246// systemName, subSystemNamePrefix); 247 return NameValidity.INVALID; 248 } 249 } 250 251 /** 252 * Get the clipboard 253 * @return the clipboard 254 */ 255 Clipboard getClipboard(); 256 257 /** 258 * Register a manager for later retrieval by getManager() 259 * @param manager the manager 260 */ 261 void registerManager(Manager<? extends MaleSocket> manager); 262 263 /** 264 * Get manager by class name 265 * @param className the class name of the manager 266 * @return the manager 267 */ 268 Manager<? extends MaleSocket> getManager(String className); 269 270 /** 271 * Register a task to be run when setup LogixNGs 272 * @param task the task 273 */ 274 void registerSetupTask(Runnable task); 275 276}