Clarify DOMEvent and DOMNotification relationship

The relationship between these interfaces is realized in the
implementation, but it is not captured in the interface contract
documentation.

JIRA: MDSAL-282
Change-Id: I99d8787a16263c6628440dac8b3bd7a6bbec3f9c
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit ae3fde5afcd6811321b8f9cbbf2f6da1661b5610)

diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMEvent.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMEvent.java
index 6c820e38bcbb2184e223d8ffe6a75f40c4d4b5d7..a0a7a5efcc2c2060f3d8d0d70fe5a4bc749da271 100644 (file)
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMEvent.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMEvent.java
@@ -10,7 +10,8 @@ package org.opendaylight.mdsal.dom.api;
 import java.time.Instant;
 
 /**
- * Generic event interface.
+ * Generic event interface. This interface is mixed in into implementations of other DOM-level constructs, such as
+ * {@link DOMNotification} to add the time when the event occurred when appropriate.
  */
 public interface DOMEvent {
     /**

diff --git a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMNotification.java b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMNotification.java
index 0d0438c55a8e3669efd1a81ba33dbf885c94034b..675e1e286904ea1c1241a5d4e5d116221e824fee 100644 (file)
--- a/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMNotification.java
+++ b/dom/mdsal-dom-api/src/main/java/org/opendaylight/mdsal/dom/api/DOMNotification.java
@@ -12,7 +12,10 @@ import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
 
 /**
- * A single YANG notification.
+ * A single YANG notification. This interface captures the data portion of a notification. Implementations may choose
+ * to additionally implement {@link DOMEvent}, in which case {@link DOMEvent#getEventInstant()} returns the time when
+ * this notification was generated -- and corresponds to <a href="https://tools.ietf.org/html/rfc5277#section-2.2.1">
+ * RFC5277</a> NETCONF notification's {@code eventTime} parameter.
  */
 public interface DOMNotification {
     /**