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}