# Handling Errors through Predefined Business Component Exception Classes

Use exceptions to indicate serious or unexpected error conditions, conditions from which the program cannot easily recover. This topic presents the following information:

- About Java exceptions

- About exception classes

- Returning a Localized Error Message

- Marshaling Exceptions Across a Network

## About Java Exceptions

Java exceptions fall into two categories: either they extend `java.lang.RuntimeException` (these are called implicit exceptions) or they do not (these are called explicit exceptions). When a method uses an explicit exception to indicate an error, a Java program requires:

- A `throws` clause in the method signature that declares the type of exception the method will throw when an error occurs.

- A `throw` statement in the method body that creates and throws an exception of the type specified in the signature.

The following code shows a method `getCustName` that declares and throws a `ValidationException`.

    public String getCustName(Customer cust) throws ValidationException {
      String name = cust.mName;
      if (name == null) {
        throw new ValidationException();
      }
      return name;
    }

When you write code that calls a method that throws an exception, enclose the call in a`try...catch` block. For example, the following code calls `getCustName`, a method defined to throw a `ValidationException`. The `try` keyword indicates that you are about to call one or more methods that throw exceptions. The `catch` keyword marks the beginning of a code block that executes only when an exception is thrown.

    public printName(Customer cust) {
      try {
        // Call the method(s) here.
        getCustName(cust);
      catch (ValidationException dae) {

        // Handle the error here.
        System.out.println(dae.getMessage());
      }
    }

Java programs are more lenient about implicit exceptions: they do not have to be declared or caught. You can write a method that throws a `RuntimeException` (or a subclass of `RuntimeException`) without declaring it in the method signature (although you can do so, if you prefer).

## About Exception Classes

The Business Components for Java framework provides many exception classes (for example, `ValidationException` and `NameClashException`). These classes extend `oracle.jbo.JboException`, which extends `java.lang.RuntimeException`. Therefore, a Business Component method can throw a Business Components for Java exception without a `throws` clause in the signature.

Business Components for Java exceptions have an attribute that stores an error message, and they support NLS translation and message formatting. `JboException` uses `java.util.ListResourceBundle` to format its messages. A resource bundle class defines constants and strings to use as error messages. The default format is:

    {productCode}-{errorCode}: {messageBody}

For example,

    ORA-10234: You cannot do that.

Business Component exception messages are derived from the following generalized set of parameters:

Parameter | Example
Product code | "OBCJ"
Error code | "03101"
ResourceBundle | "oracle.jbo.CSMessageBundle"
an optional set of parameters | "Vendor", "Oracle"
details | Any exception thrown in low-level code that is transformed into a Business Component exception.

Messages may need to include information known only when the exception is thrown, so error message strings can include placeholders that refer to values in an array of Objects passed to the exception when it's thrown. When the message is formatted for display, these parameters are placed into slots in the message (the first slot is 0) using the standard formatting capabilities provided by `java.text.MessageFormat`. Following is a an entry from `CSMessageBundle.java`.

    public static final String EXC_VAL_ATTR_SET_FAILED = "03101";
    ...
    // Description: Generic Attribute validation failure.
    //              set<Attribute> method failed to set the value.
    // Parameter 0: Ignored.
    // Parameter 1: Entity Object/View Object name.
    // Parameter 2: Attribute name.
    // Parameter 3: New value
    {EXC_VAL_ATTR_SET_FAILED, "Attribute set with value {3} for {2} in {1} failed."},

The `JboException` class provides the following methods for working with exceptions.

Method | Description
    JboException(String message,
                 String errorCode,
                 Object[] params)
| Create a Formattable Exception Object.
    JboException(Class resBundleClass,
                 String errorCode,
                 Object[] params)
| Create a Translatable Exception Object.
    String getProductCode()
| Return the Product code for the Message.
    String getErrorCode()
| Return the Error code.
    String getLocalizedMessage(Locale loc)
| Return the Message in the specific Locale.
    Object[] getDetails()
| Details are usually used to accommodate lower-level exceptions. For example, if a `SQLException` is thrown in some low-level code, the Business Components for Java framework can catch it and represent it as one of the Business Component exceptions. The original`SQLException` becomes the first entry in the detail.
    String getResourceName()
| Return the name of the ResourceBundle used to resolve messages.
    Object[] getErrorParameters()
| Return the Parameters to the Error.

## Using JboExceptionHandler

`JboExceptionHandler` is user-installable exception handler for three-tier applications. When exceptions are brought over through the piggyback mechanism, the normal Java language throw does not quite work, because (among other things) the piggyback may have carried back more than one exceptions. Thus, instead of throwing the exception, a method on the `JboExceptionHandler` interface is invoked with each exception unloaded from the piggyback.

`JboExceptionHandler` defines:

    void handleException(Exception ex, boolean lastEntryInPiggyback);

Where `ex` is the exception unloaded from the piggyback and `lastEntryInPiggyback` is a flag indicating whether the exception was the last entry on the piggyback. (Note that for two-tier execution there is no piggyback.)

If you do not install your own handler, the default handler is used. The default handler is implemented by the Application Module. (At the interface level, `ApplicationModule` implements `JboExceptionHandler`.) For `jbo.client.remote`, this implementation ignores the exception if `lastEntryInPiggyback` is false. If `lastEntryInPiggyback` is true, the exception is thrown.

To install your own handler, call the following method on the Application Module interface:

    void setExceptionHandler(JboExceptionHandler hndlr);

and pass in your own implementation of the `JboExceptionHandler` interface.

##