1. API Overview
  2. Working with Transactions, Exceptions, and Logging

2 Working with Transactions, Exceptions, and Logging

This chapter describes working with transactions, exceptions, and logging. You can use this information when working with all UIM APIs because all APIs must be called from within a transaction, and the calling code must handle exceptions and log any errors.

See the UIM Javadoc for detailed information about API methods, such as the exception thrown by each method.

Working with Transactions

This section describes handling transactions when calling APIs. A standard transaction flow typically includes:

  • Starting a transaction

  • Calling an API

  • Determining if an error occurred

  • Performing a commit or rollback of the transaction based on whether an error occurred

Example 2-1 shows a custom method that calls a manager API within a transaction:

Example 2-1 Call to an API from within a Transaction

public void sampleCallAPI()
{
    UserEnvironment ue = null;
    UserTransaction ut null; 
    try {
        // Step 1: Begin a User Environment and Transaction
        ue = startUserEnvironment(); /* see appendix */
        ut = PersistenceHelper.makePersistenceManager().getTransaction();
        ut.begin();

        // Step 2: Call the API
        PlaceManager mgr = PersistenceHelper.makePlaceManager();
        List<PlaceSpecification> list = mgr.getAllPlaceSpecs();
        // Do something with the list...
    }
    catch (Throwable t) {
        // Step 3: Handle Exception
        try {
            if (t instanceof ValidationException)
                // Do something with the Exception, such as print it.
                System.out.println("Method call returned validation exception.");
        }
        catch (Exception ignore) {}
    }
    finally {
        // Step 4: Commit or Rollback Transaction
        commitOrRollback(ut); /* see appendix */

        // Step 5: End User Environment
        if (ue != null)
            endUserEnvironment(ue); /* see appendix */
    }
}

When managing transactions and calling APIs from within a transaction, consider the following:

  • A commit is usually needed between separate groups of API calls that are making updates to the database. The group of APIs is called for an atomic and complete set of operations.

  • A rollback is needed when any error occurs.

  • Ensure the API call is made within the correct context of live or business interaction.

  • Ensure the User Environment is started before the transaction, and is ended within the finally block.

Working with Exceptions

This section describes the exceptions that the UIM APIs can throw. The EntityManager API methods typically throw a ValidationException when a validation error is encountered. However, other exceptions can also be thrown. Table 2-1 describes all of the UIM Exceptions that can be thrown, including the ValidationException.

Table 2-1 Exception Descriptions

Exception Extends Description

ValidationException

InventoryException

This exception is widely used and represents all variations of business validation exceptional conditions.

TransientObjectException

ValidationException

This exception is thrown by manager methods if an object is passed into a method in a transient state.

ReadOnlyEntityException

RuntimeException

This exception is thrown when a read-only entity is updated or deleted. A read-only entity can be an entity that is in a queued/planned object state.

InventoryException

Exception

This exception is the Base Inventory Exception and other exceptions extend it.

InvalidBusinessInteractionException

RuntimeException

This exception is thrown when the caller attempts to perform an operation against an entity under a BusinessInteraction with an invalid status such as completed or cancelled.

DeletedObjectException

ValidationException

This exception is thrown by manager methods if an object is passed into a method in a deleted state.

BusinessInteractionDisassociationException

ValidationException

This exception is thrown when the manager method is attempting to alter a Business Interaction or Business Interaction Item and the Business Interaction validation determines it is not allowed.

BusinessInteractionCompleteException

ValidationException

This exception is thrown when the manager method is attempting to complete a Business Interaction and the validation determines it is not allowed.

Working with Logging

This section describes logging messages (informational, warning, and debug messages). This section also describes detecting what messages were logged during an API call, which is helpful when trying to determine the success or failure of an API call.

See UIM System Administrator's Guide for information on configuring UIM logging, including changing the logging level.

Configuring the Logging Level

The logging level, which is the amount of logging output to the log files from UIM API calls, is determined by the values configured in the UIM_Home/config/loggingconfig.xml file.

Example 2-2 shows an entry from the loggingconfig.xml file. This entry results in any debug messages (through log.debug) existing in the code to be output to the log file when the class exists in the specified package:

