| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management SDK Developer Guide - Using APIs Release 9.3.3 E39307-02 |
|
Previous |
Next |
This chapter includes the following:
About Exceptions
Getting Error Codes
Disabling and Enabling Error Codes with Bulk APIs
Getting Error Messages
Saving and Restoring State Enabled and Disabled Warnings
Warnings on Deleting Objects Disabled Automatically by Agile API
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 on screen. 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:
Table 18-1 API Exception Error Codes
| 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. |
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 ExceptionConstants 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 Error Codes with Bulk APIs."
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 18-1 Getting Agile PLM error codes
private void removeApprover
(IChange change, IUser[] approvers, IUser[] observers, String comment) {
// 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); } }
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 18-2 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;}
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 18-3 Getting an error message
// Display an error message dialog void errorMessage(APIException ex) { try { JOptionPane.showMessageDialog(null, ex.getMessage(),
"Error", JOptionPane.ERROR_MESSAGE); } catch (Exception e) {} }
For a list of Agile PLM error messages, refer to the API Reference files (at http://edelivery.oracle.com/) under ExceptionConstants.
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 18-4 Disabling and enabling error codes
private void releaseChange(IAgileSession m_session, IChange chgObj) { IStatus nextStatus = null;
// Get the default next status
try { 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// ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING,// 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
try {
// Disable the warning m_session.disableWarning(ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING);
// Release the Change chgObj.changeStatus
(nextStatus, false, "", true, true, null, null, null, false);
// Enable all warnings m_session.enableWarning(ExceptionConstants.APDM_UNRESPONDEDCHANGE_WARNING); } catch (APIException exc) {} } } }}
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 18-5 Checking if an APIException is a warning
private void checkIfWarning(IAgileSession m_session) { boolean gotWarning = true;
while (gotWarning) {
// Add some API code here that throws an exception
try { m_session.doNothing(); gotWarning = false; } catch (APIException e) { try { if (e.isWarning()) m_session.disableWarning((Integer)e.getErrorCode()); } catch (Exception ex) {} continue; } break; }}
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 18-6 Using pushWarningState() and popWarningState()
private void pushPopWarningState(IAgileSession m_session, IItem item)
throws APIException {
// Save the current state of enabled/disabled warnings 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 ITable aml = item.getTable(ItemConstants.TABLE_MANUFACTURERS);
// Create a new row and set a value for the row 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();
// Restore the previous state of enabled/disabled warnings m_session.popWarningState(); }
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."
|
 Copyright © 2010, 2014, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|