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