Page History

Default handling:

IStatus status = new Status(IStatus.ERROR, MyPlugin.PLUGIN_ID, message, exception);
StatusManager.getManager().handle(status);

If you want to force the status manager to display the error in a dialog, pass the option StatusManager.SHOW.

How to Throw an Exception

The throwable classes are Error, Exception, and RuntimeException. You should choose to throw either an Exception or a RuntimeException. In the first case you must specify the exception in the method's throws declaration (checked exception), in the latter case this is not required (unchecked exception). In most cases it is advisable to throw a more specific subclass in order to give a hint on what has happened.

• Checked exceptions
  • KielerModelException
    Thrown when a problem occurs with a certain model element.
  • TransformException
    Thrown when a problem occurs during a model transformation.
• Unchecked exceptions
  • IllegalStateException
    Thrown when the class is in an illegal state, e.g. some class variables have incorrect values or are not compatible with the method parameters.
  • UnsupportedOperationException
    Thrown when a method is not implemented by a concrete subclass or a specific feature given by parameters is not supported.
  • IllegalArgumentException
    Thrown when method parameters have invalid values.
  • WrappedException
    Used to wrap a checked exception into an unchecked one.
  • UnsupportedPartException
    Thrown when no graphical framework bridge is found for an editor part or edit part instance.
  • UnsupportedGraphException
    Thrown when a layout algorithm is executed on a graph that is not supported.

Another hint: often some cleanup code is required that needs to be executed in case of an exception as well as in the normal case. Use a finally block to do this! You can also make a try ... finally block without any catch block, which is very useful.

Checked or Unchecked?

Checked exceptions have the advantage that it is explicitly visible that such an exception can occur and must be handled in some way. They should be used when specific problems are likely to occur and it is known in advance what kind of problems must be covered. A good example is IOException.

Unchecked exceptions have the advantage that it is not required to attach throws declarations for any type of exception that can occur in any part of the call tree. They should be used when it is not known in advance what kind of problems can occur or the problems may occur only in a very deep part of the call tree. This applies to programming errors, which may invoke unchecked exceptions such as NullPointerException or IndexOutOfBoundsException and should always be made visible to the user. Often it is also useful to wrap exceptions into unchecked exceptions:

try {
    // ...
} catch (IOException e) {
    throw new WrappedException("Oh no, the input file wasn't found!", e);
}

Platform Independence

Always try to separate user interface code from conceptual or algorithmic code. This avoids dependencies on GUI stuff in pure algorithm projects, such as KLay. A big concern is to avoid Eclipse dependencies in KIELER's base plug-ins to make the code as portable as possible. Other people might want to use it, but might not be developing Eclipse-based projects.

That being said, Eclipse is still the main platform for KIELER, and many projects are tightly integrated with it.

Special KIELER Issues

In order to stay platform-independent, KIELER handles preferences and algorithm progress monitoring independently of Eclipse. Thus, don't use the standard mechanisms, but the KIELER ones:

• IKielerPreferenceStore
  Wrapper for an Eclipse Preference Store. An UI plug-in could set a static reference to an IKielerPreferenceStore in a non-GUI-plug-in to a standard Eclipse PreferenceStore. The non-GUI-Plugin would just use the KIELER interface and would avoid dependencies on Eclipse. In a different Environment the Interface could be implemented by some other prefs mechanism of the corresponding platform.
• IKielerProgressMonitor
  This is just the same idea for a progress monitor, which is very useful when executing long running algorithms. Such also the algorithm (with no dependencies on UI elements or Eclipse) need to access the progress monitor in order to report any progress. The KIELER implementation adds neat features such as execution time measurement.