001package jmri;
002
003import java.util.List;
004
005/**
006 * Each LightControl object is linked to a specific Light, and provides one of
007 * the controls available for switching the Light ON/OFF in response to time or
008 * events occurring on the layout.
009 * <p>
010 * Each LightControl holds the information for one control of the parent Light.
011 * <p>
012 * Each Light may have as many controls as desired by the user. It is the user's
013 * responsibility to ensure that the various control mechanisms do not conflict
014 * with one another.
015 * <p>
016 * Available control types are those defined in the Light.java interface.
017 * Control types: SENSOR_CONTROL FAST_CLOCK_CONTROL TURNOUT_STATUS_CONTROL
018 * TIMED_ON_CONTROL TWO_SENSOR_CONTROL
019 *
020 * <hr>
021 * This file is part of JMRI.
022 * <p>
023 * JMRI is free software; you can redistribute it and/or modify it under the
024 * terms of version 2 of the GNU General Public License as published by the Free
025 * Software Foundation. See the "COPYING" file for a copy of this license.
026 * <p>
027 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
028 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
029 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
030 *
031 * @author Dave Duchamp      Copyright (C) 2010
032 * @author Daniel Bergqvist  Copyright (C) 2020
033 */
034public interface LightControl {
035
036    /**
037     * Get the control type used by the Control
038     *
039     * @return the Control Type, eg. FAST_CLOCK_CONTROL
040     */
041    int getControlType();
042
043    /**
044     * Set the control type used by the Control
045     * Does NOT update any changelisteners
046     *
047     * @param type the Control Type, eg. FAST_CLOCK_CONTROL
048     */
049    void setControlType(int type);
050
051    /**
052     * Set Sensor 1 used by the 1 Sensor and 2 Sensor Control
053     * Does NOT update any changelisteners
054     * If Sensor not present and name not empty, is provided by the SensorManager
055     * when #activateLightControl() is called
056     *
057     * @param sensorName the Sensor name
058     */
059    void setControlSensorName(String sensorName);
060
061    /**
062     * Get the Sensor State used by the 1 Sensor Control
063     *
064     * @return Sensor.ACTIVE or Sensor.INACTIVE
065     */
066    int getControlSensorSense();
067
068    /**
069     * Get the Sensor 1 name for 1 and 2 Sensor Control Types.
070     *
071     * @return  If a Sensor is registered, returns the Sensor.getName()
072     *          else the Sensor Name as set by #setControlSensorName
073     */
074    String getControlSensorName();
075
076    /**
077     * Set the Sensor State used by the Control
078     * Does NOT update any changelisteners
079     *
080     * @param sense The state to react to, eg. Sensor.ACTIVE or Sensor.INACTIVE
081     */
082    void setControlSensorSense(int sense);
083
084    /**
085     * Get the Fast Clock On Hour.
086     *
087     * @return  On Hour value
088     */
089    int getFastClockOnHour();
090
091    /**
092     * Get the Fast Clock On Minute.
093     *
094     * @return  On Minute value
095     */
096    int getFastClockOnMin();
097
098    /**
099     * Get the Fast Clock On Hours and Minutes Combined
100     * Convenience method of separate getFastClockOnHour() and getFastClockOnMin()
101     * @return  Total combined Minute value
102     */
103    int getFastClockOnCombined();
104
105    /**
106     * Get the Fast Clock Off Hour.
107     *
108     * @return  Off Hour value
109     */
110    int getFastClockOffHour();
111
112    /**
113     * Get the Fast Clock Off Minute.
114     *
115     * @return  Off Minute value
116     */
117    int getFastClockOffMin();
118    
119    /**
120     * Get the Fast Clock Off Hours and Minutes Combined
121     * Convenience method of separate getFastClockOnHour() and getFastClockOnMin()
122     * @return  Total combined Minute value
123     */
124    int getFastClockOffCombined();
125
126    /**
127     * Set a Fast Clock LightControl Schedule.
128     *
129     * @param onHour Hour the Light should switch On
130     * @param onMin Minute the Light should switch On
131     * @param offHour Hour the Light should switch Off
132     * @param offMin Minute the Light should switch Off     * 
133     */
134    void setFastClockControlSchedule(int onHour, int onMin, int offHour, int offMin);
135
136    /**
137     * Get the LightControl Turnout Name.
138     *
139     * @return  The Turnout name
140     */
141    String getControlTurnoutName();
142
143    /**
144     * Set the Turnout used by the Control
145     * Does NOT update any changelisteners
146     * <p>
147     * A Turnout of this name is provided by the TurnoutManager 
148     * on LightControl Initialisation
149     *
150     * @param turnoutName The Turnout name
151     */
152    void setControlTurnout(String turnoutName);
153
154    /**
155     * Get the LightControl Turnout Name.
156     *
157     * @return  The Turnout name
158     */
159    int getControlTurnoutState();
160
161    /**
162     * Set the Turnout State used by the Control
163     * Does NOT update any changelisteners
164     *
165     * @param state Turnout state to act on, eg. Turnout.CLOSED or Turnout.THROWN
166     */
167    void setControlTurnoutState(int state);
168
169    /**
170     * Get the Timed On Trigger Sensor name.
171     *
172     * @return  The Sensor Name as set by #setControlTimedOnSensorName
173     */
174    String getTimedSensorName();
175
176    /**
177     * Get the Timed On Trigger Sensor name.
178     *
179     * @return  If a Sensor is registered, returns the Sensor.getName()
180     *          else the Sensor Name as set by #setControlTimedOnSensorName
181     */
182    String getControlTimedOnSensorName();
183
184    /**
185     * Set Sensor used by the Timed On Control
186     * Does NOT update any changelisteners
187     *
188     * @param sensorName the Sensor name to be used for the On Trigger
189     */
190    void setControlTimedOnSensorName(String sensorName);
191
192    /**
193     * Get the Timed On Control Duration
194     *
195     * @return duration in ms
196     */
197    int getTimedOnDuration();
198
199    /**
200     * Set Duration used by the Timed On Control
201     * Does NOT update any changeListeners
202     *
203     * @param duration in ms following the Sensor On Trigger
204     */
205    void setTimedOnDuration(int duration);
206
207    /**
208     * Get the Second Sensor name.
209     * as used in the 2 Sensor Control Group.
210     *
211     * @return  If a 2nd Sensor is registered, returns the Sensor.getName()
212     *          else the 2nd Sensor Name as set by #setControlSensor2Name
213     */
214    String getControlSensor2Name();
215
216    /**
217     * Set Sensor 2 used by the 2 Sensor Control
218     * Does NOT update any changelisteners
219     *
220     * @param sensorName the Sensor 2 name
221     */
222    void setControlSensor2Name(String sensorName);
223
224    /**
225     * Set Light to control
226     * Does NOT update any changelisteners
227     *
228     * @param l the Light object to control
229     */
230    void setParentLight(Light l);
231
232    /**
233     * Get a Textual Description
234     * eg. Light Control TestLight ON when TestSensor is Active
235     * eg. Light Control ON at 14:00, OFF at 15:00.
236     * 
237     * @param lightName the Light Name, can be empty.
238     * @return An I18N full-text description of thiscontrol
239     */
240    String getDescriptionText(String lightName);
241
242    /**
243     * Activates a Light Control by control type. This method tests the control
244     * type, and set up a control mechanism, appropriate for the control type.
245     * Adds PropertyChangeListeners to Sensors / Turnout / Fast Clock as necessary
246     */
247    void activateLightControl();
248    
249    /**
250     * Check to see if we have the FastClock Follower has unique times for a single Light Control.
251     * <p>
252     * Hour / Minute combination must be unique for each Light to avoid flicker.
253     * 
254     * @return true if the clock on time equals the off time, otherwise false.
255     */
256    boolean onOffTimesFaulty();
257    
258    /**
259     * Check to see if we have the FastClock Follower has unique times for a single Light.
260     * <p>
261     * Hour / Minute combination must be unique for each Light to avoid flicker.
262     * 
263     * @param compareList the ArrayList of other Light Controls to compare against
264     * @return true if there are multiple exact same times
265     */
266    boolean areFollowerTimesFaulty( List<LightControl> compareList );
267    
268    /**
269     * Deactivates a LightControl by control type. This method tests the control
270     * type, and deactivates the control mechanism, appropriate for the control
271     * type.
272     */
273    void deactivateLightControl();
274
275}