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    public static final int TOGGLE = 0x08;
041    static final int MAX_CONTROL_SENSORS = 3;
042
043    static final int ONACTIVE = 0;    // route fires if sensor goes active
044    static final int ONINACTIVE = 1;  // route fires if sensor goes inactive
045    static final int VETOACTIVE = 2;  // sensor must be active for route to fire
046    static final int VETOINACTIVE = 3;  // sensor must be inactive for route to fire
047
048    static final int ONCHANGE = 32;   // route fires if turnout or sensor changes
049
050    static final int ONCLOSED = 2;    // route fires if turnout goes closed
051    static final int ONTHROWN = 4;  // route fires if turnout goes thrown
052    static final int VETOCLOSED = 8;  // turnout must be closed for route to fire
053    static final 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    public void setEnabled(boolean state);
061
062    /**
063     * Get enabled status.
064     *
065     * @return true if enabled; false otherwise
066     */
067    public boolean getEnabled();
068
069    /**
070     * Set locked status.
071     *
072     * @param state true if locked; false otherwise
073     */
074    public void setLocked(boolean state);
075
076    /**
077     * Get locked status.
078     *
079     * @return true if locked; false otherwise
080     */
081    public boolean getLocked();
082
083    /**
084     * Has at least one lockable turnout.
085     *
086     * @return true if lockable; false otherwise
087     */
088    public 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    public boolean addOutputTurnout(String systemName, int state);
100
101    /**
102     * Delete all output Turnouts from this Route.
103     */
104    public void clearOutputTurnouts();
105
106    public 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    public 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    public 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    public 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    public 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    public 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    public boolean addOutputSensor(String systemName, int state);
158
159    /**
160     * Delete all output Sensors from this Route.
161     */
162    public void clearOutputSensors();
163
164    public 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    public 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    public 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    public 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    public 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    public 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    public 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    public 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    public 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    public 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    public 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    public String getTurnoutsAlignedSensor();
248
249    /**
250     * Get the turnouts aligned sensor.
251     *
252     * @return the sensor or null if not defined
253     */
254    public 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    public boolean addSensorToRoute(String sensorSystemName, int mode);
264
265    /**
266     * Delete all control Sensors from this Route.
267     */
268    public 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    public 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    public 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    public 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    public 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    public 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    public Turnout getCtlTurnout();
314
315    /**
316     * Set the State of control Turnout that fires this Route.
317     *
318     * @param turnoutState the turnout state
319     */
320    public 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    public int getControlTurnoutState();
328
329    /**
330     * Set the lock control Turnout for this Route.
331     *
332     * @param turnoutSystemName the system name of the turnout
333     */
334    public void setLockControlTurnout(String turnoutSystemName);
335
336    /**
337     * Get the SystemName of the lock control Turnout for this Route.
338     *
339     * @return the system name or null if not defined
340     */
341    public String getLockControlTurnout();
342
343    /**
344     * Get the Turnout of a lock control Turnout for this Route.
345     *
346     * @return the turnout or null if not defined
347     */
348    public Turnout getLockCtlTurnout();
349
350    /**
351     * Set the State of the lock control Turnout for this Route.
352     *
353     * @param turnoutState the turnout state
354     */
355    public void setLockControlTurnoutState(int turnoutState);
356
357    /**
358     * Get the State of the lock control Turnout that locks this Route.
359     *
360     * @return the turnout state
361     */
362    public int getLockControlTurnoutState();
363
364    /**
365     * Set the delay between issuing Turnout commands on this route.
366     *
367     * @param delay the delay in milliseconds
368     */
369    public void setRouteCommandDelay(int delay);
370
371    /**
372     * Get the delay between issuing Turnout commands on this route.
373     *
374     * @return the delay in milliseconds
375     */
376    public int getRouteCommandDelay();
377
378    /**
379     * Set the Route.
380     * <p>
381     * Sets all Route Turnouts to the directed state in the Route definition.
382     */
383    public void setRoute();
384
385    /**
386     * Activate the Route.
387     * <p>
388     * This starts route processing by connecting to inputs, etc. A Route must
389     * be activated before it will fire.
390     */
391    public void activateRoute();
392
393    /**
394     * Deactivate the Route.
395     * <p>
396     * This disconnects the Route from all other objects and stops it from
397     * processing. A Route must be deactivated before its input and output
398     * definitions are changed.
399     */
400    public void deActivateRoute();
401
402}