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}