org.osgi.service.dmt
Class DmtException

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.

UNAUTHORIZED
The originator's authentication credentials specify a principal with
insufficient rights to complete the command.

static int

URI_TOO_LONG
The requested command failed because the target URI is too long for what
the recipient is able or willing to process.

Constructor Summary

DmtException(java.lang.String[] path,
int code,
java.lang.String message)
Create an instance of the exception, specifying the target node as an
array of path segments.

DmtException(java.lang.String[] path,
int code,
java.lang.String message,
java.lang.Throwable cause)
Create an instance of the exception, specifying the target node as an
array of path segments, and specifying the cause exception.

DmtException(java.lang.String[] path,
int code,
java.lang.String message,
java.util.Vector causes,
boolean fatal)
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.

NODE_NOT_FOUND

public static final int NODE_NOT_FOUND

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".

FEATURE_NOT_SUPPORTED

public static final int FEATURE_NOT_SUPPORTED

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.

NODE_ALREADY_EXISTS

public static final int NODE_ALREADY_EXISTS

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).

PERMISSION_DENIED

public static final int PERMISSION_DENIED

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.

COMMAND_FAILED

public static final int COMMAND_FAILED

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.

DATA_STORE_FAILURE

public static final int DATA_STORE_FAILURE

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.

REMOTE_ERROR

public static final int REMOTE_ERROR

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.

METADATA_MISMATCH

public static final int METADATA_MISMATCH

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.

CONCURRENT_ACCESS

public static final int CONCURRENT_ACCESS

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.

ALERT_NOT_ROUTED

public static final int ALERT_NOT_ROUTED

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.

SESSION_CREATION_TIMEOUT

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.

DmtException

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

DmtException

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

DmtException

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

getURI

Get the node on which the failed DMT operation was issued. Some
operations like DmtSession.close() don't require an URI,
in this case this method returns null.

Returns:

the URI of the node, or null

getCode

public int getCode()

Get the error code associated with this exception. Most of the error
codes within this exception correspond to OMA DM error codes.

Returns:

the error code

getMessage

public java.lang.String getMessage()

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):

<exception_code>[: '<uri>'][: <error_message>]

Overrides:

getMessage in class java.lang.Throwable

Returns:

the error message in the format described above

getCause

public java.lang.Throwable getCause()

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.

Overrides:

getCause in class java.lang.Throwable

Returns:

the cause of this exception, or null if no cause
was given

getCauses

public java.lang.Throwable[] getCauses()

Get all causes of this exception. Returns the causing exceptions in an
array. If no cause was specified, an empty array is returned.

Returns:

the list of causes of this exception

isFatal

public boolean isFatal()

Check whether this exception is marked as fatal in the session. Fatal
exceptions trigger an automatic rollback of atomic sessions.

Returns:

whether the exception is marked as fatal

printStackTrace

public void printStackTrace(java.io.PrintStream s)

Prints the exception and its backtrace to the specified print stream. Any
causes that were specified for this exception are also printed, together
with their backtraces.