Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Business Components
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.jbo
Class JboException

    java.lang.Object
      |
      +--java.lang.Throwable
            |
            +--java.lang.Exception
                  |
                  +--java.lang.RuntimeException
                        |
                        +--oracle.jbo.JboException

Direct Known Subclasses:
  AfterCommitException, AfterPostException, AfterRollbackException, AlreadyConnectedException, AlreadyLockedException, ApplicationModuleCreateException, ApplicationPoolException, AttributeLoadException, CustomClassNotFoundException, DataCreationException, DeadEntityAccessException, DeadViewRowAccessException, DMLException, DomainValidationException, GenericDomainException, InvalidAttrKindException, InvalidDefNameException, InvalidObjAccessException, InvalidObjNameException, InvalidOperException, InvalidOwnerException, InvalidParamException, JboAssert, JboExMsgCarrier, JboSerializationException, JboUnexpectedException, KeyNotFoundException, NameClashException, NoDefException, NoObjException, NotConnectedException, PersistenceException, PiggybackException, ReadOnlyViewObjectException, ReadXMLException, RemoveWithDetailsException, RowCreateException, RowInconsistentException, RowNotFoundException, SQLDatumException, SQLStmtException, TooManyObjectsException, UnknownSQLTypeException, ValidationException, VariantException, ViewLinkAlreadyExistsException

public class JboException
extends java.lang.RuntimeException
implements java.io.Serializable, MetaObjectBase, JboMessage

Top level exception for the JBO package.

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).

## 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.

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 `CSMessageBundle`
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."},

## Exceptions generated by applications.

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:

- `getResourceName`
to return the name of the appropriate resource bundle.
- `getProductCode`
to return the name of the product.

Other methods may be overridden to modify the message format.

## Creating Custom Exception Classes

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.

## Localizing Exception Messages

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`:

        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.

## Marshaling Exceptions

`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:

- add derived information to the serialized stream which is not present in a member variable of your class

- 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();
      }

Since:
  JDeveloper 3.0
See Also:
  Serialized Form

Fields inherited from interface oracle.jbo.common.MetaObjectBase
`TYP_APP_MODULE, TYP_ATTRIBUTE, TYP_COMPONENT_OBJECT, TYP_DEF_APP_MODULE, TYP_DEF_ATTRIBUTE, TYP_DEF_COMPONENT_OBJECT, TYP_DEF_DOMAIN, TYP_DEF_ENTITY_ASSOC, TYP_DEF_ENTITY_OBJECT, TYP_DEF_PACKAGE, TYP_DEF_VIEW_LINK, 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_PACKAGE, TYP_VALIDATOR_TYPE, TYP_VIEW_LINK, TYP_VIEW_OBJECT, TYP_VIEW_ROW, TYP_VIEW_ROW_SET, TYP_VIEW_ROW_SET_ITERATOR`

Constructor Summary
`JboException(java.lang.Class resBundleClass, 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`.

Method Summary
`void` | `addToDetails(java.lang.Object obj)` Adds to the list of details.
`java.lang.String` | `getBaseMessage()` Gets the message without localizing it or inserting parameters.
`java.lang.String` | `getDetailMessage()` Constructs a message incorporating the list of details.
`java.lang.Object[]` | `getDetails()` Gets the list of objects and exceptions that spawned this message.
`java.lang.String` | `getErrorCode()` Returns the message's error code.
`java.lang.Object[]` | `getErrorParameters()` Returns the error message parameters.
`protected JboExceptionHelper` | `getJboExceptionHelper()` Get the Helper object for this exception.
`java.lang.String` | `getLocalizedBaseMessage(java.util.Locale l)` Localizes the message text for a specific `Locale`, but without inserting parameters.
`java.lang.String` | `getLocalizedMessage(java.util.Locale l)` Formats the message text for a specific `Locale`.
`java.lang.String` | `getMessage()` Formats the message text for the default locale.
`java.lang.String` | `getProductCode()` Returns a message's product code.
`java.lang.Class` | `getResourceClass()` Gets the class of the resource bundle used to localize messages.
`java.lang.String` | `getResourceName()` Returns the name of the `ResourceBundle` used to localize or resolve messages.
`static java.lang.String` | `getTypeNameFromId(int id)`
`boolean` | `isLocalizable()` Tests this message's localizability.
`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)`
`void` | `setDetails(java.lang.Object[] details)` Sets the list of details.
`protected void` | `setErrorParameters(java.lang.Object[] params)` Resets the error parameters.

