View Javadoc

1   /*
2    * Copyright (C) 2006  Tom Gibara
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
17   */
18  package com.tomgibara.pronto.control.impl;
19  
20  /**
21   * Controller parts provide the settings-specific functionality of a controller.
22   * Any number of parts may be aggregated into a single controller. No part
23   * should change the state engine's state before being started, or after being
24   * stopped. A single part may be stopped and started any number of times.
25   * 
26   * @param <S>
27   *            the type of state
28   * @param <L>
29   *            the type of label
30   * @param <P>
31   *            the type of parameter
32   * 
33   * @author Tom Gibara
34   * 
35   */
36  
37  interface ControllerPart<S, L, P> {
38  
39      // lifecycle methods
40  
41      /**
42       * Causes the controller part to start monitoring. The part should have
43       * completed its starting before returning. If this method is called after
44       * the part has already been started, no action should be peformed and the
45       * method should return normally.
46       */
47  
48      void start();
49  
50      /**
51       * Causes the controller part to stop. The controller should make a sensible
52       * effort to stop before the timeout has elapsed. If this method is called
53       * after the part has already been stopped (or before it has been started),
54       * no action should be peformed and the method should return successfully.
55       * 
56       * @param timeout
57       *            the number of milliseconds for which the calling thread is
58       *            willing to wait for stoppage to complete
59       * @return true if the part stopped successfully (or was already stopped)
60       *         false otherwise.
61       */
62  
63      boolean stop(long timeout);
64  
65      // accessors
66  
67      /**
68       * The controller of which this is part.
69       * 
70       * @return the controller that aggregates this part.
71       */
72  
73      ControllerImpl<S, L, P> getController();
74  
75  }