Error Transformations
- Tom Coppeto
Summary
OSID methods define possible error conditions. According to the OSID Specification, an OSID method returns the specified value type (or nothing) or an Error is returned. Except in the case where an OSID method implies an pseudo-asynchronous behavior, one or the other must occur when control is returned to an OSID Consumer. No mechanisms such as external error statuses or messages are possible.
OSID Errors are grouped into four Error Categories indicating to whom the error pertains.
Transformations
OSID Errors map to Java Exceptions. org.osid.OsidException is defined to group the Error Categories that will map to checked exceptions. org.osid.OsidRuntimeException is defined to group the Error Categories that will map to unchecked exceptions. Unchecked exceptions are used in places where the OSID Consumer should not need to catch and process them, such as programming errors.
| OSID Error Category | OSID Error | Java Exception | Java Class Parent | Description |
|---|---|---|---|---|
| org.osid.OsidException | java.lang.Exception | These exceptions are checked exceptions in Java. | ||
| User | org.osid.UserException | org.osid.OsidException | The category of user errors are the result of a user action and directed toward the user. | |
| User | ALREADY_EXISTS | org.osid.AlreadyExistsException | org.osid.UserException | Attempt to add a relation that already exists. Typically, these are used where two OSID IDs are mapped to each other in some way, and that mapping already exists. |
| User | NOT_FOUND | org.osid.NotFoundException | org.osid.UserException | The object or relation requested by a primary unique Id was not found. These typically are not used when looking up objects by a related object or by some other data element where the lookup key is not a primary unique identifier and an empty list if returned. |
| User | PERMISSION_DENIED | org.osid.PermissionDeniedException | org.osid.UserException | An authorization failure occurred. These are thrown when the authorization failure is pertinent to the user and is desirable to expose that fact as opposed to a Java security or file permission error that the user cannot do anything about. The latter cases would fall under OPERATION_FAILED. |
| Operational | org.osid.OperationalException | org.osid.OsidException | The category of operational or system errors that may occur and are directed toward the user. | |
Operational | CONFIGURATION_ERROR | org.osid.ConfigurationErrorException | org.osid.OperationalException | A configuration error occurred during initializing an OSID. |
| Operational | OPERATION_FAILED | org.osid.OperationFailedException | org.osid.OperationalException | A problem occurred in the execution of an OSID method. This covers the gamut of unavoidable operational problems not attributable to the other operational categories. Examples are the database is down or creating a circular dependency. |
| Operational | TRANSACTION_FAILURE | org.osid.TransactionFailureException | org.osid.OperationalException | An error occurred while committing a transaction using the osid.transaction.Transaction interface. |
| org.osid.OsidRuntimeException | java.lang.RuntimeException | These exceptions are unchecked exceptions in Java. These exceptions are defined where there are alternatives to avoid them such as checking for compliance or testing one's code. | ||
| ConsumerContract | org.osid.ConsumerContractException | org.osid.OsidRuntimeException | The category of errors used where an OSID Consumer has violated the contract. | |
| ConsumerContract | ILLEGAL_STATE | org.osid.IllegalStateException | org.osid.ConsumerContractException | A method has been executed at an inappropriate time. |
| ConsumerContract | INVALID_ARGUMENT | org.osid.InvalidArgumentException | org.osid.ConsumerContractException | A bad value supplied to an OSID method parameter. |
| ConsumerContract | INVALID_METHOD | org.osid.InvalidMethodException | org.osid.ConsumerContractException | The OSID Consumer attempted to invoke an undefined method. |
| ConsumerContract | NO_ACCESS | org.osid.NoAccessException | org.osid.ConsumerContractException | An attempt at updating a read-only value. |
| ConsumerContract | NULL_ARGUMENT | org.osid.NullArgumentException | org.osid.ConsumerContractException | A null argument was provided to an OSID method. |
| ConsumerContract | UNIMPLEMENTED | org.osid.UnimplementedException | org.osid.ConsumerContractException | An OSID method was invoked but not implemented by an OSID Provider. These errors can only be defined when the compliance is optional. |
| ConsumerContract | UNSUPPORTED | org.osid.UnsupportedException | org.osid.ConsumerContractException | An OSID Provider does not support the supplied data or data type. |
| ProviderContract | org.osid.ProviderContractException | org.osid.OsidRuntimeException | The category of errors used where an OSID Provider has violated the contract. | |
| ProviderContract | BAD_LOGIC | org.osid.BadLogicException | org.osid.ProviderContractException | An OSID Provider exhibited incorrect behavior. |
| ProviderContract | INVALID_ERROR | org.osid.InvalidErrorException | org.osid.ProviderContractException | An OSID Provider threw an exception not defined in an OSID method. |
| ProviderContract | INVALID_RETURN | org.osid.InvalidReturnException | org.osid.ProviderContractException | An OSID Provider returned in invalid return value. |
| ProviderContract | MISSING_METHOD | org.osid.MissingMethodException | org.osid.ProviderContractException | A defined method is missing from the OSID Provider. |
| ProviderContract | NULL_RETURN | org.osid.NullReturnException | org.osid.ProviderContractException | The OSID Provider returned a null. |