DmtException
Date: 2016-06-25

org.osgi.service.dmt

## Class DmtException

- java.lang.Object
- - java.lang.Throwable
  - - java.lang.Exception
    - - org.osgi.service.dmt.DmtException

- All Implemented Interfaces:
    java.io.Serializable

      public class DmtException
      extends java.lang.Exception

  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.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ALERT_NOT_ROUTED` An alert can not be sent from the device to the given principal.
    `static int` | `COMMAND_FAILED` The recipient encountered an error which prevented it from fulfilling the request.
    `static int` | `COMMAND_NOT_ALLOWED` The requested command is not allowed on the target node.
    `static int` | `CONCURRENT_ACCESS` An error occurred related to concurrent access of nodes.
    `static int` | `DATA_STORE_FAILURE` An error related to the recipient data store occurred while processing the request.
    `static int` | `FEATURE_NOT_SUPPORTED` The requested command failed because an optional feature required by the command is not supported.
    `static int` | `INVALID_URI` The requested command failed because the target URI or node name is `null` or syntactically invalid.
    `static int` | `LIMIT_EXCEEDED` The requested operation failed because a specific limit was exceeded, e.g.
    `static int` | `METADATA_MISMATCH` Operation failed because of meta data restrictions.
    `static int` | `NODE_ALREADY_EXISTS` The requested node creation operation failed because the target already exists.
    `static int` | `NODE_NOT_FOUND` The requested target node was not found.
    `static 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.
    `static int` | `REMOTE_ERROR` A device initiated remote operation failed.
    `static int` | `ROLLBACK_FAILED` The rollback command was not completed successfully.
    `static int` | `SESSION_CREATION_TIMEOUT` Creation of a session timed out because of another ongoing session.
    `static int` | `TRANSACTION_ERROR` A transaction-related error occurred in an atomic session.
    `static int` | `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

    Constructors
    Constructor and Description
    `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.
    `DmtException(java.lang.String uri, int code, java.lang.String message)` Create an instance of the exception.
    `DmtException(java.lang.String uri, int code, java.lang.String message, java.lang.Throwable cause)` Create an instance of the exception, specifying the cause exception.
    `DmtException(java.lang.String uri, int code, java.lang.String message, java.util.Vector causes, boolean fatal)` Create an instance of the exception, specifying the list of cause exceptions and whether the exception is a fatal one.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Throwable` | `getCause()` Get the cause of this exception.
    `java.lang.Throwable[]` | `getCauses()` Get all causes of this exception.
    `int` | `getCode()` Get the error code associated with this exception.
    `java.lang.String` | `getMessage()` Get the message associated with this exception.
    `java.lang.String` | `getURI()` Get the node on which the failed DMT operation was issued.
    `boolean` | `isFatal()` Check whether this exception is marked as fatal in the session.
    `void` | `printStackTrace(java.io.PrintStream s)` Prints the exception and its stacktrace to the specified print stream.

    - ### Methods inherited from class java.lang.Throwable

      `addSuppressed, fillInStackTrace, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### UNAUTHORIZED

          public static final int UNAUTHORIZED

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

      This status code is used as response to device originated sessions if the remote management server cannot authorize the device to perform the requested operation.

      This error code corresponds to the OMA DM response status code 401 "Unauthorized".

      See Also:
        Constant Field Values

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

      See Also:
        Constant Field Values

    - #### COMMAND_NOT_ALLOWED

          public static final int COMMAND_NOT_ALLOWED

      The requested command is not allowed on the target node. This includes the following situations:
      - an interior node operation is requested for a leaf node, or vice versa (e.g. trying to retrieve the children of a leaf node)
      - an attempt is made to create a node where the parent is a leaf node
      - an attempt is made to rename or delete the root node of the tree
      - an attempt is made to rename or delete the root node of the session
      - a write operation (other than setting the ACL) is performed in a non-atomic write session on a node provided by a plugin that is read-only or does not support non-atomic writing
      - a node is copied to its descendant
      - the ACL of the root node is changed not to include Add rights for all principals

      This error code corresponds to the OMA DM response status code 405 "Command not allowed".

      See Also:
        Constant Field Values

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

      This error code corresponds to the OMA DM response status code 406 "Optional feature not supported".

      See Also:
        Constant Field Values

    - #### LIMIT_EXCEEDED

          public static final int LIMIT_EXCEEDED

      The requested operation failed because a specific limit was exceeded, e.g. if a requested resource exceeds a size limit.

      This error code corresponds to the OMA DM response status code 413 "Request entity too large".

      Since:
        2.0
      See Also:
        Constant Field Values

    - #### URI_TOO_LONG

          public static final 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.

      This error code corresponds to the OMA DM response status code 414 "URI too long".

      See Also:
        "OSGi Service Platform, Mobile Specification Release 4", Constant Field 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).

      This error code corresponds to the OMA DM response status code 418 "Already exists".

      See Also:
        Constant Field Values

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

      This error code corresponds to the OMA DM response status code 425 "Permission denied".

      See Also:
        Constant Field Values

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

      This error code corresponds to the OMA DM response status code 500 "Command Failed".

      See Also:
        Constant Field Values

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

      This error code corresponds to the OMA DM response status code 510 "Data store failure".

      See Also:
        Constant Field Values

    - #### ROLLBACK_FAILED

          public static final int ROLLBACK_FAILED

      The rollback command was not completed successfully. The tree might be in an inconsistent state after this error.

      This error code corresponds to the OMA DM response status code 516 "Atomic roll back failed".

      See Also:
        Constant Field Values

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

      See Also:
        Constant Field Values

    - #### 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
      - any leaf node value setting that would violate the allowed formats, values, mime types, etc.
      - any node creation that would violate the allowed node names

      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.

      See Also:
        Constant Field Values

    - #### INVALID_URI

          public static final int INVALID_URI

      The requested command failed because the target URI or node name is `null` or syntactically invalid. This covers the following cases:
      - the URI or node name ends with the '\' or '/' character
      - the URI is an empty string (only invalid if the method does not accept relative URIs)
      - the URI contains the segment "`.`" at a position other than the beginning of the URI
      - the node name is "`..`" or the URI contains such a segment
      - the node name contains an unescaped '/' character

      See the `Uri.encode(String)` method for support on escaping invalid characters in a URI.

      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.

      See Also:
        Constant Field Values

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

      See Also:
        Constant Field Values

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

      See Also:
        Constant Field Values

    - #### TRANSACTION_ERROR

          public static final int TRANSACTION_ERROR

      A transaction-related error occurred in an atomic session. This error is caused by one of the following situations:
      - an updating method within an atomic session can not be executed because the underlying plugin is read-only or does not support atomic writing
      - a commit operation at the end of an atomic session failed because one of the underlying plugins failed to close
      The latter case may leave the tree in an inconsistent state due to the lack of a two-phase commit system, see `DmtSession.commit()` for details.

      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.

      See Also:
        Constant Field Values

    - #### SESSION_CREATION_TIMEOUT

          public static final int 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.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DmtException

          public DmtException(java.lang.String uri,
                      int code,
                      java.lang.String message)

      Create an instance of the exception. The `uri` and `message` parameters are optional. No originating exception is specified.
      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

    - #### DmtException

          public DmtException(java.lang.String uri,
                      int code,
                      java.lang.String message,
                      java.lang.Throwable cause)

      Create an instance of the exception, specifying the cause exception. The `uri`, `message` and `cause` parameters are optional.
      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
        `cause` - the originating exception, or `null` if there is no originating exception

    - #### DmtException

          public DmtException(java.lang.String uri,
                      int code,
                      java.lang.String message,
                      java.util.Vector causes,
                      boolean fatal)

      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
        `fatal` - whether the exception is fatal

    - #### DmtException

          public 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. 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
      See Also:
        `DmtException(String, int, String)`

    - #### DmtException

          public 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. 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
      See Also:
        `DmtException(String, int, String, Throwable)`

    - #### DmtException

          public 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. 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
        `fatal` - whether the exception is fatal
      See Also:
        `DmtException(String, int, String, Vector, boolean)`

  - ### Method Detail

    - #### getURI

          public java.lang.String 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 stacktrace to the specified print stream. Any causes that were specified for this exception are also printed, together with their stacktraces.
      Overrides:
        `printStackTrace` in class `java.lang.Throwable`
      Parameters:
        `s` - `PrintStream` to use for output