Skip Headers

Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-01 |
| Contents

Previous | Next |

# 18 Handling Exceptions

Errors that cause a problem in a Java program are called exceptions. When Java throws an exception that is not caught, your program may quit, or errors may appear onscreen. To handle an exception gracefully, your program must:

- Protect code that contains a method that might throw an exception by putting it in a try block.

- Test for and handle any exceptions that are thrown inside a catch block.

The Agile API provides a subclass of Exception called APIException. This is a general-purpose exception class that is used throughout the Agile API to handle Agile PLM runtime errors. In the Agile API HTML reference, each method indicates the types of exceptions it throws. Generally, any Agile API method that requires interaction with the Agile Application Server throws APIException. The table below lists the APIException class methods for handling exceptions:

Method | Description
--- | ---
getErrorCode() | Returns the number of the error code associated with the APIException.
getMessage() | Returns the error message associated with the APIException.
getRootCause() | Returns the root cause of the APIException, if any.
getType() | Returns the type of exception.

## 18.1 Exception Constants

The ExceptionConstants class contains String constants for all Agile Application Server and Agile API runtime error and warning codes. For a description of each of these constants, refer to the API Reference files at `http://edelivery.oracle.com/`.

Several ofExceptionConstants are for exceptions that are used to display an Agile PLM warning message before completing an action. All constants for warning messages end with the suffix WARNING. If you don't want to use Agile PLM warning messages in your code, you can disable them. For more information, see Disabling and Enabling Warning Messages on page 285.

## 18.2 Getting Error Codes

To properly trap warning errors, you may need to retrieve the error code of the exception and then handle it appropriately. Generally, this involves displaying a confirmation dialog box to let the user choose whether to complete the action. The following example shows how to check for the error code of an exception in the catch block.

Example: Getting Agile PLM error codes

    private void removeApprover(IChange change, IUser[] approvers, IUser[] observers, String comment) {
    void errorMessage(APIException ex) {
    // Remove the selected approver

try {

change.removeApprovers(change.getStatus(), approvers, observers, comment);

} catch (APIException ex) {

if (ex.getErrorCode().equals(ExceptionConstants.APDM_RESPONDEDUSERS_WARNING))

JOptionPane.showMessageDialog(null, ex.getMessage(), "Warning", JOptionPane.YES_NO_OPTION);

}

    }

## 18.3 Disabling and Enabling Error Codes with Bulk APIs

The SDK supports the following bulk operations in IAgileSession to disable/enable all error codes or for a given set of error codes:

- IAgileSession.enableWarnings(Integer[])

- IAgileSession.disableWarnings(Integer[])

- IAgileSession.enableAllWarnings()

- IAgileSession.disableAllWarnings()

The process is similar to the previous example. The following example shows how to use these bulk APIs to suppress warnings while releasing a Change.

Example: Disabling and enabling error codes in the bulk mode

    public static void releseECO(IAgileSession session, IChange change)

throws Exception {

// Set workflow

IWorkflow workflow = change.getWorkflows()[0];

change.setWorkflow(workflow);

IStatus submit = getStatus(workflow, StatusConstants.TYPE_SUBMIT);

IStatus ccb = getStatus(workflow, StatusConstants.TYPE_REVIEW);

IStatus released = getStatus(workflow, StatusConstants.TYPE_RELEASED);

session.disableWarnings(new Integer[] {

ExceptionConstants.APDM_WFL_ATLEASTONECHGANALYST_WARNING,

ExceptionConstants.APDM_MISSINGFIELDS_WARNING });

// instead you can use session.disableAllWarnings()

// route to SUBMIT

change.changeStatus(submit, false, null, false, false, new Object[]{}, new Object[]{}, new Object[] {}, false);

// Change status to CCB

change.changeStatus(ccb, false, null, false, false, new Object[]{}, new Object[]{}, new Object[]{}, false);

// route from CCB to release

change.changeStatus(released, false, "release", false, false, new Object[]{}, new Object[]{}, new Object[]{}, false);

session.enableWarnings(new Integer[] {

ExceptionConstants.APDM_WFL_ATLEASTONECHGANALYST_WARNING,

ExceptionConstants.APDM_MISSINGFIELDS_WARNING });

// instead you can use session.enableAllWarnings()

    }
    public static IStatus getStatus(IWorkflow workflow, StatusConstants status)

throws Exception {

IStatus[] states = workflow.getStates(status);

IStatus state = states[0];

return state;

}

## 18.4 Getting Error Messages

If your program throws an APIException, which indicates an Agile PLM runtime error, you may want to display an error message. You can use the getMessage() method to return the error message string and then display it in a message dialog box, as shown in the following example.

Example: Getting an error message

    // Display an error message dialog

try {

JOptionPane.showMessageDialog(null, ex.getMessage(), "Error", JOptionPane.ERROR_MESSAGE);

} catch (Exception e) {}

    }
    // ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING,