Example 2-2 Entry from loggingconfig.xml

<Logger name="oracle.communications.inventory.extensibility" additivity="false">
    <level="debug" />
    <AppenderRef ref="stdout"/>
    <AppenderRef ref="rollingFile"/>
</Logger>

Working with the Log Interface

The Log interface is located in the package:

oracle.communications.inventory.api.framework.logging

The Log interface provides the ability for an API, or custom code calling an API, to log errors, throw exceptions, and log informational, warning, or debug messages.

Table 2-2 lists the items that can be requested of the Log interface. See the UIM Javadoc for information regarding the specific parameters of each method.

Table 2-2 Log Interface Description

Description Method to Use Throws Exception Checked with Method on FeedbackProvider

Fatal Exception

fatal()

LogFatalException

getFatals()

Validation Exception

validationException()

ValidationException or the exception type provided on method input

getErrors()hasMessages()

Validation Error

validationError()

Currently does not throw a ValidationException

getErrors()hasMessages()

Warning Message

warn()

Not applicable

getWarnings()hasMessages()

Informational Message

info()

Not applicable

getNotes()hasMessages()

Debug Message

debug()

Not applicable

getDebugs()

When calling an API method, additional errors may be thrown. For example, a custom ruleset that calls an API method may throw additional log messages that the developer wants to include in the log file. Example 2-3 shows custom code that adds additional log messages to the log file by calling the Log interface to log an informational message and a debug message:

Example 2-3 Using the Log Interface

import oracle.communications.inventory.api.framework.logging.Log;
import oracle.communications.inventory.api.framework.logging.LogFactory;
protected Log log;
	
public void testLog() 
{
    this.log = LogFactory.getLog(this.getClass());
    this.log.validationError("service.findServiceError", service.getId());
	
    if (this.log.isInfoEnabled())
        	this.log.info ("", "This is an informational message");
 
    if (this.log.isDebugEnabled())
        this.log.debug ("", "This is a debug message.");
}

About UIM Log Messages

Messages logged by UIM APIs are defined in several *.properties files, per domain. For example, the service.properties file defines the messages for the service domain, and the equipment.properties file defines the messages for the equipment domain. All message-specific *.properties files are located in the UIM_Home/config/resources/logging directory.

Several of methods on the Log interface define an input parameter of a String key for an error message. These unique keys, along with a corresponding error message String, are defined in the message-specific *.properties files. Example 2-4 shows a single message entry from the servce.properties file:

Example 2-4 Message Entry from service.properties

service.findServiceError.id=110311
service.findServiceError=Error finding service with id {0}.

The numbers within the braces are parameter values passed in as arguments to the method call.

Defining Custom Log Messages

You can define custom log messages in the UIM_Home/config/resources/logging /*.properties files by adding a unique key and corresponding message. The key must be unique across all *.properties files in this directory, and across any *.properties files contained in any installed cartridges.

Working with the FeedbackProvider Interface

The FeedbackProvider interface is located in the package:

oracle.communications.inventory.api.framework.logging

After calling an API, the code must determine what messages have been logged. The FeedbackProvider interface provides the ability for an API, or custom code calling an API, to interrogate what has occurred. Example 2-5 shows code that checks to see if an error has been logged, and then prints the error:

Example 2-5 Using the FeedbackProvider Interface

public void sampleCallAPIWithFeedbackProvider() 
{ 
    UserEnvironment ue = null;
    UserTransaction ut = null;
	
    try {
        // Step 1: Begin a User Environment and Transaction
        // Step 2: Call the API 
        if (!hasErrors()) /* see appendix */
            ut.commit();
        else {
            ut.rollback(); 
            List<FeedbackMessage> errors =
            ue.getFeedbackProvider().getErrors();
            for ( java.util.Iterator iter = errors.iterator(); iter.hasNext(); ) 
            {
                FeedbackMessage error = (FeedbackMessage)iter.next();
                System.out.println("Error occurred: " + error.getMessage());
            }
        }
    }
    catch (Throwable t)
    {
        // Step 3: Handle Exception
    }
    finally
    {
        // Step 4: Commit or Rollback Transaction 
        // Step 5: End User Environment 
    }
}