BUG-7608: Clarify DOMRpc routing/invocation/listener interactions
[controller.git] / opendaylight / md-sal / sal-dom-api / src / main / java / org / opendaylight / controller / md / sal / dom / api / DOMRpcProviderService.java
index 4a4f965..82de4b0 100644 (file)
@@ -11,8 +11,23 @@ import java.util.Set;
 import javax.annotation.Nonnull;
 
 /**
- * A {@link DOMService} which allows registration of RPC implementations with a conceptual
- * router. The client counterpart of this service is {@link DOMRpcService}.
+ * A {@link DOMService} which allows registration of RPC implementations with a conceptual router. The client
+ * counterpart of this service is {@link DOMRpcService}.
+ *
+ * <p>
+ * This interface supports both RFC6020 RPCs and RFC7950 actions (formerly known as 'Routed RPCs'. Invocation for
+ * RFC6020 RPCs is always based on an empty context reference. Invocation of actions requires a non-empty context
+ * reference and is matched against registered implementations as follows:
+ * <ul>
+ *     <li>First, attempt to look up the implementation based on exact match. If a match is found the invocation is
+ *         on that implementation, returning its result.</li>
+ *     <li>Second, attempt to look up the implementation which registered for empty context reference. If a such an
+ *         implementation exists, invoke that implementation, returning its result</li>
+ *     <li>Throw {@link DOMRpcImplementationNotAvailableException}
+ * </ul>
+ *
+ * <p>
+ * All implementations are required to perform these steps as specified above.
  */
 public interface DOMRpcProviderService extends DOMService {
     /**
@@ -25,7 +40,8 @@ public interface DOMRpcProviderService extends DOMService {
      * @throws NullPointerException if implementation or types is null
      * @throws IllegalArgumentException if types is empty or contains a null element.
      */
-    @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(@Nonnull T implementation, @Nonnull DOMRpcIdentifier... rpcs);
+    @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(
+            @Nonnull T implementation, @Nonnull DOMRpcIdentifier... rpcs);
 
     /**
      * Register an {@link DOMRpcImplementation} object with this service.
@@ -36,5 +52,6 @@ public interface DOMRpcProviderService extends DOMService {
      * @throws NullPointerException if implementation or types is null
      * @throws IllegalArgumentException if types is empty or contains a null element.
      */
-    @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(@Nonnull T implementation, @Nonnull Set<DOMRpcIdentifier> rpcs);
+    @Nonnull <T extends DOMRpcImplementation> DOMRpcImplementationRegistration<T> registerRpcImplementation(
+            @Nonnull T implementation, @Nonnull Set<DOMRpcIdentifier> rpcs);
 }