c26b84acdda63e3e105311c9734ce631b8dad8f8
[controller.git] / 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 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.