[kepler-users] Error handling

[Christopher Brooks]

Hi Barbara,
There are two types of exceptions.
The primary type of exceptions are Java exceptions that occur in the
Java code.

See section 6.4.4 of the Ptolemy II Coding Style document at
http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/ptII/doc/coding/index.htm
Which I've reproduced below.

The ThrowModelError and ThrowException actors throw what we call "model errors"
which are handled by passing the error up the containment hierarchy until
a container handles the error.

The ThrowModelError class comment says:
--start--
<p>An actor that throws a model error when it receives a true token
  on any input channel.  The message reported in the model error is
  given by the <i>message</i> parameter.
  The inputs are read and checked in the postfire() method only.
  </p><p>
  A model error is an exception that is passed up the containment
  hierarchy rather than being immediately thrown. Any container
  in the containment hierarchy may choose to handle the error.
  By default, containers will pass and delegate the error to their
  container, if they have one, and throw an exception if they
  don't. But some containers might do more with the error.</p>
...
  @see ptolemy.kernel.util.NamedObj#handleModelError(NamedObj, IllegalActionException)
--end--


I don't think we have a model that has a container that handles model
errors.

I took a look at some old email and it looks like handleModelError was created
to handle problems with Settables that are in an invalid state.  This
came up when the solver step size would be set.  It looks like Finite State
Machines use this mechanism.  Searching the code for "handleModelError"
is somewhat illuminating.  Edward might have some comments about this.

If you wanted to use this mechanism, then I think you would need to create
a container that extended TypedCompositeActor and had a handleModelError()
method that did what you want.

An alternative method is to use the Stop actor to stop execution.  There
are a few examples of using Stop.


Below is the section from the coding style doc.

_Christopher


--start--
6.4.4 Exceptions
A number of exceptions are provided in the ptolemy.kernel.util package. Use these exceptions when possible because they provide convenient constructor arguments of type Nameable that identify the 
source of the exception by name in a consistent way.

A key decision you need to make is whether to use a compile-time exception or a run-time exception. A run-time exception is one that implements the RuntimeException interface. Run-time exceptions are 
more convenient in that they do not need to be explicitly declared by methods that throw them. However, this can have the effect of masking problems in the code.

The convention we follow is that a run-time exception is acceptable only if the cause of the exception can be tested for prior to calling the method. This is called a testable precondition. For 
example, if a particular method will fail if the argument is negative, and this fact is documented, then the method can throw a run-time exception if the argument is negative. On the other hand, 
consider a method that takes a string argument and evaluates it as an expression. The expression may be malformed, in which case an exception will be thrown. Can this be a run-time exception? No, 
because to determine whether the expression is malformed, you really need to invoke the evaluator. Making this a compile-time exception forces the caller to explicitly deal with the exception, or to 
declare that it too throws the same exception. In general, we prefer to use compile-time exceptions wherever possible.

When throwing an exception, the detail message should be a complete sentence that includes a string that fully describes what caused the exception. For example

throw IllegalActionException(this,
         "Cannot append an object of type: "
                 + obj.getClass().getName() + " because "
                 + "it does not implement Cloneable.");


Note that the exception not only gives a way to identify the objects that caused the exception, but also why the exception occurred. There is no need to include in the message an identification of the 
"this" object passed as the first argument to the exception constructor. That object will be identified when the exception is reported to the user.

If an exception is caught, be sure to use exception chaining to include the original exception. For example:


String fileName = foo();
try {
     // Try to open the file
} catch (IOException ex) {
     throw new IllegalActionException(this, ex,
             "Failed to open '" + fileName + "'");
}

--end--

Barbara Lerner wrote:
> Hi,
> 
>   I am new to Kepler and I am trying to understand how exception 
> handling is done in Kepler.  I see two actors:  Throw Exception and 
> Throw Model Error.  From the documentation, it seems that using Throw 
> Model Error would allow one to catch the error elsewhere in the 
> workflow, but I don't see any discussion of how I would do that.  Can 
> someone explain this or point me to the documentation that does?
> 
> Thanks,
>   Barbara
> 
> ------------------
> 
> Barbara Lerner                                                  "Power 
> to the peaceful"
> Associate Professor                                                  -- 
> Michael Franti
> Computer Science Dept.
> Mt. Holyoke College
> 
> 
> 
> 
> _______________________________________________
> Kepler-users mailing list
> Kepler-users at kepler-project.org
> http://mercury.nceas.ucsb.edu/kepler/mailman/listinfo/kepler-users

-- 
Christopher Brooks, PMP                       University of California
CHESS Executive Director                      US Mail: 337 Cory Hall
Programmer/Analyst CHESS/Ptolemy/Trust        Berkeley, CA 94720-1774
ph: 510.643.9841 fax:510.642.2718	      (Office: 545Q Cory)
home: (F-Tu) 707.665.0131 cell: 707.332.0670