Contents Previous Next

Throwing and Handling Exceptions

Raising and reporting exceptions correctly is critical to the usability and maintenance of any system. This section describes how the SCM Framework deals with the exceptions thrown from classes in your source code control extension and how to use them to your advantage, specifically:

Many of the methods in the oracle.ide.scm package classes of the SCM Framework can throw an oracle.ide.scm.error.SCMException instance or derivative type exception. This applies to both the SCM Framework and your source code control extension.

If you throw one of these exceptions from a method in your source code control extension, the SCM Framework knows that your processing has failed and that it should inform the user promptly.

Note: How JDeveloper informs the user of an exception depends on the type of exception thrown. Judge the severity of each error and decide which exception class you need to use.

There are several significant exception classes in the SCM Framework, inherited directly from SCMException:

Hint: You can instantiate these exception classes, but we recommend that you create specific exception subclasses for your extension. Using your own subclasses can help to identify where and why an exception occurs and provide a clearer explanation to the user.

Back to top

Serious or 'Detailed' Exceptions

For serious and unexpected errors for which the user needs a detailed description, e.g. when an 'illegal' state occurs from which the SCM Framework may not be able to recover, throw an instance of SCMDetailException. Normally, you create a detailed exception for a target throwable.

import oracle.ide.scm.SCMFile;
import oracle.ide.scm.SCMOptions;
import oracle.ide.scm.error.SCMException;
import oracle.ide.scm.error.SCMDetailException;

...

public void execute( SCMFile file, SCMOptions options )
  throws SCMException
{
  BufferedReader in;
  try
  {
    in = new BufferedReader( new FileReader( file.toFile() ) );
    ...
  }
  catch (FileNotFoundException fnfe)
  {
    throw new ACMEIOException(
      "Could not open file at location " + file + " - not found.", 
      fnfe
    );
  }
}
...

class ACMEIOException extends SCMDetailException
{
  ACMEIOException(String msg, IOException ioe) { super( MSG, ioe ); }
}

The dialog for a serious exception includes a stack trace for the user's reference that they can display or hide as appropriate.

Back to top

User or 'Minimal' Exceptions

For simple errors for which the user needs only a brief description, e.g. when they do something wrong like entering invalid data, throw an instance of SCMMinimalException.

The user normally sees a short message for these types of error, so the dialog displayed contains a simple panel with message text.

Back to top

Informative or 'Extended' Exceptions

For those errors for which the user may need further information, throw an instance of SCMExtendedException. Informative exceptions are appropriate when a non-critical, but 'illegal' state occurs and the user needs help on how to recover from this position.

The user normally sees two messages; the basic message and a second extended message explaining the position and how to recover from it. The dialog for this type of exception contains a simple panel with the message text.

Back to top

Silent or 'Gesture' Exceptions

For errors where the user should not receive any further details, e.g. when the user cancels one or more actions such as canceling a Check In dialog, throw an instance of SCMGestureException.

This type of error is not associated with any message text and so there is no user interface.

Back to top

ACME VCS Sample

The sample file ACMEVCSClient.java demonstrates how to throw and handle exceptions.

For more details on ACME VCS, see Introduction.

Back to top

Contents Previous Next