001/* A listener for events from a manager.
002
003 Copyright (c) 1997-2005 The Regents of the University of California.
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024 PT_COPYRIGHT_VERSION_2
025 COPYRIGHTENDKEY
026
027 */
028package ptolemy.actor;
029
030//////////////////////////////////////////////////////////////////////////
031//// ExecutionListener
032
033/**
034 An ExecutionListener listens for events that are issued
035 during the execution of a model by a Manager.   In general, an
036 object that implements this interface will probably be a front end such
037 as an applet, a GUI, or a command-line interpreter,
038 or an object that is communicating with a front end. Most of the
039 events that are reported are state changes in the manager.
040 <p>
041 Some execution events happen in response to an asynchronous
042 request.  For example, when the pause() method of a manager is
043 called, a flag is set, and at the end of the next toplevel
044 iteration, the manager will notice the flag and pause execution. In
045 such cases, the execution listeners are not notified when the
046 request occurs, but only when the execution thread has actually
047 been suspended.
048
049 @author Steve Neuendorffer, Edward A. Lee
050 @version $Id$
051 @since Ptolemy II 0.2
052 @Pt.ProposedRating Green (neuendor)
053 @Pt.AcceptedRating Green (bart)
054 @see Manager
055 */
056public interface ExecutionListener {
057    /** Report an execution failure.   This method will be called
058     *  when an exception or error is caught by a manager.
059     *  Exceptions are reported this way when the run() or startRun()
060     *  methods of the manager are used to perform the execution.
061     *  If instead the execute() method is used, then exceptions are
062     *  not caught, and are instead just passed up to the caller of
063     *  the execute() method.  Those exceptions are not reported
064     *  here (unless, of course, the caller of the execute() method does
065     *  so).
066     *
067     *  @param manager The manager controlling the execution.
068     *  @param throwable The throwable to report.
069     */
070    public void executionError(Manager manager, Throwable throwable);
071
072    /** Report that the current execution has finished and
073     *  the wrapup sequence has completed normally. The number of successfully
074     *  completed iterations can be obtained by calling getIterationCount()
075     *  on the manager.
076     *
077     *  @param manager The manager controlling the execution.
078     */
079    public void executionFinished(Manager manager);
080
081    /** Report that the manager has changed state.
082     *  To access the new state, use the getState() method of Manager.
083     *
084     *  @param manager The manager controlling the execution.
085     *  @see Manager#getState()
086     */
087    public void managerStateChanged(Manager manager);
088}