For a list of Agile PLM error messages, refer to the API Reference files (at `http://edelivery.oracle.com/`) under ExceptionConstants.

## 18.5 Disabling and Enabling Warning Messages

Several Agile PLM error messages are warnings that give you the option to stop or continue with an operation. By default, most error messages, including warning messages, are enabled. If you try to perform an action that triggers a warning, an exception will be thrown. To avoid the exception, you can disable the warning message before performing the action.

The following example shows how to check whether attempting to release a change causes an exception to be thrown. If the error code for the exception is ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING, the program displays a warning. The user can click Yes in the warning dialog box to release the change.

Example: Disabling and enabling error codes

    private void releaseChange(IAgileSession m_session, IChange chgObj) {

IStatus nextStatus = null;

try {

// Get the default next status

nextStatus = chgObj.getDefaultNextStatus();

    // Release the Change

chgObj.changeStatus(nextStatus, false, "", false, false, null, null, null, false);

} catch (APIException ex) {

    // If the exception is error code
    // display a warning message

if (ex.getErrorCode() == ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING) {

int i =

JOptionPane.showConfirmDialog(null, ex.getMessage(),

"Warning", JOptionPane.YES_NO_OPTION);

if (i == 0) {

    // If the user clicks Yes on the warning, disable the error code and release the change
    // Save the current state of enabled/disabled warnings
    // Disable the warning

try {

m_session.disableWarning(ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING);

    // Release the Change
    // Enable all warnings

chgObj.changeStatus(nextStatus, false, "", true, true, null, null, null, false);

m_session.enableWarning(ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING);

} catch (APIException exc) {}

}

}

}

    }

## 18.6 Checking if APIException is Warning and not Error

As noted above, if you try to perform an operation that triggers a warning, an exception will be thrown. Warning messages are helpful for interactive GUI clients, like Agile Web Client, but you may not want to use them in your Agile API program, particularly if it performs batch processes.

You can use APIException.isWarning() to check whether an Agile PLM exception is a warning. If so, you can disable the warning to continue the operation.

Example: Checking if an APIException is a warning

    private void checkIfWarning(IAgileSession m_session) {

boolean gotWarning = true;

while (gotWarning) {

try {

    // Add some API code here that throws an exception

m_session.doNothing();

gotWarning = false;

} catch (APIException e) {

try {

if (e.isWarning())

m_session.disableWarning((Integer)e.getErrorCode());

} catch (Exception ex) {}

continue;

}

break;

}

    }

## 18.7 Saving and Restoring State Enabled and Disabled Warnings

Rather than keep track of which warning messages are disabled or enabled before beginning a particular operation, you can use IAgileSession.pushWarningState() to save the current state of enabled and disabled warnings. After completing the operation, you can restore the previous state of enabled and disabled warnings using IAgileSession.popWarningState().

Example: Using pushWarningState() and popWarningState()

    private void pushPopWarningState(IAgileSession m_session, IItem item) throws APIException {

m_session.pushWarningState();

    // Disable two AML warnings

m_session.disableWarning(ExceptionConstants.APDM_WARN_MFRNAMECHANGE_WARNING);

m_session.disableWarning(ExceptionConstants.APDM_ONEPARTONEMFRPART_WARNING);

    // Get the Manufacturers table
    // Create a new row and set a value for the row

ITable aml = item.getTable(ItemConstants.TABLE_MANUFACTURERS);

HashMap amlEntry = new HashMap();

amlEntry.put(ItemConstants.ATT_MANUFACTURERS_MFR_NAME, "MFR_TEST3");

amlEntry.put(ItemConstants.ATT_MANUFACTURERS_MFR_PART_NUMBER, "MFR_PART3");

IRow rowAML1 = aml.createRow(amlEntry);

rowAML1.setValue(ItemConstants.ATT_MANUFACTURERS_REFERENCE_NOTES, "new note");

    // Restore the previous state of enabled/disabled warnings
    }

m_session.popWarningState();

## 18.8 Warnings on Deleting Objects Automatically Disabled by Agile API

In the Agile Web Client, when you try to delete an object a warning message appears. These warning messages are not appropriate for batch processes in an Agile API program. Therefore, the Agile API implicitly disables the following warnings, which saves you the trouble of disabling them in your code.

- ExceptionConstants.APDM_HARDDELETE_WARNING

- ExceptionConstants.APDM_SOFTDELETE_WARNING

For more information about deleting objects, see Deleting and Undeleting Objects on page 36.