Use exceptions to indicate serious or unexpected error conditions, conditions from which the program cannot easily recover. This topic presents the following information:
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).
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 |
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, |
Create a Formattable Exception Object. |
JboException(Class resBundleClass, |
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 |
String getResourceName() |
Return the name of the ResourceBundle used to |
Object[] getErrorParameters() |
Return the Parameters to the Error. |
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.