ControllerAwarePR.java
001 /*
002  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
003  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
004  *
005  *  This file is part of GATE (see http://gate.ac.uk/), and is free
006  *  software, licenced under the GNU Library General Public License,
007  *  Version 2, June 1991 (in the distribution as file licence.html,
008  *  and also available at http://gate.ac.uk/gate/licence.html).
009  *
010  *  Ian Roberts 04/07/2007
011  *
012  *  $Id: ControllerAwarePR.java 15333 2012-02-07 13:18:33Z ian_roberts $
013  */
014 package gate.creole;
015 
016 import gate.Controller;
017 import gate.ProcessingResource;
018 
019 /**
020  <p>
021  * This interface should be implemented by processing resources that
022  * need to know when any containing controller starts and ends its
023  * execution, for example to initialise internal data structures or to
024  * do some aggregate processing of data gathered from a whole corpus.
025  </p>
026  <p>
027  * If a controller contains several PRs that implement this interface,
028  * the order in which their <code>controllerExecutionStarted</code> (<code>Finished</code>
029  * or <code>Aborted</code>) methods are called is not specified. In
030  * particular, the "ended" methods may be called in a different order
031  * from the "started" ones. Also, if one PR throws an exception from its
032  <code>controllerExecutionFinished</code> method, the other finished
033  * methods may not be called at all for this run. PRs should be robust
034  * to this possibility.
035  </p>
036  <p>
037  * If the processing resource implementing this interface is contained in
038  * a conditional controller the methods defined by this interface are invoked
039  * independently of the RunningStrategy for the processing resource: even if
040  * the PR is disabled, the methods will get invoked. The method
041  {@link gate.Utils#isEnabled(Controller, ProcessingResource)} can be used
042  * inside the implementation of the methods defined in this interface 
043  * if necessary to find out if the processing resource has a chance to run
044  * in the controller.
045  </p>
046  <p>
047  * The controller should call this PRs started and finished (or aborted)
048  * methods at most once per run, even if the controller allows the same
049  * PR to be added multiple times.
050  </p>
051  */
052 public interface ControllerAwarePR extends ProcessingResource {
053   /**
054    * Called by a controller containing this PR when the controller
055    * begins executing. When this method is called, it is guaranteed that
056    * none of the PRs in this controller have yet been
057    <code>execute</code>d on this run.
058    
059    @param c the {@link Controller} that is executing.
060    @throws ExecutionException if an error occurs that requires the
061    *           controller to abort its execution.
062    */
063   public void controllerExecutionStarted(Controller c)
064           throws ExecutionException;
065 
066   /**
067    * Called by a controller containing this PR when the controller's
068    * execution has completed successfully. When this method is called,
069    * it is guaranteed that there will be no more calls to the
070    <code>execute</code> method of any of this controller's PRs in
071    * this run.
072    
073    @param c the {@link Controller} that is executing.
074    @throws ExecutionException if an error occurs that requires the
075    *           controller to abort its execution.
076    */
077   public void controllerExecutionFinished(Controller c)
078           throws ExecutionException;
079 
080   /**
081    * Called by a controller containing this PR when the controller's
082    * execution has been aborted by an exception thrown by one of the
083    * contained PR's <code>execute</code> methods, or by the controller
084    * itself. When this method is called, it is guaranteed that there
085    * will be no more calls to the <code>execute</code> method of any
086    * of this controller's PRs in this run.
087    
088    @param c the {@link Controller} that is executing.
089    @param t the <code>Throwable</code> that caused the controller to
090    *          abort. This will be either an {@link ExecutionException},
091    *          a {@link RuntimeException} or an {@link Error}.
092    @throws ExecutionException if an error occurs in this method that
093    *           requires the controller to abort its execution. This
094    *           method should not rethrow <code>t</code>, as the
095    *           controller will do this after informing any other
096    *           <code>ControllerAware</code> PRs it contains.
097    */
098   public void controllerExecutionAborted(Controller c, Throwable t)
099           throws ExecutionException;
100 }