Exceptions

All problems are reported by means of an exception object, which is a subclass of the exception object defined by WVCM.

The client can obtain the following information from an exception:
  • A reason code (an extension of a WVCM enumeration), which classifies the type of incident being reported (for example, WvcmException.ReasonCode.READ_FAILED).
  • A subordinate reason code, which provides a finer classification of the incident within the classification of the reason code (for example, StpException.StpReasonCode.CONFLICT).
  • A locale-independent message identifier (catalog index) and argument values specific to the incident being reported. This information is suitable for logging purposes and can also be used to generate a localized message.
  • A list of nested exceptions, each of which describes a subordinate incident that contributed to the incident reported by the exception.
  • For resource access problems, the primary resource involved in the incident, which is typically the resource targeted by the operation that failed.
  • For property access problems, the property of the primary resource involved in the incident.
  • For operations that address multiple resources, a list of the resources for which the operation was successful.
  • For selected incidences, additional information specific to the incident being reported.

Each operation defines a set of preconditions that must be met for the operation to succeed. For example, a resource whose properties are to be read must exist, a resource that has the same name as the resource to be created cannot exist, a resource to be checked out must be versioned and checked in. Violations of such preconditions cause the operation to throw an exception.

Operations can often be applied to a collection of resources. If the operation fails on any one of them, an exception is thrown (with the successes reported in the exception object).

Problems that the server encounters while reading or writing the properties or meta-properties of a resource do not cause a CM API operation to throw an exception. Instead, the exception is associated with the property within the returned proxy. Only when the client attempts to extract that property value from the proxy is the exception be thrown. The client might also interrogate the proxy before extracting the property value to determine whether there are any problems and obtain the exception without it being thrown. See Additional information about properties.

The CM API includes these principal types of exceptions:
  • StpException (extends WvcmException)
  • StpPropertyException (extends StpException)
  • StpPartialResultsException (extends PropertyException)

StpException

StpException is an extension of WvcmException and is the base class of all checked exceptions thrown by the CM API. All implementations of WVCM-defined methods throw WvcmException. All public methods of the CM API that are extensions to WVCM also throw WvcmException. However, the implementations of all these methods consistently throw only StpExceptions, not WvcmExceptions. These conventions apply:
  • Throwing an StpException is never used in any method declaration (public or otherwise). Even when a method throws an StpException it is declared as if it throws a WvcmExceptions.
  • A method never throws a new WvcmExceptions. Although the exception can be expressed as a WvcmExceptions, it is always thrown as a new StpException.

StpPropertyException

StpPropertyException extends StpException and is the base exception class for errors associated with the reading or writing of resource properties.

After a property value is requested from a server, its name is associated with the result and stored in a proxy. That name is associated with the retrieved value if the retrieval attempt was successful or with status information (in the form of an StpPropertyException object) if the retrieval attempt was unsuccessful.

StpPartialResultsException

StpPartialResultsException extends StpPropertyException and is used to report the failure of an operation or property that involves multiple resources. It becomes a substitute for the ResourceList that is usually returned by the operation or property. It contains a ResourceList, which has the proxies for the resources that were successfully processed, and a list of StpExceptions, each of which corresponds to a resource for which the operation failed. See the Javadoc information for details.