From: Robert Varga Date: Wed, 25 Jan 2017 21:47:02 +0000 (+0100) Subject: BUG-7608: Clarify DOMRpc routing/invocation/listener interactions X-Git-Tag: release/carbon~301 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=commitdiff_plain;h=aa342f77a044988c1f6a0deaf9f7e94373f2dfb5;hp=a3737302942580f13ca9988647873b83985895ed BUG-7608: Clarify DOMRpc routing/invocation/listener interactions As it happens our DOMRpcProviderService is under-documented around routing behavior and how it interacts with respect to both DOMRpcService and DOMRpcAvailabilityListener. Fix this by defining the interactions the same way they are implemented in the only implementation, DOMRpcRouter. The fallout of these clarifications is that blueprint's interpretation of the API contract covers only the RFC6020 RPC part correctly and falls short of the RFC7950 action case. This shortcoming will be addressed in a follow-up patch. Change-Id: I2572c21b7aa6f24b9e2ed37f446b76a032f1880b Signed-off-by: Robert Varga --- 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 35c58feb16..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'. + * + *

+ * 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}. + * + *

+ * 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. + * + *

+ * For RFC7950 actions with a non-empty context-reference, the indication is the same as for RFC6020 RPCs. + * + *

+ * 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: + *

+ * 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. + * + *

+ * 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 { /** diff --git a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcProviderService.java b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcProviderService.java index 4a4f9656ba..82de4b02a2 100644 --- a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcProviderService.java +++ b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcProviderService.java @@ -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}. + * + *

+ * 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: + *

+ * + *

+ * 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 DOMRpcImplementationRegistration registerRpcImplementation(@Nonnull T implementation, @Nonnull DOMRpcIdentifier... rpcs); + @Nonnull DOMRpcImplementationRegistration 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 DOMRpcImplementationRegistration registerRpcImplementation(@Nonnull T implementation, @Nonnull Set rpcs); + @Nonnull DOMRpcImplementationRegistration registerRpcImplementation( + @Nonnull T implementation, @Nonnull Set rpcs); } diff --git a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcService.java b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcService.java index e0c95a197b..c84e2d3ad0 100644 --- a/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcService.java +++ b/opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcService.java @@ -31,17 +31,22 @@ public interface DOMRpcService extends DOMService { * or report a subclass of {@link DOMRpcException} reporting a transport * error. */ - @Nonnull CheckedFuture invokeRpc(@Nonnull SchemaPath type, @Nullable NormalizedNode input); + @Nonnull CheckedFuture invokeRpc(@Nonnull SchemaPath type, + @Nullable NormalizedNode input); /** * Register a {@link DOMRpcAvailabilityListener} with this service to receive notifications * about RPC implementations becoming (un)available. The listener will be invoked with the * current implementations reported and will be kept uptodate as implementations come and go. * - * Users should note that using a listener does not necessarily mean that {@link #invokeRpc(SchemaPath, NormalizedNode)} - * will not report a failure due to {@link DOMRpcImplementationNotAvailableException} and - * need to be ready to handle it. Implementations are encouraged to take reasonable precautions - * to prevent this scenario from occurring. + *

+ * Users should note that using a listener does not necessarily mean that + * {@link #invokeRpc(SchemaPath, NormalizedNode)} will not report a failure due to + * {@link DOMRpcImplementationNotAvailableException} and need to be ready to handle it. + * + *

+ * Implementations of this interface are encouraged to take reasonable precautions to prevent this scenario from + * occurring. * * @param listener {@link DOMRpcAvailabilityListener} instance to register * @return A {@link ListenerRegistration} representing this registration. Performing