Methods inherited from class java.lang.Throwable
`fillInStackTrace, getLocalizedMessage, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail

### JboException

    public JboException(java.lang.String message,
                        java.lang.String errorCode,
                        java.lang.Object[] params)

  Creates a formattable but non-localizable exception.

  If a localizable exception is desired, use the `JboException(Class, String, Object[])` constructor.

  Parameters:
    `message` - the unformatted text of the message.
    `errorCode` - an error code.
    `params` - the error message's parameters.
  See Also:
    `ResourceBundle`

### JboException

    public JboException(java.lang.String message)

  Create a non-formattable exception.
  Parameters:
    `message` - the text of the message.

### JboException

    public JboException(java.lang.Throwable ex)

  Converts an exception into a non-formattable `JboException`.
  Parameters:
    `ex` - an excpetion to be added to the details list.

### JboException

    public JboException(java.lang.Class resBundleClass,
                        java.lang.String errorCode,
                        java.lang.Object[] params)

  Creates a translatable exception.
  Parameters:
    `resBundleClass` - the base class of the `ResourceBundle` that will supply the message text.
    `errorCode` - error code; a key associated with a message in the resource bundle.
    `params` - the error message's parameters.
  See Also:
    `ResourceBundle`

Method Detail

### getMessage

    public java.lang.String getMessage()

  Formats the message text for the default locale.
  Specified by:
    getMessage in interface JboMessage
  Overrides:
    getMessage in class java.lang.Throwable
  Returns:
    the localized message.

### getLocalizedMessage

    public java.lang.String getLocalizedMessage(java.util.Locale l)

  Formats the message text for a specific `Locale`.
  Specified by:
    getLocalizedMessage in interface JboMessage
  Parameters:
    `l` - a locale.
  Returns:
    the localized message.

### getBaseMessage

    public java.lang.String getBaseMessage()

  Gets the message without localizing it or inserting parameters.
  Specified by:
    getBaseMessage in interface JboMessage
  Returns:
    the un-formatted, non-localized message.

### getResourceClass

    public java.lang.Class getResourceClass()

  Gets the class of the resource bundle used to localize messages.
  Specified by:
    getResourceClass in interface JboMessage
  Returns:
    a `ResourceBundle`.

### getLocalizedBaseMessage

    public java.lang.String getLocalizedBaseMessage(java.util.Locale l)

  Localizes the message text for a specific `Locale`, but without inserting parameters.
  Specified by:
    getLocalizedBaseMessage in interface JboMessage
  Parameters:
    `l` - a locale.
  Returns:
    the localalized but un-formatted message.

### getResourceName

    public java.lang.String getResourceName()

  Returns the name of the `ResourceBundle` used to localize or resolve messages.
  Specified by:
    getResourceName in interface JboMessage
  Returns:
    a string identifying a resource bundle.

### getErrorParameters

    public java.lang.Object[] getErrorParameters()

  Returns the error message parameters.
  Specified by:
    getErrorParameters in interface JboMessage
  Returns:
    an array.

### setErrorParameters

    protected void setErrorParameters(java.lang.Object[] params)

  Resets the error parameters. This method is for use by derived classes who create their own set of parameters but do not want the "thrower" to know about it.

### getErrorCode

    public java.lang.String getErrorCode()

  Returns the message's error code.
  Specified by:
    getErrorCode in interface JboMessage
  Returns:
    a string containing an error code.

### getProductCode

    public java.lang.String getProductCode()

  Returns a message's product code.
  Specified by:
    getProductCode in interface JboMessage
  Returns:
    `JBO_PRODUCT_CODE`.

### getDetails

    public java.lang.Object[] getDetails()

  Gets the list of objects and exceptions that spawned this message.

  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.

  Specified by:
    getDetails in interface JboMessage
  Returns:
    an array.

### getDetailMessage

    public java.lang.String getDetailMessage()

  Constructs a message incorporating the list of details.
  Specified by:
    getDetailMessage in interface JboMessage
  Returns:
    a text string.

### setDetails

    public void setDetails(java.lang.Object[] details)

  Sets the list of details.
  Specified by:
    setDetails in interface JboMessage
  Parameters:
    `details` - an array which replaces the current list of details. array in this exception object.

### addToDetails

    public void addToDetails(java.lang.Object obj)

  Adds to the list of details.
  Specified by:
    addToDetails in interface JboMessage
  Parameters:
    `obj` - an object to add to the details list.

### isLocalizable

    public boolean isLocalizable()

  Tests this message's localizability.
  Specified by:
    isLocalizable in interface JboMessage
  Returns:
    `true` if this message can be localized.

### getJboExceptionHelper

    protected JboExceptionHelper getJboExceptionHelper()

  Get the Helper object for this exception. The helper object contains all of the shared storage for both the JboRuntimeException and the JboException.
  Returns:
    the JboExceptionHelper object.
  See Also:
    `JboExceptionHelper`

### getTypeNameFromId

    public static java.lang.String getTypeNameFromId(int id)

### setApplicationModule

    public void setApplicationModule(ApplicationModule am)

### printStackTrace

    public void printStackTrace()

  Prints this `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)

  This example was produced by running the program:

  >      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]);
  >          }
  >      }

  Overrides:
    printStackTrace in class java.lang.Throwable
  See Also:
    "java.lang.System#err"

### printStackTrace

    public void printStackTrace(java.io.PrintStream s)

  Prints this `Throwable` and its backtrace to the specified print stream.
  Overrides:
    printStackTrace in class java.lang.Throwable

### printStackTrace

    public void printStackTrace(java.io.PrintWriter s)

  Prints this `Throwable` and its backtrace to the specified print writer.
  Overrides:
    printStackTrace in class java.lang.Throwable
  Since:
    JDK1.1

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Business Components
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD