01 /*
02 * Copyright (c) 1995-2010, The University of Sheffield. See the file
03 * COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
04 *
05 * This file is part of GATE (see http://gate.ac.uk/), and is free
06 * software, licenced under the GNU Library General Public License,
07 * Version 2, June 1991 (in the distribution as file licence.html,
08 * and also available at http://gate.ac.uk/gate/licence.html).
09 *
10 * Ian Roberts 04/07/2007
11 *
12 * $Id: ControllerAwarePR.java 12006 2009-12-01 17:24:28Z thomas_heitz $
13 */
14 package gate.creole;
15
16 import gate.Controller;
17 import gate.ProcessingResource;
18
19 /**
20 * <p>
21 * This interface should be implemented by processing resources that
22 * need to know when any containing controller starts and ends its
23 * execution, for example to initialise internal data structures or to
24 * do some aggregate processing of data gathered from a whole corpus.
25 * </p>
26 *
27 * <p>
28 * If a controller contains several PRs that implement this interface,
29 * the order in which their <code>controllerExecutionStarted</code> (<code>Finished</code>
30 * or <code>Aborted</code>) methods are called is not specified. In
31 * particular, the "ended" methods may be called in a different order
32 * from the "started" ones. Also, if one PR throws an exception from its
33 * <code>controllerExecutionFinished</code> method, the other finished
34 * methods may not be called at all for this run. PRs should be robust
35 * to this possibility.
36 * </p>
37 *
38 * <p>
39 * The controller should call this PRs started and finished (or aborted)
40 * methods at most once per run, even if the controller allows the same
41 * PR to be added multiple times.
42 * </p>
43 */
44 public interface ControllerAwarePR extends ProcessingResource {
45 /**
46 * Called by a controller containing this PR when the controller
47 * begins executing. When this method is called, it is guaranteed that
48 * none of the PRs in this controller have yet been
49 * <code>execute</code>d on this run.
50 *
51 * @param c the {@link Controller} that is executing.
52 * @throws ExecutionException if an error occurs that requires the
53 * controller to abort its execution.
54 */
55 public void controllerExecutionStarted(Controller c)
56 throws ExecutionException;
57
58 /**
59 * Called by a controller containing this PR when the controller's
60 * execution has completed successfully. When this method is called,
61 * it is guaranteed that there will be no more calls to the
62 * <code>execute</code> method of any of this controller's PRs in
63 * this run.
64 *
65 * @param c the {@link Controller} that is executing.
66 * @throws ExecutionException if an error occurs that requires the
67 * controller to abort its execution.
68 */
69 public void controllerExecutionFinished(Controller c)
70 throws ExecutionException;
71
72 /**
73 * Called by a controller containing this PR when the controller's
74 * execution has been aborted by an exception thrown by one of the
75 * contained PR's <code>execute</code> methods, or by the controller
76 * itself. When this method is called, it is guaranteed that there
77 * will be no more calls to the <code>execute</code> method of any
78 * of this controller's PRs in this run.
79 *
80 * @param c the {@link Controller} that is executing.
81 * @param t the <code>Throwable</code> that caused the controller to
82 * abort. This will be either an {@link ExecutionException},
83 * a {@link RuntimeException} or an {@link Error}.
84 * @throws ExecutionException if an error occurs in this method that
85 * requires the controller to abort its execution. This
86 * method should not rethrow <code>t</code>, as the
87 * controller will do this after informing any other
88 * <code>ControllerAware</code> PRs it contains.
89 */
90 public void controllerExecutionAborted(Controller c, Throwable t)
91 throws ExecutionException;
92 }
|