Previous     Contents     Index     DocHome     Next     
iPlanet Unified Integration Framework Developer's Guide



Chapter 6   Exceptions


This chapter describes the generic exception framework implemented in UIF. It also describes various exception types, exception scenarios, and how to handle them. In addition, refer to your specific iPlanet Enterprise Connector Developer's Guide for more details on enterprise connector specific exceptions.

The chapter contains the following sections:

Refer to Chapter 5 "Programming Model" for more information on UIF programming model and suggestions pertaining to the UIF exception handling mechanisms.



About UIF Exceptions


UIF exceptions are used to notify the user of an error. UIF exceptions follow Java exception patterns and have all the characteristics of Java exceptions. UIF throws various types of netscape.bsp.BspException which can be interpreted and extended to provide more meaningful information at the application level.

All UIF exceptions are logged into the iPlanet Application Server logs. The logging of UIF exceptions are enabled by setting log_user_exceptions to `on' in the iPlanet Application Server registry using the iPlanet Application Server tools. Refer to the iPlanet Application Server documentation for the specifics of changing log levels. Refer to Related Information for details.

In addition to the generic netscape.bsp.BspException, UIF throws the following data object specific exceptions.

  • netscape.bsp.dataobject.exceptions.DataObjectException

  • netscape.bsp.dataobject.exceptions.FieldNameIsNullException

  • netscape.bsp.dataobject.exceptions.FieldNameTooLongException

  • netscape.bsp.dataobject.exceptions.FieldNotFoundException

  • netscape.bsp.dataobject.exceptions.IllegalPathException

  • netscape.bsp.dataobject.exceptions.IllegalRecursionException

  • netscape.bsp.dataobject.exceptions.IndexOutOfBoundsException

  • netscape.bsp.dataobject.exceptions.MethodUnsupportedException

  • netscape.bsp.dataobject.exceptions.TypeMismatchException

Refer to Chapter 7 "API Reference" for more information on these Exceptions.

UIF exceptions have a wrapped IBSPDataObjectStructure inside which provides the error information. This object is obtained by calling getInfo() on the UIF exception. This is an opaque structure that is populated by the exception thrower to provide details on the error state. This structure is not used by most of the exceptions originating from UIF. The enterprise connectors use this feature more concretely to forward the EIS error details. Refer to your specific iPlanet Enterprise Connector Developer's Guide for specific exceptions and the error data object structure contents.



Exception Scenarios


UIF exceptions can occur in the following scenarios:


Application Logic Errors

Exceptions that usually occur due to application logic errors. The various exceptions with correction information are as follows:

  1. DataObject missing

    Reason: The specified path may be wrong or the data object may not be available in the repository.

  2. IllegalRecursion

    Reason: Illegal recursion when getting or setting values on a data object.

  3. IndexOutOfBounds

    Reason: The array or list index is exceeding the number of elements.

  4. IllegalPath

    Reason: Data object, function object, and/or service path is not set correctly.

  5. FieldNotFound

    Reason: The data object field is missing in the repository.

  6. FieldNameIsNull

    Reason: The field name is null in the repository.

  7. FieldNameTooLong

    Reason: The field name specified is too long.

  8. MethodUnsupported

    Reason: The method being used is not supported.

  9. TypeMismatch

    Reason: The value being set does not match the type specified in the repository.

  10. Invalid datasource/domain

    Reason: The datasource or domain is not specified in the repository.

  11. Repository node not found

    Reason: The repository node being accessed is not found in the repository.

  12. Unable to create map dataobject

    Reason: Unable to create the map object for a specific data object.

  13. Map is not array

    Reason: The map being specified is not an array.

  14. Bad Mapelement type

    Reason: The element type specified in the data object and data object map do not match.

  15. Invalid MapStruct

    Reason: The data object map specified for the data object is invalid.

  16. Access not allowed for this user

    Reason: The web user and the datasource user match is not successful. The access is not allowed for the specified user.

  17. Function Object not prepared yet

    Reason: The web user is trying to use a function object that has not been prepared yet.

  18. Object instance is not valid

    Reason: The object instance being accessed is invalid or is no longer in memory.

  19. Invalid repository content

    Reason: The respository content being accessed is invalid.

  20. Invalid repository content for datasource

    Reason: The repository content being access is invalid for the datasource being used.


UIF Runtime Errors

Exceptions that usually occur due to UIF runtime errors. The various exceptions with correction information are as follows:

  1. Metadata service missing

    Reason: The UIF metadata service is not loaded properly.

  2. LDAPRepository missing

    Reason: The LDAP repository is not available to read contents from, it may be down or the application server cannot reach it.

  3. Cannot create repository with LDAP parameters: hostname, port, userdn, password, and bspbasedn

    Reason: UIF cannot access the repository with the configuration parameters such as host name, port, username, password and bsp base node.

  4. Cannot create pool

    Reason: UIF cannot create the pool based on the pool path. The configuration may be wrong or the pool size is set to 0.

  5. Pooled connection cannot be reserved (likely, the maximum number of concurrent connections is reached)

    Reason: UIF is unable to reserve a pooled connection. The system may have reached the maximum number of concurrent users.

  6. Cannot find pool

    Reason: Cannot find the specified pool.

  7. Service provider has not been enabled or has timed out

    Reason: The service provider being accessed has not been enabled or has timed out.

  8. Cannot retrieve LDAP configuration data

    Reason: UIF is unable to retrieve LDAP configuration data.

  9. Cannot find datasource instance with name

    Reason: UIF cannot find the datasource instance with the specified name.

  10. Service provider has timed out with state

    Reason: The service provider with certain state content has timed out and is no longer available.

  11. Repository instance missing

    Reason: The repository instance is not accessible by UIF and may not be loaded properly.

  12. Repository manager unavailable

    Reason: The repository manager instance is not accessible by UIF and may not be loaded properly.


Enterprise Connector Errors

Exceptions that usually occur due to enterprise connector errors. Please refer to your enterprise connector documentation for more specific enterprise connector exceptions. The various exceptions with correction information are as follows:

  1. Cannot create the datasource instance with name

    Reason: UIF is unable to create the datasource instance being specified. The enterprise connector may not be available or not loaded properly.

  2. Cannot find extension

    Reason: UIF cannot find a specific enterprise connector extension. The connector may not be available or not loaded properly.



UIF Exceptions Handling

Most exceptions that originate from the UIF runtime are due to various repository and access errors. These are data path missing errors, invalid content errors, illegal access errors, etc. These development time errors need to be resolved by taking the necessary corrective actions in the repository or the user code. Use the reason presented to make corrective actions.

Runtime specific errors need to have programmatic correction steps to exit from the error state gracefully. A few of the exception thrown by UIF are due to either missing a specific service or LDAP related errors explained above. These error may not be taken care of programmatically.

The crucial exceptions to handle programmatically are thrown by the enterprise connector. Enterprise connector specific exceptions extend netscape.bsp.BspException. Use getInfo() for the enterprise connector specific exceptions to interpret the results and take corrective actions accordingly. Refer to your specific iPlanet Enterprise Connector Developer's Guide for detailed error description contents.

Refer to Chapter 5 "Programming Model" for more information on UIF programming model and suggestions pertaining to the UIF exception handling mechanisms.


Previous     Contents     Index     DocHome     Next     
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.

Last Updated October 19, 2000