2 * Copyright (c) 2018 Pantheon Technologies, s.r.o. and others. All rights reserved.
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
8 package org.opendaylight.mdsal.dom.api;
10 import com.google.common.annotations.Beta;
11 import java.util.EventListener;
13 import org.eclipse.jdt.annotation.NonNullByDefault;
14 import org.opendaylight.yangtools.concepts.ListenerRegistration;
15 import org.opendaylight.yangtools.yang.common.QName;
16 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
17 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
20 * An {@link DOMOperationServiceExtension} exposed by {@link DOMOperationService}s which allow their users to listen
21 * for operations becoming available.
23 * @author Robert Varga
27 public interface DOMOperationAvailabilityExtension extends DOMOperationServiceExtension {
29 * Register a {@link AvailabilityListener} with this service to receive notifications about operation
30 * implementations becoming (un)available. The listener will be invoked with the current implementations reported
31 * and will be kept uptodate as implementations come and go.
34 * Users should note that using a listener does not necessarily mean that
35 * {@link DOMOperationService#invokeRpc(QName, ContainerNode)} and
36 * {@link DOMOperationService#invokeAction(SchemaPath, DOMDataTreeIdentifier, ContainerNode)} will not report
37 * a failure due to {@link DOMOperationNotAvailableException} and need to be ready to handle it.
40 * Implementations are encouraged to take reasonable precautions to prevent this scenario from occurring.
42 * @param listener {@link AvailabilityListener} instance to register
43 * @return A {@link ListenerRegistration} representing this registration. Performing a
44 * {@link ListenerRegistration#close()} will cancel it.
45 * @throws NullPointerException if {@code listener} is null
47 <T extends AvailabilityListener> ListenerRegistration<T> registerAvailabilityListener(T listener);
50 * An {@link EventListener} used to track Operation implementations becoming (un)available
51 * to a {@link DOMOperationService}.
53 interface AvailabilityListener extends EventListener {
55 * Method invoked whenever an operation type becomes available or unavailable. There are two sets reported,
56 * removed and added. To reconstruct the state, first apply removed and then added operations, like this:
59 * Set<AvailableOperation<?>> operations;
60 * operations.removeAll(removed);
61 * operations.addAll(added);
64 * @param removed operations which disappeared
65 * @param added operations which became available
67 void onOperationsChanged(Set<DOMOperationInstance<?>> removed, Set<DOMOperationInstance<?>> added);
70 * Implementation filtering method. This method is useful for forwarding operation 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.
75 * @param impl Operation implementation being registered
76 * @return False if the implementation should not be reported, defaults to true.
78 default boolean acceptsImplementation(final DOMOperationImplementation impl) {