The Purpose of Operation Result
Operation Result is a rich data structure that describe useful information about the whole operation and its sub-operations. It describes what parts of the operation failed and provides a rich diagnostics information to display to user. The purpose of Operation Result is twofold:
- Indicate machine-processable result of sub-operations. E.g. it may indicate which specific parts have failed during test connection operation. It may also indicate which accounts were provisioned and which have failed, indicating a partial success of the operation. Clients that understand such results may re-try only the parts of the operation that have failed and may also provide better information about the process state to the user.
- Show rich human-readable diagnostics information to the user. The intent is to remove the need of a system administrators to wade through system logs and parse kilometers-long Java exceptions to understand what is the problem. Operation Result displays the information in a quite convenient and (possible) interactive way, showing the details and context of the operation. The operation result may contain even the exceptions that describe the problem in details, but the focus is on a short error messages that can display reasonable information to the user.
Operation Result data structure is designed to allow a sophisticated error handling. E.g. if a user is modified by invocation of IDM Model Interface the modification can be reflected to several accounts using mappings. Some of account modification may succeed and other modification may fail. In such a case an exception is not thrown. The operation returns as in it would after a successful operation. After the return the operation result structure will be filled with details of every significant sub-operation. The overall status will indicate partial error and one of the sub-operations will be set to fatal error. As this structure is intended for human readability and machine processability it can be used for variety of purposes. It can be used to display detailed error information to the user, to automatically react to certain situation or for any similar purpose.
TODO: operation tree, operation names (machine-processable, catalog keys), status, etc.
Example Usage on Client Side
Example Usage in the Implementation
TODO: More Examples
- Data items that are part of OperationResult (parameters, context, return values) should be serializable - ideally primitive types or prisms.
- As stated above, the information in OperationResult should be meaningful to the administrator. So you should not duplicate whole call stack here (i.e. by adding "createSubResult" at the beginning of each of your method). Instead, focus on the most important parts of execution. (Subresult creation is obligatory only on component interfaces.)
- OR can be used by the client to detect whether the operation was successful. However, they are not meant as a replacement of exceptions. In case of fatal errors, when there is an expectation that the client could not meaningfully continue its operation (e.g. when getObject couldn't find the requested object in repository), it is necessary to throw an exception and set the OperationResult as well.
- The difference between parameters and context is that parameters denote real parameters passed to the method called, whereas context somehow describes the current state of world the method acts upon. E.g. the method task.refresh(), which by itself has no parameters except for OperationResult, can put the OID of the task into the context. Another example of an item put into context is the name of class implementing the called method.