Exceptions
All problems are reported by means of an exception object, which is a subclass of the exception object defined by WVCM.
- 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.
- 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 StpException
s, not
WvcmExceptions
. These conventions apply:- Throwing an
StpException
is never used in any method declaration (public or otherwise). Even when a method throws anStpException
it is declared as if it throws aWvcmExceptions
. - A method never throws a new
WvcmExceptions
. Although the exception can be expressed as aWvcmExceptions
, it is always thrown as a newStpException
.
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.