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;
19  
20  import com.tomgibara.pronto.state.StateEngine;
21  
22  /**
23   * A Controller manipulates a state engine in response to events in an
24   * application's environment. Implementations of this interface are produced by
25   * the control factory.
26   * 
27   * @param <S>
28   *            the type of state supported on the state engine for the controller
29   * @param <L>
30   *            the type of label supported on the state engine for the controller
31   * @param <P>
32   *            the type of parameter supported on the state engine for the
33   *            controller
34   * 
35   * @author Tom Gibara
36   */
37  
38  public interface Controller<S, L, P> {
39  
40      // lifecycle methods
41  
42      /**
43       * Starts the controller. If the controller has already been started, no
44       * action is taken.
45       */
46  
47      void start();
48  
49      /**
50       * Stops the controller. If the controller has already been stopped, or has
51       * not yet been started, the method returns immediately with the value true.
52       * 
53       * @param timeout
54       *            the number of milliseconds that the calling thread is willing
55       *            to wait for stoppage to occur, 0L waits indefinitely.
56       * @return true if the controller is not running, false otherwise.
57       */
58  
59      boolean stop(long timeout);
60  
61      // accessors
62  
63      /**
64       * The engine through which this controller operates.
65       * 
66       * @return the engine used by this controller
67       */
68  
69      StateEngine<S, L, P> getEngine();
70  
71      /**
72       * The adapter that is being used by the controller to mediate external
73       * events and the state graph.
74       * 
75       * @return the adapter used by this controller
76       */
77  
78      EngineControlAdapter<S, L, P> getAdapter();
79  
80  }