All
problems are reported by means of an exception object, which is a subclass
of the exception object defined by WVCM. From such an exception, the client
can obtain the following information:
- 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 Rational® 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 Rational 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 Rational CM API. All implementations
of WVCM-defined methods throw WvcmException. All public methods of the Rational 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 a 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 WvcmException.
- A method never throws a new WvcmException. Although the exception can
be expressed as a WvcmException, it is always thrown as a new StpException.
StpPropertyException
StpPropertyException extends
StpExtension 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. For details see the Javadoc
information.