DmtEvent
Date: 2016-06-25

org.osgi.service.dmt

## Interface DmtEvent

-     public interface DmtEvent

  Event class storing the details of a change in the tree. `DmtEvent` is used by `DmtAdmin` to notify registered `EventListeners` services about important changes. Events are generated after every successful DMT change, and also when sessions are opened or closed. If a `DmtSession` is opened in atomic mode, DMT events are only sent when the session is committed, when the changes are actually performed.

  The `type` of the event describes the change that triggered the event delivery. Each event carries the unique identifier of the session in which the described change happened or -1 when the change originated outside a session. The events describing changes in the DMT carry the list of affected nodes. In case of `COPIED` or `RENAMED` events, the event carries the list of new nodes as well.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ADDED` Event type indicating nodes that were added.
    `static int` | `COPIED` Event type indicating nodes that were copied.
    `static int` | `DELETED` Event type indicating nodes that were deleted.
    `static int` | `RENAMED` Event type indicating nodes that were renamed.
    `static int` | `REPLACED` Event type indicating nodes that were replaced.
    `static int` | `SESSION_CLOSED` Event type indicating that a session was closed.
    `static int` | `SESSION_OPENED` Event type indicating that a new session was opened.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String[]` | `getNewNodes()` This method can be used to query the new nodes, when the type of the event is `COPIED` or `RENAMED`.
    `java.lang.String[]` | `getNodes()` This method can be used to query the subject nodes of this event.
    `java.lang.Object` | `getProperty(java.lang.String key)` This method can be used to get the value of a single event property.
    `java.lang.String[]` | `getPropertyNames()` This method can be used to query the names of all properties of this event.
    `int` | `getSessionId()` This method returns the identifier of the session in which this event took place.
    `int` | `getType()` This method returns the type of this event.

- - ### Field Detail

    - #### ADDED

          static final int ADDED

      Event type indicating nodes that were added.
      See Also:
        Constant Field Values

    - #### COPIED

          static final int COPIED

      Event type indicating nodes that were copied.
      See Also:
        Constant Field Values

    - #### DELETED

          static final int DELETED

      Event type indicating nodes that were deleted.
      See Also:
        Constant Field Values

    - #### RENAMED

          static final int RENAMED

      Event type indicating nodes that were renamed.
      See Also:
        Constant Field Values

    - #### REPLACED

          static final int REPLACED

      Event type indicating nodes that were replaced.
      See Also:
        Constant Field Values

    - #### SESSION_OPENED

          static final int SESSION_OPENED

      Event type indicating that a new session was opened.
      See Also:
        Constant Field Values

    - #### SESSION_CLOSED

          static final int SESSION_CLOSED

      Event type indicating that a session was closed. This type of event is sent when the session is closed by the client or becomes inactive for any other reason (session timeout, fatal errors in business methods, etc.).
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getType

          int getType()

      This method returns the type of this event.
      Returns:
        the type of this event.

    - #### getSessionId

          int getSessionId()

      This method returns the identifier of the session in which this event took place. The ID is guaranteed to be unique on a machine.

      For events that do not result from a session, the session id is -1.

      The availability of a session.id can also be check by using `getProperty()` with "session.id" as key.

      Returns:
        the unique identifier of the session that triggered the event or -1 if there is no session associated

    - #### getNodes

          java.lang.String[] getNodes()

      This method can be used to query the subject nodes of this event. The method returns `null` for `SESSION_OPENED` and `SESSION_CLOSED`.

      The method returns only those affected nodes that the caller has the GET permission for (or in case of `COPIED` or `RENAMED` events, where the caller has GET permissions for either the source or the destination nodes). Therefore, it is possible that the method returns an empty array. All returned URIs are absolute.

      Returns:
        the array of affected nodes
      See Also:
        `getNewNodes()`

    - #### getNewNodes

          java.lang.String[] getNewNodes()

      This method can be used to query the new nodes, when the type of the event is `COPIED` or `RENAMED`. For all other event types this method returns `null`.

      The array returned by this method runs parallel to the array returned by `getNodes()`, the elements in the two arrays contain the source and destination URIs for the renamed or copied nodes in the same order. All returned URIs are absolute.

      This method returns only those nodes where the caller has the GET permission for the source or destination node of the operation. Therefore, it is possible that the method returns an empty array.

      Returns:
        the array of newly created nodes

    - #### getPropertyNames

          java.lang.String[] getPropertyNames()

      This method can be used to query the names of all properties of this event.

      The returned names can be used as key value in subsequent calls to `getProperty(String)`.

      Returns:
        the array of property names
      Since:
        2.0
      See Also:
        `getProperty(String)`

    - #### getProperty

          java.lang.Object getProperty(java.lang.String key)

      This method can be used to get the value of a single event property.
      Parameters:
        `key` - the name of the requested property
      Returns:
        the requested property value or null, if the key is not contained in the properties
      Since:
        2.0
      See Also:
        `getPropertyNames()`