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 ClearQuest® 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 ClearQuest 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 ClearQuest CM API. All implementations
of WVCM-defined methods throw
WvcmException.
All public methods of the ClearQuest 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.