public class JboException extends JboWarning
All exceptions thrown from the Business Components for Java framework should be subclasses of this exception.
This class provides a single point for the localization and formatting of Exception messages.
Translation of a message's text occurs at the time
the client calls getLocalizedMessage() rather than at
creation time since the client may need to present the message in
one of a number of different languages (refer to DAC for details).
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.
Most subclasses of JboException will provide a
value for the error code in a specialized constructor.
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.
The components of a Business Component exception messages are derived from the following generalized set of parameters:
|
Parameter |
Description |
|
Product code |
A non-translated product code string, such as FRM, ORA, or OBCJ |
|
Error code |
A non-translated error code string, such as 10234 or 03101 |
|
ResourceBundle |
Un-translated message text such as contained in
|
|
an optional set of parameters |
These can be message parameters, equal in number to the number of "%" symbols in the message text. Possible message parameter examples are: Vendor and Oracle. |
|
details |
A "details" list containing background information. This can be any exception thrown in low-level code that is transformed into a Business Component exception. |
Additional components may be introduced in future.
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."},
Applications may define subclasses of most JBO exceptions. To do this the application should override the following methods to provide the correct set of values for the messaging services:
You can use Business Component for Java exception classes in your own code to indicate errors, and you can create custom exception classes. For example, you can extend JboException and override the getProductCode method, making it return values appropriate for your exception.
You can throw a JboException by using a statement like this:
throw new JboException("Don't do that.", "101", null );
The drawback to this approach is that the hard-coded error message is not easy to localize.
To make an exception localizable into different national languages, use the NLS framework. First, create a resource bundle for your error messages. The following code example defines a bundle named MyMsgBundle that stores three error messages.
import oracle.jbo.common.util.CheckedListResourceBundle;
public class MyMsgBundle extends CheckedListResourceBundle
// String Constants
public static final String BAD_EMPNO = "101";
public static final String DEPT_NOT_FOUND = "102";
public static final String NOT_IN_DEPT = "103";
...
//Private 2-D array of key-value pairs
private static final Object[][] sMessageStrings = {
...
{ BAD_EMPNO, "Invalid employee number." },
{ DEPT_NOT_FOUND, "Department {0} does not exist." }
{ NOT_IN_DEPT, "Employee {0} not found in Department {1}." }
...
}
}
Then you can use the resource bundle class to define a value to pass to the constructor for your exception class or JboException:
ss
throw new JboException(MyMsgBundle.class // Class of Bundle
MyMsgBundle.DEPT_NOT_FOUND // String Constant
new Object[1] { localVar1 } //Arguments to message
);
JboException provides a getLocalizedMessage method which returns the message formatted for the specified locale.
The NLS framework translates the message text when the client calls getLocalizedMessage rather than at creation time because the client may need to present the message in a number of different languages. This mechanism provides a single point for localizing and formatting messages.
JboException can marshal itself across a network. It handles NLS issues for the middle tier, enabling one instance of a middle-tier component to serve (for example) French users and English users at the same time.
If your exception contains member data that must be marshalled, extend JboException. If you need to provide more control over the serialized stream, implement the readObject and writeObject methods. The Java serialization mechanism uses these methods to serialize/deserialize an object. You might want implement these methods if you want to:
exclude some members from being serialized
For example, suppose you have the class MyException (shown below), and you want to carry memberA and memberB across tiers:
public class MyException extends JboException
{
int memberA;
String memberB;
...
}
Write code like the following in MyException:
private void writeObject(ObjectOutputStream out) throws IOException {
out.writeInt(memberA);
out.writeUTF(mEntityRowHandle);
}
private void readObject(ObjectInputStream in) throws IOException,
ClassNotFoundException {
memberA = in.readInt();
memberB = in.readUTF();
}
| Modifier and Type | Field and Description |
|---|---|
protected boolean |
mHasPeerException |
HIDE_DETAIL_EXCEPTIONS_HINT, mHelper, SEVERITY_ERROR, SEVERITY_RAC_RECOVERABLE_ERROR, SEVERITY_RECOVERABLE_ERROR, SEVERITY_VETOABLE_WARNING, SEVERITY_WARNINGTYP_APP_MODULE, TYP_ATTRIBUTE, TYP_ATTRIBUTE_LIST_WITH_DEF, TYP_CATEGORY, TYP_COMPONENT_OBJECT, TYP_DATA_CONTROL, TYP_DEF_ANY, TYP_DEF_APP_MODULE, TYP_DEF_ASSOC_END, TYP_DEF_ATTRIBUTE, TYP_DEF_COMPONENT_OBJECT, TYP_DEF_DOMAIN, TYP_DEF_ENTITY_ASSOC, TYP_DEF_ENTITY_OBJECT, TYP_DEF_EXPRWHITELIST, TYP_DEF_KEY, TYP_DEF_LIST_BINDING, TYP_DEF_METHOD, TYP_DEF_OPERATION, TYP_DEF_OPERATION_PARAM, TYP_DEF_OPERATIONS, TYP_DEF_PACKAGE, TYP_DEF_ROWFINDER, TYP_DEF_VIEW_ACCESSOR, TYP_DEF_VIEW_ANNOT, TYP_DEF_VIEW_LINK, TYP_DEF_VIEW_LINK_END, TYP_DEF_VIEW_OBJECT, TYP_DOMAIN, TYP_ENTITY_ASSOC, TYP_ENTITY_OBJECT, TYP_ENTITY_ROW, TYP_ENTITY_ROW_SET, TYP_ENTITY_ROW_SET_ITERATOR, TYP_ENTITY_USAGE, TYP_PACKAGE, TYP_PERS_DEF_APP_MODULE, TYP_PERS_DEF_ATTRIBUTE, TYP_PERS_DEF_COMPONENT_OBJECT, TYP_PERS_DEF_DOMAIN, TYP_PERS_DEF_ENTITY_ASSOC, TYP_PERS_DEF_ENTITY_OBJECT, TYP_PERS_DEF_OFFSET, TYP_PERS_DEF_OPERATION, TYP_PERS_DEF_PACKAGE, TYP_PERS_DEF_VARIABLE, TYP_PERS_DEF_VIEW_LINK, TYP_PERS_DEF_VIEW_OBJECT, TYP_SERVICE_VIEW_USAGE, TYP_SORT_CRITERIA, TYP_TRANSACTION, TYP_TRIGGER_TYPE, TYP_VALIDATOR_TYPE, TYP_VARIABLE, TYP_VARIABLE_WHERE_CLAUSE, TYP_VIEW_CRITERIA, TYP_VIEW_CRITERIA_ITEM, TYP_VIEW_CRITERIA_ROW, TYP_VIEW_LINK, TYP_VIEW_OBJECT, TYP_VIEW_ROW, TYP_VIEW_ROW_SET, TYP_VIEW_ROW_SET_ITERATOR, TYP_VIEW_USAGE| Constructor and Description |
|---|
JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params)
Creates a translatable exception.
|
JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params,
java.lang.Exception[] excs)
Creates a translatable exception.
|
JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params,
JboException[] exceptions)
Creates a translatable exception.
|
JboException(ResourceBundleDef resBundleDef,
java.lang.String errorCode,
java.lang.Object[] params)
Creates a translatable exception.
|
JboException(java.lang.String message)
Create a non-formattable exception.
|
JboException(java.lang.String message,
java.lang.String errorCode,
java.lang.Object[] params)
Creates a formattable but non-localizable exception.
|
JboException(java.lang.Throwable ex)
Converts an exception into a non-formattable
JboException. |
| Modifier and Type | Method and Description |
|---|---|
void |
addToDetails(java.lang.Object obj)
Deprecated.
since 5.0. Instead use addToExceptions.
|
void |
addToExceptions(java.lang.Throwable exception)
Adds an exception to the list of detail exceptions.
|
boolean |
containsException(java.lang.Throwable e)
Returns true if this exception contains the given Throwable object in it's
details or if one of it's details contains the Throwable object.
|
void |
doEntityToVOMapping(ApplicationModule rootAm,
ViewObject[] vos) |
java.lang.Throwable[] |
getExceptions()
Gets the list of exceptions that spawned this message.
|
boolean |
hasPeerExceptions() |
boolean |
needsEntityToVOMapping() |
void |
printStackTrace()
Prints this
Throwable and its backtrace to the
standard error stream. |
void |
printStackTrace(java.io.PrintStream s)
Prints this
Throwable and its backtrace to the
specified print stream. |
void |
printStackTrace(java.io.PrintWriter s)
Prints this
Throwable and its backtrace to the specified
print writer. |
void |
setApplicationModule(ApplicationModule am)
Internal: Applications should not use this method.
|
void |
setDetails(java.lang.Object[] details)
Deprecated.
since 5.0. Instead use setExceptions.
|
void |
setExceptions(java.lang.Throwable[] details)
Sets the list of details.
|
void |
setNeedsEntityToVOMapping(boolean flag) |
getBaseMessage, getDetailMessage, getDetails, getErrorCode, getErrorParameters, getErrorParametersMap, getJboExceptionHelper, getLocalizedBaseMessage, getLocalizedMessage, getMessage, getProductCode, getProperties, getProperty, getProperty, getResourceClass, getResourceName, getSeverity, getSource, getTypeNameFromId, isAppendCodes, isExceptionInNonUIContext, isLocalizable, isShowDetailExceptions, isWarning, refreshProperty, setAppendCodes, setErrorParameters, setErrorParametersMap, setLocaleContext, setProperty, setSeverity, setShowDetailExceptions, setSourcepublic JboException(java.lang.String message,
java.lang.String errorCode,
java.lang.Object[] params)
If a localizable exception is desired, use the
JboException(Class, String, Object[]) constructor.
message - the unformatted text of the message.errorCode - an error code.params - the error message's parameters.ResourceBundlepublic JboException(java.lang.String message)
message - the text of the message.public JboException(java.lang.Throwable ex)
JboException.ex - an excpetion to be added to the details list.public JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params)
resBundleClass - a subclass class of the ResourceBundle
that will supply the message text.errorCode - an error code associated with a message in the
resource bundle.params - the error message's parameters.ResourceBundlepublic JboException(ResourceBundleDef resBundleDef, java.lang.String errorCode, java.lang.Object[] params)
resBundleDef - a ResourceBundleDef.errorCode - an error code associated with a message in the
resource bundle.params - the error message's parameters.ResourceBundlepublic JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params,
JboException[] exceptions)
resBundleClass - a subclass class of the ResourceBundle
that will supply the message text.errorCode - an error code associated with a message in the
resource bundle.params - the error message's parameters.exceptions - array of exceptions that this collection exception contains.ResourceBundlepublic JboException(java.lang.Class resBundleClass,
java.lang.String errorCode,
java.lang.Object[] params,
java.lang.Exception[] excs)
**Primarily for use by Oracle Applications.** BC4J framework does not use this exception nor throws such an exception.
resBundleClass - a subclass class of the ResourceBundle
that will supply the message text.errorCode - an error code associated with a message in the
resource bundle.params - the error message's parameters.excs - An array if exceptions that this exception bundles as peer exceptions.ResourceBundlepublic final boolean hasPeerExceptions()
public java.lang.Throwable[] getExceptions()
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.
public void setDetails(java.lang.Object[] details)
setDetails in interface JboMessagesetDetails in class JboWarningdetails - an array which replaces the current list of details.
array in this exception object.public void setExceptions(java.lang.Throwable[] details)
details - a list of Throwable exception objects
array in this exception object.public void addToDetails(java.lang.Object obj)
addToDetails in interface JboMessageaddToDetails in class JboWarningobj - a Throwable exception object to add to the details list.public void addToExceptions(java.lang.Throwable exception)
exception - a Throwable exception object to add to the details list.public void setApplicationModule(ApplicationModule am)
public void printStackTrace()
Throwable and its backtrace to the
standard error stream. This method prints a stack trace for this
Throwable object on the error output stream that is
the value of the field System.err. The first line of
output contains the result of the Throwable.toString() method for
this object. Remaining lines represent data previously recorded by
the method Throwable.fillInStackTrace(). The format of this
information depends on the implementation, but the following
example may be regarded as typical:
java.lang.NullPointerException
at MyClass.mash(MyClass.java:9)
at MyClass.crunch(MyClass.java:6)
at MyClass.main(MyClass.java:3)
class MyClass {
public static void main(String[] argv) {
crunch(null);
}
static void crunch(int[] a) {
mash(a);
}
static void mash(int[] b) {
System.out.println(b[0]);
}
}
printStackTrace in class java.lang.Throwablepublic void printStackTrace(java.io.PrintStream s)
Throwable and its backtrace to the
specified print stream.printStackTrace in class java.lang.Throwablepublic void printStackTrace(java.io.PrintWriter s)
Throwable and its backtrace to the specified
print writer.printStackTrace in class java.lang.Throwablepublic final void setNeedsEntityToVOMapping(boolean flag)
public final boolean needsEntityToVOMapping()
public void doEntityToVOMapping(ApplicationModule rootAm, ViewObject[] vos)
public boolean containsException(java.lang.Throwable e)