1   package interfaces;
2   
3   /**
4   * Interface class for all controllers.
5   *
6   * All Controllers must extend this abstract class, and should obey the commands
7   * specified or system behaviour is undefined. e.g. a call to halt() *must* stop 
8   * this controller's thread as quickly as possible and allow run() to return.
9   *
10  * @author Graham Ritchie, modified by: Simon Zienkiewicz
11  */
12  public abstract class Controller extends Thread
13  {
14  
15      /** Constant for sensor of type light.
16       * Sensor type constants (see getSensors() for explanation)
17       */
18      public static int SENSOR_TYPE_LIGHT=1;
19      /** Constant for sensor of type touch.
20       * Sensor type constants (see getSensors() for explanation)
21       */    
22      public static int SENSOR_TYPE_TOUCH=2;
23  
24      /**
25      * Initialises controller. It should be noted that this method will only
26      * ever be called once, whereas run() can be called many times, so any
27      * variables or data structures etc. that are meant to persist in between
28      * stops and starts of the controller's thread, or that should only be 
29      * initialised once should be set up from within this method, not in run().
30      *
31      * @param r the AbstractRobot associated with this controller
32      */
33      public abstract void initController(AbstractRobot r);
34      
35      /**
36      * Returns the AbstractRobot associated with this controller
37      *
38      * @return the AbstractRobot
39      */
40      public abstract AbstractRobot getRobot();
41  
42      /**
43      * Returns an array of the sensors used by this controller, and the type
44      * of sensor required. This type must be one of the sensor type constants
45      * declared above. The index of the array is used to establish which sensor
46      * is being defined. e.g. if array[0] is SENSOR_TYPE_TOUCH then sensor 1 
47      * will be set to a touch sensor. The sensors array *must* be initialised
48      * with the correct values from the outset, and must not be set in 
49      * initController(), or any other method. (see example Controllers for 
50      * working examples)
51      *
52      * @return the sensor array
53      */
54      public abstract int[] getSensors();
55      
56      /**
57      * Stops this controller's thread running, i.e. must allow run() to return
58      * as quickly as possible. However it is acceptable for this method to do 
59      * some housekeeping before stopping the controller, e.g. save some internal
60      * data strcuture to a file.
61      */
62      public abstract void halt();
63  
64      /** This method is called whenever a LIGHT SENSOR detects change from its previous value.
65       * @param sensorNumber this is the LIGHT SENSOR number that called this method
66       */
67      public abstract void lightSensorListener(int sensorNumber);
68  
69      /** This method is called whenever a TOUCH SENSOR detects change from its previous value.
70       * @param sensorNumber this is the TOUCH SENSOR number that called this method
71       */
72      public abstract void touchSensorListener(int sensorNumber);
73      
74      /**
75      * Starts this controller's thread running. The 'real' controller 
76      * functionality should be started from here.
77      */
78      public abstract void run();
79      
80      /** Whenever a timer elapses this method is called and the timer which
81       * elapsed is passed as a parameter
82       * @param elapsedTimer the timer which elapsed
83       */
84      public abstract void setTimerExecution(int elapsedTimer);
85      
86  }
87