X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blobdiff_plain;f=opendaylight%2Fmd-sal%2Fsal-dom-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fmd%2Fsal%2Fdom%2Fapi%2FDOMRpcAvailabilityListener.java;h=a62f79db0bf71c1b1baf6019053154f9a99528a6;hp=77d42a43c994edca187aa8cde354ffb6f881a983;hb=aa342f77a044988c1f6a0deaf9f7e94373f2dfb5;hpb=4ac1576e7d2d5de5cf2828b829e34833bcfa8da7

diff --git a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcAvailabilityListener.java b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcAvailabilityListener.java
index 77d42a43c9..a62f79db0b 100644
--- a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcAvailabilityListener.java
+++ b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcAvailabilityListener.java
@@ -12,8 +12,41 @@ import java.util.EventListener;
 import javax.annotation.Nonnull;
 
 /**
- * An {@link EventListener} used to track RPC implementations becoming (un)available
- * to a {@link DOMRpcService}.
+ * An {@link EventListener} used to track RPC implementations becoming (un)available a {@link DOMRpcService}. Note that
+ * the reported {@link DOMRpcIdentifier}s form an identifier space shared between RFC7950 actions and RFC6020 RPCs,
+ * the former being also known as 'Routed RPCs'.
+ *
+ * <p>
+ * Interpretation of DOMRpcIdentifiers has to be evaluated in the context of one of these types, which need to be
+ * determined by matching {@link DOMRpcIdentifier#getType()} against a
+ * {@link org.opendaylight.yangtools.yang.model.api.SchemaContext}, which determines actual semantics of
+ * {@link DOMRpcIdentifier#getContextReference()}. Corresponding SchemaNode is required to be a known sub-interface
+ * of {@link org.opendaylight.yangtools.yang.model.api.OperationDefinition}.
+ *
+ * <p>
+ * For RFC6020 RPCs, reported context reference is always non-null and empty. It indicates an RPC implementation has
+ * been registered and invocations can be reasonably (with obvious distributed system caveats coming from asynchronous
+ * events) expected to succeed.
+ *
+ * <p>
+ * For RFC7950 actions with a non-empty context-reference, the indication is the same as for RFC6020 RPCs.
+ *
+ * <p>
+ * For RFC7950 actions with an empty context-reference, the indication is that the corresponding actions are
+ * potentially available, but are subject to dynamic lifecycle of their context references. This includes two primary
+ * use cases:
+ * <ul>
+ *     <li>dynamic action instantiation (when a device connects)</li>
+ *     <li>dynamic action translation, such as transforming one action into another</li>
+ * </ul>
+ * First use case will provide further availability events with non-empty context references as they become available,
+ * which can be safely ignored if the listener is interested in pure invocation-type integration.
+ *
+ * <p>
+ * Second use case will not be providing further events, but rather will attempt to map any incoming invocation onto
+ * some other RPC or action, or similar, which can separately fail. If a sub-request fails, such implementations are
+ * required do report {@link DOMRpcImplementationNotAvailableException} as the invocation result, with the underlying
+ * failure being linked as a cause.
  */
 public interface DOMRpcAvailabilityListener extends EventListener {
     /**
@@ -29,4 +62,17 @@ public interface DOMRpcAvailabilityListener extends EventListener {
      * @param rpcs RPC types which became unavailable
      */
     void onRpcUnavailable(@Nonnull Collection<DOMRpcIdentifier> rpcs);
+
+    /**
+     * Implementation filtering method. This method is useful for forwarding RPC implementations,
+     * which need to ensure they do not re-announce their own implementations. Without this method
+     * a forwarder which registers an implementation would be notified of its own implementation,
+     * potentially re-exporting it as local -- hence creating a forwarding loop.
+     *
+     * @param impl RPC implementation being registered
+     * @return False if the implementation should not be reported, defaults to true.
+     */
+    default boolean acceptsImplementation(final DOMRpcImplementation impl) {
+        return true;
+    }
 }