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
11  */
12  public abstract class Controller extends Thread
13  {
14  
15      /**
16      * Sensor type constants (see getSensors() for explanation)
17      */
18      public static int SENSOR_TYPE_LIGHT=1;
19      public static int SENSOR_TYPE_TOUCH=2;
20      
21      /**
22      * Initialises controller. It should be noted that this method will only
23      * ever be called once, whereas run() can be called many times, so any
24      * variables or data structures etc. that are meant to persist in between
25      * stops and starts of the controller's thread, or that should only be 
26      * initialised once should be set up from within this method, not in run().
27      *
28      * @param r the AbstractRobot associated with this controller
29      */
30      public abstract void initController(AbstractRobot r);
31      
32      /**
33      * Returns an array of the sensors used by this controller, and the type
34      * of sensor required. This type must be one of the sensor type constants
35      * declared above. The index of the array is used to establish which sensor
36      * is being defined. e.g. if array[0] is SENSOR_TYPE_TOUCH then sensor 1 
37      * will be set to a touch sensor. The sensors array *must* be initialised
38      * with the correct values from the outset, and must not be set in 
39      * initController(), or any other method. (see example Controllers for 
40      * working examples)
41      *
42      * @return the sensor array
43      */
44      public abstract int[] getSensors();
45      
46      /**
47      * Starts this controller's thread running. The 'real' controller 
48      * functionality should be started from here.
49      */
50      public abstract void run();
51  
52      /**
53      * Stops this controller's thread running, i.e. must allow run() to return
54      * as quickly as possible. However it is acceptable for this method to do 
55      * some housekeeping before stopping the controller, e.g. save some internal
56      * data strcuture to a file.
57      */
58      public abstract void halt();
59  
60      /**
61      * Returns the AbstractRobot associated with this controller
62      *
63      * @return the AbstractRobot
64      */
65      public abstract AbstractRobot getRobot();
66  }
67