001package jmri; 002 003/** 004 * Routes represent a collection of Turnouts that may be set at the same time. 005 * <p> 006 * When a user adds a Turnout to a Route, the user specifies whether the Turnout 007 * state is to be set to CLOSED or THROWN when the Route is invoked (set). 008 * <p> 009 * Initially, Routes will have a fixed maximum number of sensors for simplicity 010 * of implementation. We can revise this later to use Java Collections if this 011 * becomes a problem. 012 * <p> 013 * To allow control via fascia panel pushbuttons, Routes may optionally be 014 * invoked by one or more Sensors (up to the maximum allowed). 015 * <p> 016 * A route can be enabled or not. By default it is enabled, and will act when 017 * its specified input conditions become satisfied. When not enabled (the 018 * enabled parameter is false), the route will not act even if the specified 019 * input conditions are satisfied. When the route transitions from disabled to 020 * enabled, it may act, depending on the conditions: Edge triggered conditions 021 * will not be satisfied, but level-conditions may be. 022 * 023 * <hr> 024 * This file is part of JMRI. 025 * <p> 026 * JMRI is free software; you can redistribute it and/or modify it under the 027 * terms of version 2 of the GNU General Public License as published by the Free 028 * Software Foundation. See the "COPYING" file for a copy of this license. 029 * <p> 030 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY 031 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 032 * A PARTICULAR PURPOSE. See the GNU General Public License for more details. 033 * 034 * @author Dave Duchamp Copyright (C) 2004 035 * @author Bob Jacobsen Copyright (C) 2007 036 * @author Simon Reader Copyright (C) 2008 037 */ 038public interface Route extends NamedBean { 039 040 int TOGGLE = 0x08; 041 int MAX_CONTROL_SENSORS = 3; 042 043 int ONACTIVE = 0; // route fires if sensor goes active 044 int ONINACTIVE = 1; // route fires if sensor goes inactive 045 int VETOACTIVE = 2; // sensor must be active for route to fire 046 int VETOINACTIVE = 3; // sensor must be inactive for route to fire 047 048 int ONCHANGE = 32; // route fires if turnout or sensor changes 049 050 int ONCLOSED = 2; // route fires if turnout goes closed 051 int ONTHROWN = 4; // route fires if turnout goes thrown 052 int VETOCLOSED = 8; // turnout must be closed for route to fire 053 int VETOTHROWN = 16; // turnout must be thrown for route to fire 054 055 /** 056 * Set enabled status. 057 * 058 * @param state true if enabled; false otherwise 059 */ 060 void setEnabled(boolean state); 061 062 /** 063 * Get enabled status. 064 * 065 * @return true if enabled; false otherwise 066 */ 067 boolean getEnabled(); 068 069 /** 070 * Set locked status. 071 * 072 * @param state true if locked; false otherwise 073 */ 074 void setLocked(boolean state); 075 076 /** 077 * Get locked status. 078 * 079 * @return true if locked; false otherwise 080 */ 081 boolean getLocked(); 082 083 /** 084 * Has at least one lockable turnout. 085 * 086 * @return true if lockable; false otherwise 087 */ 088 boolean canLock(); 089 090 /** 091 * Add an output Turnout to this Route. 092 * 093 * @param systemName The turnout system name 094 * @param state must be Turnout.CLOSED, Turnout.THROWN, or 095 * Route.TOGGLE, which determines how the Turnout is to be 096 * switched when this Route is set 097 * @return true if the output turnout was added 098 */ 099 boolean addOutputTurnout(String systemName, int state); 100 101 /** 102 * Delete all output Turnouts from this Route. 103 */ 104 void clearOutputTurnouts(); 105 106 int getNumOutputTurnouts(); 107 108 /** 109 * Inquire if a Turnout is included in this Route as an output. 110 * 111 * @param systemName the system name of the turnout 112 * @return true if the named turnout is an output; false otherwise 113 */ 114 boolean isOutputTurnoutIncluded(String systemName); 115 116 /** 117 * get the Set State of an output Turnout. 118 * 119 * @param systemName the system name of the turnout 120 * @return the state or -1 if the Turnout is not found 121 */ 122 int getOutputTurnoutSetState(String systemName); 123 124 /** 125 * Get an output Turnout system name by index. 126 * 127 * @param index the index of the turnout 128 * @return the turnout system name or null if no turnout exists at index 129 */ 130 String getOutputTurnoutByIndex(int index); 131 132 /** 133 * Get the output Turnout by index. 134 * 135 * @param index the index of the turnout 136 * @return the turnout or null if no turnout exists at index 137 */ 138 Turnout getOutputTurnout(int index); 139 140 /** 141 * Get the desired state of the Turnout by index. 142 * 143 * @param index the index of the turnout 144 * @return the turnout state or -1 if no turnout exists at index 145 */ 146 int getOutputTurnoutState(int index); 147 148 /** 149 * Add an output Sensor to this Route. 150 * 151 * @param systemName the sensor system name 152 * @param state the state the sensor switches to when the Route is set; 153 * must be one of Sensor.ACTIVE, Sensor.INACTIVE, or 154 * Route.TOGGLE 155 * @return true if the sensor was added; false otherwise 156 */ 157 boolean addOutputSensor(String systemName, int state); 158 159 /** 160 * Delete all output Sensors from this Route. 161 */ 162 void clearOutputSensors(); 163 164 int getNumOutputSensors(); 165 166 /** 167 * Inquire if a Sensor is included in this Route as an output. 168 * 169 * @param systemName the Sensor system name 170 * @return true if the sensor is an output in this Route 171 */ 172 boolean isOutputSensorIncluded(String systemName); 173 174 /** 175 * Get the Set State of an output Sensor. 176 * 177 * @param systemName the system name of the Sensor 178 * @return -1 if the Sensor is not found 179 */ 180 int getOutputSensorSetState(String systemName); 181 182 /** 183 * Get an output Sensor system name by index. 184 * 185 * @param index the index of the sensor 186 * @return the sensor or null if no sensor exists at index 187 */ 188 String getOutputSensorByIndex(int index); 189 190 /** 191 * Get the output Sensor by index. 192 * 193 * @param index the index of the sensor 194 * @return the sensor or null if no sensor exists at index 195 */ 196 Sensor getOutputSensor(int index); 197 198 /** 199 * Get the desired state of an output Sensor by index. 200 * 201 * @param index the index of the sensor 202 * @return the sensor state or -1 if no sensor exists at index 203 */ 204 int getOutputSensorState(int index); 205 206 /** 207 * Set name of script file to be run when Route is fired. 208 * 209 * @param filename path to script 210 */ 211 void setOutputScriptName(String filename); 212 213 /** 214 * Get name of script file to be run when Route is fired. 215 * 216 * @return script path or null if not defined 217 */ 218 String getOutputScriptName(); 219 220 /** 221 * Set name of sound file to be played when Route is fired. 222 * 223 * @param filename path to sound 224 */ 225 void setOutputSoundName(String filename); 226 227 /** 228 * Get name of sound file to be played when Route is fired. 229 * 230 * @return sound file path or null if not defined 231 */ 232 String getOutputSoundName(); 233 234 /** 235 * Set a sensor to be the turnouts aligned sensor. 236 * 237 * @param sensorSystemName the system name of the sensor; pass null to 238 * disassociate any sensor from this route 239 */ 240 void setTurnoutsAlignedSensor(String sensorSystemName); 241 242 /** 243 * Get the system name of the turnouts aligned sensor. 244 * 245 * @return the name or null if not defined 246 */ 247 String getTurnoutsAlignedSensor(); 248 249 /** 250 * Get the turnouts aligned sensor. 251 * 252 * @return the sensor or null if not defined 253 */ 254 Sensor getTurnoutsAlgdSensor(); 255 256 /** 257 * Add a Sensor to the list of control Sensors for this Route. 258 * 259 * @param sensorSystemName system name of the sensor 260 * @param mode the default state of the sensor 261 * @return true if added; false otherwise 262 */ 263 boolean addSensorToRoute(String sensorSystemName, int mode); 264 265 /** 266 * Delete all control Sensors from this Route. 267 */ 268 void clearRouteSensors(); 269 270 /** 271 * Get the SystemName of a control Sensor in this Route. 272 * 273 * @param index The index in the Sensor array of the requested Sensor 274 * @return null If there is no Sensor at index 275 */ 276 String getRouteSensorName(int index); 277 278 /** 279 * Get the Sensor of a control Sensor in this Route. 280 * 281 * @param index The index in the Sensor array of the requested Sensor 282 * @return null If there is no Sensor with at index 283 */ 284 Sensor getRouteSensor(int index); 285 286 /** 287 * Get the state of a particular Sensor in this Route. 288 * 289 * @param index The index in the Sensor array of the requested Sensor 290 * @return ONACTIVE if there is no Sensor with at index 291 */ 292 int getRouteSensorMode(int index); 293 294 /** 295 * Set the control Turnout for this Route. 296 * 297 * @param turnoutSystemName the system name of a turnout 298 */ 299 void setControlTurnout(String turnoutSystemName); 300 301 /** 302 * Get the SystemName of the control Turnout for this Route. 303 * 304 * @return the name of the control turnout or null if not set 305 */ 306 String getControlTurnout(); 307 308 /** 309 * Get the Turnout of a control Turnout for this Route. 310 * 311 * @return the control turnout or null if not set 312 */ 313 Turnout getCtlTurnout(); 314 315 /** 316 * Set the State of control Turnout that fires this Route. 317 * 318 * @param turnoutState the turnout state 319 */ 320 void setControlTurnoutState(int turnoutState); 321 322 /** 323 * Get the State of control Turnout that fires this Route. 324 * 325 * @return the turnout state 326 */ 327 int getControlTurnoutState(); 328 329 330 /** 331 * Set the feedback to use when checking the control turnout state 332 * 333 * @param turnoutFeedbackIsCommanded true if commanded state is to be checked; default is false 334 */ 335 void setControlTurnoutFeedback(boolean turnoutFeedbackIsCommanded); 336 337 /** 338 * Get the feedback to use when checking the control turnout state 339 * 340 * @return true if commanded state is to be checked; false is known state 341 */ 342 boolean getControlTurnoutFeedback(); 343 344 /** 345 * Set the lock control Turnout for this Route. 346 * 347 * @param turnoutSystemName the system name of the turnout 348 */ 349 void setLockControlTurnout(String turnoutSystemName); 350 351 /** 352 * Get the SystemName of the lock control Turnout for this Route. 353 * 354 * @return the system name or null if not defined 355 */ 356 String getLockControlTurnout(); 357 358 /** 359 * Get the Turnout of a lock control Turnout for this Route. 360 * 361 * @return the turnout or null if not defined 362 */ 363 Turnout getLockCtlTurnout(); 364 365 /** 366 * Set the State of the lock control Turnout for this Route. 367 * 368 * @param turnoutState the turnout state 369 */ 370 void setLockControlTurnoutState(int turnoutState); 371 372 /** 373 * Get the State of the lock control Turnout that locks this Route. 374 * 375 * @return the turnout state 376 */ 377 int getLockControlTurnoutState(); 378 379 /** 380 * Set the delay between issuing Turnout commands on this route. 381 * 382 * @param delay the delay in milliseconds 383 */ 384 void setRouteCommandDelay(int delay); 385 386 /** 387 * Get the delay between issuing Turnout commands on this route. 388 * 389 * @return the delay in milliseconds 390 */ 391 int getRouteCommandDelay(); 392 393 /** 394 * Set the Route. 395 * <p> 396 * Sets all Route Turnouts to the directed state in the Route definition. 397 */ 398 void setRoute(); 399 400 /** 401 * Activate the Route. 402 * <p> 403 * This starts route processing by connecting to inputs, etc. A Route must 404 * be activated before it will fire. 405 */ 406 void activateRoute(); 407 408 /** 409 * Deactivate the Route. 410 * <p> 411 * This disconnects the Route from all other objects and stops it from 412 * processing. A Route must be deactivated before its input and output 413 * definitions are changed. 414 */ 415 void deActivateRoute(); 416 417}