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

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:

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.