opendaylight/md-sal/sal-dom-api/src/main/java/org/opendaylight/controller/md/sal/dom/api/DOMRpcAvailabilityListener.java

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.controller.md.sal.dom.api;
   9
  10 import java.util.Collection;
  11 import java.util.EventListener;
  12 import org.eclipse.jdt.annotation.NonNull;
  13
  14 /**
  15  * An {@link EventListener} used to track RPC implementations becoming (un)available a {@link DOMRpcService}. Note that
  16  * the reported {@link DOMRpcIdentifier}s form an identifier space shared between RFC7950 actions and RFC6020 RPCs,
  17  * the former being also known as 'Routed RPCs'.
  18  *
  19  * <p>
  20  * Interpretation of DOMRpcIdentifiers has to be evaluated in the context of one of these types, which need to be
  21  * determined by matching {@link DOMRpcIdentifier#getType()} against a
  22  * {@link org.opendaylight.yangtools.yang.model.api.SchemaContext}, which determines actual semantics of
  23  * {@link DOMRpcIdentifier#getContextReference()}. Corresponding SchemaNode is required to be a known sub-interface
  24  * of {@link org.opendaylight.yangtools.yang.model.api.OperationDefinition}.
  25  *
  26  * <p>
  27  * For RFC6020 RPCs, reported context reference is always non-null and empty. It indicates an RPC implementation has
  28  * been registered and invocations can be reasonably (with obvious distributed system caveats coming from asynchronous
  29  * events) expected to succeed.
  30  *
  31  * <p>
  32  * For RFC7950 actions with a non-empty context-reference, the indication is the same as for RFC6020 RPCs.
  33  *
  34  * <p>
  35  * For RFC7950 actions with an empty context-reference, the indication is that the corresponding actions are
  36  * potentially available, but are subject to dynamic lifecycle of their context references. This includes two primary
  37  * use cases:
  38  * <ul>
  39  *     <li>dynamic action instantiation (when a device connects)</li>
  40  *     <li>dynamic action translation, such as transforming one action into another</li>
  41  * </ul>
  42  * First use case will provide further availability events with non-empty context references as they become available,
  43  * which can be safely ignored if the listener is interested in pure invocation-type integration.
  44  *
  45  * <p>
  46  * Second use case will not be providing further events, but rather will attempt to map any incoming invocation onto
  47  * some other RPC or action, or similar, which can separately fail. If a sub-request fails, such implementations are
  48  * required do report {@link DOMRpcImplementationNotAvailableException} as the invocation result, with the underlying
  49  * failure being linked as a cause.
  50  *
  51  * @deprecated Use {@link org.opendaylight.mdsal.dom.api.DOMRpcAvailabilityListener} instead.
  52  */
  53 @Deprecated
  54 public interface DOMRpcAvailabilityListener extends EventListener {
  55     /**
  56      * Method invoked whenever an RPC type becomes available.
  57      *
  58      * @param rpcs RPC types newly available
  59      */
  60     void onRpcAvailable(@NonNull Collection<DOMRpcIdentifier> rpcs);
  61
  62     /**
  63      * Method invoked whenever an RPC type becomes unavailable.
  64      *
  65      * @param rpcs RPC types which became unavailable
  66      */
  67     void onRpcUnavailable(@NonNull Collection<DOMRpcIdentifier> rpcs);
  68
  69     /**
  70      * Implementation filtering method. This method is useful for forwarding RPC implementations,
  71      * which need to ensure they do not re-announce their own implementations. Without this method
  72      * a forwarder which registers an implementation would be notified of its own implementation,
  73      * potentially re-exporting it as local -- hence creating a forwarding loop.
  74      *
  75      * @param impl RPC implementation being registered
  76      * @return False if the implementation should not be reported, defaults to true.
  77      */
  78     default boolean acceptsImplementation(final DOMRpcImplementation impl) {
  79         return true;
  80     }
  81 }