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