Checked exception received when a DMT operation fails. Beside the exception
message, a DmtException always contains an error code (one of the
constants specified in this class), and may optionally contain the URI of the
related node, and information about the cause of the exception.

Some of the error codes defined in this class have a corresponding error code
defined in OMA DM, in these cases the name and numerical value from OMA DM is
used. Error codes without counterparts in OMA DM were given numbers from a
different range, starting from 1.

The cause of the exception (if specified) can either be a single
Throwable instance, or a list of such instances if several problems
occurred during the execution of a method. An example for the latter is the
close method of DmtSession that tries to close multiple
plugins, and has to report the exceptions of all failures.

Each constructor has two variants, one accepts a String node URI, the
other accepts a String[] node path. The former is used by the
DmtAdmin implementation, the latter by the plugins, who receive the node URI
as an array of segment names. The constructors are otherwise identical.

Getter methods are provided to retrieve the values of the additional
parameters, and the printStackTrace(PrintWriter) method is extended
to print the stack trace of all causing throwables as well.

The requested target node was not found. No indication is given as to
whether this is a temporary or permanent condition, unless otherwise
noted.

This is only used when the requested node name is valid, otherwise the
more specific error codes URI_TOO_LONG or INVALID_URI
are used. This error code corresponds to the OMA DM response status code
404 "Not Found".

The requested command failed because an optional feature required by the
command is not supported. For example, opening an atomic session might
return this error code if the DmtAdmin implementation does not support
transactions. Similarly, accessing the optional node properties (Title,
Timestamp, Version, Size) might not succeed if either the DmtAdmin
implementation or the underlying plugin does not support the property.

When getting or setting values for interior nodes (an optional
optimization feature), a plugin can use this error code to indicate that
the given interior node does not support values.

The requested node creation operation failed because the target already
exists. This can occur if the node is created directly (with one of the
create... methods), or indirectly (during a copy
operation).

The requested command failed because the principal associated with the
session does not have adequate access control permissions (ACL) on the
target. This can only appear in case of remote sessions, i.e. if the
session is associated with an authenticated principal.

The recipient encountered an error which prevented it from fulfilling the
request.

This error code is only used in situations not covered by any of the
other error codes that a method may use. Some methods specify more
specific error situations for this code, but it can generally be used for
any unexpected condition that causes the command to fail.

An error related to the recipient data store occurred while processing
the request. This error code may be thrown by any of the methods
accessing the tree, but whether it is really used depends on the
implementation, and the data store it uses.

A device initiated remote operation failed. This is used when the
protocol adapter fails to send an alert for any reason.

Alert routing errors (that occur while looking for the proper protocol
adapter to use) are indicated by ALERT_NOT_ROUTED, this code is
only for errors encountered while sending the routed alert. This error
code does not correspond to any OMA DM response status code. It should be
translated to the code 500 "Command Failed" when transferring
over OMA DM.

Operation failed because of meta data restrictions. This covers any
attempted deviation from the parameters defined by the MetaNode
objects of the affected nodes, for example in the following situations:

creating, deleting or renaming a permanent node, or modifying its
type

creating an interior node where the meta-node defines it as a leaf,
or vice versa

any operation on a node which does not have the required access type
(e.g. executing a node that lacks the MetaNode.CMD_EXECUTE access
type)

any node creation or deletion that would violate the cardinality
constraints

This error code can also be used to indicate any other meta data
violation, even if it cannot be described by the MetaNode class.
For example, detecting a multi-node constraint violation while committing
an atomic session should result in this error.

This error code does not correspond to any OMA DM response status code.
It should be translated to the code 405 "Command not allowed"
when transferring over OMA DM.

This code is only used if the URI or node name does not match any of the
criteria for URI_TOO_LONG. This error code does not correspond
to any OMA DM response status code. It should be translated to the code
404 "Not Found" when transferring over OMA DM.

An error occurred related to concurrent access of nodes. This can happen
for example if a configuration node was deleted directly through the
Configuration Admin service, while the node was manipulated via the tree.

This error code does not correspond to any OMA DM response status code.
It should be translated to the code 500 "Command Failed" when
transferring over OMA DM.

An alert can not be sent from the device to the given principal. This can
happen if there is no Remote Alert Sender willing to forward the alert to
the given principal, or if no principal was given and the DmtAdmin did
not find an appropriate default destination.

This error code does not correspond to any OMA DM response status code.
It should be translated to the code 500 "Command Failed" when
transferring over OMA DM.

Creation of a session timed out because of another ongoing session. The
length of time while the DmtAdmin waits for the blocking session(s) to
finish is implementation dependent.

This error code does not correspond to any OMA DM response status code.
OMA has several status codes related to timeout, but these are meant to
be used when a request times out, not if a session can not be
established. This error code should be translated to the code 500
"Command Failed" when transferring over OMA DM.

Create an instance of the exception, specifying the list of cause
exceptions and whether the exception is a fatal one. This constructor is
meant to be used by plugins wishing to indicate that a serious error
occurred which should invalidate the ongoing atomic session. The
uri, message and causes parameters are optional.

If a fatal exception is thrown, no further business methods will be
called on the originator plugin. In case of atomic sessions, all other
open plugins will be rolled back automatically, except if the fatal
exception was thrown during commit.

Parameters:

uri the node on which the failed DMT operation was issued, or
null if the operation is not associated with a node

code the error code of the failure

message the message associated with the exception, or null
if there is no error message

causes the list of originating exceptions, or empty list or
null if there are no originating exceptions

Create an instance of the exception, specifying the target node as an
array of path segments, and specifying the cause exception. This method
behaves in exactly the same way as if the path was given as a URI string.

Parameters:

path the path of the node on which the failed DMT operation was
issued, or null if the operation is not associated with a
node

code the error code of the failure

message the message associated with the exception, or null
if there is no error message

cause the originating exception, or null if there is no
originating exception

Create an instance of the exception, specifying the target node as an
array of path segments, the list of cause exceptions, and whether the
exception is a fatal one. This method behaves in exactly the same way as
if the path was given as a URI string.

Parameters:

path the path of the node on which the failed DMT operation was
issued, or null if the operation is not associated with a
node

code the error code of the failure

message the message associated with the exception, or null
if there is no error message

causes the list of originating exceptions, or empty list or
null if there are no originating exceptions

Get the message associated with this exception. The returned string also
contains the associated URI (if any) and the exception code. The
resulting message has the following format (parts in square brackets are
only included if the field inside them is not null):

Get the cause of this exception. Returns non-null, if this
exception is caused by one or more other exceptions (like a
NullPointerException in a DmtPlugin). If there are more than one
cause exceptions, the first one is returned.