001/* An event representing the various changes in the state of a process in PN.
002
003 Copyright (c) 1997-2014 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.domains.pn.kernel.event;
029
030import ptolemy.actor.Actor;
031import ptolemy.kernel.Entity;
032import ptolemy.kernel.util.InternalErrorException;
033
034///////////////////////////////////////////////////////////////////
035//// PNProcessEvent
036
037/**
038 An event passed from a process executing under the PN semantics to a
039 PNProcessListener. This is used to
040 represent an event that happened during the execution of a topology.
041 This event contains two pieces of information:  the actor under the control
042 of the process and an exception that might be thrown.
043 The exception might not be a valid reference.
044
045 @author Mudit Goel
046 @version $Id$
047 @since Ptolemy II 0.3
048 @Pt.ProposedRating Yellow (mudit)
049 @Pt.AcceptedRating Red (cxh)
050 */
051public class PNProcessEvent {
052    /** Create a new event.
053     *  @param actor The actor
054     *  @param state The state of the actor, should be one of
055     *  PROCESS_BLOCKED, PROCESS_FINISHED, PROCESS_PAUSED
056     *  or PROCESS_RUNNING.
057     */
058    public PNProcessEvent(Actor actor, int state) {
059        this(actor, state, 0);
060    }
061
062    /** Create a new event that corresponds to an exception
063     *  caught by the process.
064     *  @param actor The actor.
065     *  @param state The state of the actor, should be one of
066     *  PROCESS_BLOCKED, PROCESS_FINISHED, PROCESS_PAUSED
067     *  or PROCESS_RUNNING.
068     *  @param cause The cause of the state.
069     */
070    public PNProcessEvent(Actor actor, int state, int cause) {
071        _actor = actor;
072
073        if (state < PROCESS_BLOCKED || state > PROCESS_RUNNING) {
074            throw new InternalErrorException(
075                    "state '" + state + "' is incorrect, it must be one of "
076                            + PROCESS_BLOCKED + ", " + PROCESS_FINISHED + ", "
077                            + PROCESS_PAUSED + " or " + PROCESS_RUNNING);
078        }
079
080        _state = state;
081        _cause = cause;
082    }
083
084    /** Create a new event that corresponds to an exception
085     *  caught by the process.
086     *  @param actor The actor.
087     *  @param exception The exception.
088     */
089    public PNProcessEvent(Actor actor, Exception exception) {
090        _actor = actor;
091        _state = PROCESS_FINISHED;
092        _cause = FINISHED_WITH_EXCEPTION;
093        _exception = exception;
094    }
095
096    ///////////////////////////////////////////////////////////////////
097    ////                    public methods                   /////
098
099    /** Return the actor corresponding to the process that generated
100     *  the event.
101     *  @return the actor corresponding to the process that generated
102     *  the event.
103     */
104    public Actor getActor() {
105        return _actor;
106    }
107
108    /** Return the cause of the blocking state.
109     *  @return an integer representing the cause of the blocking state.
110     */
111    public int getBlockingCause() {
112        return _cause;
113    }
114
115    /** Return the current state.
116     *  @return an integer representing the current state.
117     */
118    public int getCurrentState() {
119        return _state;
120    }
121
122    /** Return the exception associated with the event.
123     *  @return The exception associated with the event.
124     */
125    public Exception getException() {
126        return _exception;
127    }
128
129    /** Return the cause of the finishing state.
130     *  @return an integer representing the cause of the finishing state
131     */
132    public int getFinishingCause() {
133        return _cause;
134    }
135
136    /** Return the string value of this event.
137     *  @return The string value of this event.
138     */
139    @Override
140    public String toString() {
141        String result;
142        String state = null;
143        String cause = null;
144
145        if (_state == PROCESS_BLOCKED) {
146            state = "PROCESS_BLOCKED";
147
148            if (_cause == BLOCKED_ON_DELAY) {
149                cause = "BLOCKED_ON_DELAY";
150            } else if (_cause == BLOCKED_ON_MUTATION) {
151                cause = "BLOCKED_ON_MUTATION";
152            } else if (_cause == BLOCKED_ON_READ) {
153                cause = "BLOCKED_ON_READ";
154            } else if (_cause == BLOCKED_ON_WRITE) {
155                cause = "BLOCKED_ON_WRITE";
156            } else {
157                cause = "BLOCKING_CAUSE_UNKNOWN";
158            }
159
160            result = "State of " + ((Entity) _actor).getFullName() + " is "
161                    + state + " and the cause = " + cause;
162        } else if (_state == PROCESS_FINISHED) {
163            state = "PROCESS_FINISHED";
164
165            if (_cause == FINISHED_ABRUPTLY) {
166                cause = "FINISHED_ABRUPTLY";
167            } else if (_cause == FINISHED_PROPERLY) {
168                cause = "FINISHED_PROPERLY";
169            } else if (_cause == FINISHED_WITH_EXCEPTION) {
170                cause = "FINISHED_WITH_EXCEPTION with "
171                        + (_exception == null ? "null exception"
172                                : "exception " + _exception);
173            } else {
174                cause = "FINISHED_CAUSE_UNKNOWN";
175            }
176
177            result = "State of " + ((Entity) _actor).getFullName() + " is "
178                    + state + " and the cause = " + cause;
179        } else if (_state == PROCESS_PAUSED) {
180            state = "PROCESS_PAUSED";
181            result = "State of " + ((Entity) _actor).getFullName() + " is "
182                    + state;
183        } else if (_state == PROCESS_RUNNING) {
184            state = "PROCESS_RUNNING";
185            result = "State of " + ((Entity) _actor).getFullName() + " is "
186                    + state;
187        } else {
188            state = "UNKNOWN_PROCESS_STATE";
189            result = "State of " + ((Entity) _actor).getFullName() + " is "
190                    + state;
191        }
192
193        return result;
194    }
195
196    ///////////////////////////////////////////////////////////////////
197    ////                   public variables                  /////
198
199    /** A process is blocked on a delay. */
200    public static final int BLOCKED_ON_DELAY = 111;
201
202    /** A process is blocked on a mutation. */
203    public static final int BLOCKED_ON_MUTATION = 112;
204
205    /** A process is blocked on a read. */
206    public static final int BLOCKED_ON_READ = 113;
207
208    /** A process is blocked on a write. */
209    public static final int BLOCKED_ON_WRITE = 114;
210
211    /** A process finished abruptly. */
212    public static final int FINISHED_ABRUPTLY = 734;
213
214    /** A process finished properly. */
215    public static final int FINISHED_PROPERLY = 735;
216
217    /** A process finished with an exception. */
218    public static final int FINISHED_WITH_EXCEPTION = 736;
219
220    // These are legitimate states
221    /** The process is in the blocked state. */
222    public static final int PROCESS_BLOCKED = 367;
223
224    /** The process is in the finished state. */
225    public static final int PROCESS_FINISHED = 368;
226
227    /** The process is in the paused state. */
228    public static final int PROCESS_PAUSED = 369;
229
230    /** The process is in the running state. */
231    public static final int PROCESS_RUNNING = 370;
232
233    ///////////////////////////////////////////////////////////////////
234    ////                   private variables                      /////
235    private Actor _actor = null;
236
237    private int _cause = 0;
238
239    private Exception _exception = null;
240
241    private int _state = 0;
242}