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 java.util.concurrent.Executor;
14 import org.eclipse.jdt.annotation.NonNullByDefault;
15 import org.opendaylight.yangtools.concepts.ListenerRegistration;
16 import org.opendaylight.yangtools.yang.common.QName;
17 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
18 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
21 * An {@link DOMOperationServiceExtension} exposed by {@link DOMOperationService}s which allow their users to listen
22 * for operations becoming available.
24 * @author Robert Varga
28 public interface DOMOperationAvailabilityExtension extends DOMOperationServiceExtension {
30 * Register a {@link AvailabilityListener} with this service to receive notifications about operation
31 * implementations becoming (un)available. The listener will be invoked with the current implementations reported
32 * and will be kept uptodate as implementations come and go.
35 * Users should note that using a listener does not necessarily mean that
36 * {@link DOMOperationService#invokeRpc(QName, NormalizedNode, DOMOperationCallback, Executor)} and
37 * {@link DOMOperationService#invokeAction(SchemaPath, DOMDataTreeIdentifier, NormalizedNode)} will not report
38 * a failure due to {@link DOMOperationNotAvailableException} and need to be ready to handle it.
41 * Implementations are encouraged to take reasonable precautions to prevent this scenario from occurring.
43 * @param listener {@link AvailabilityListener} instance to register
44 * @return A {@link ListenerRegistration} representing this registration. Performing a
45 * {@link ListenerRegistration#close()} will cancel it.
46 * @throws NullPointerException if {@code listener} is null
48 <T extends AvailabilityListener> ListenerRegistration<T> registerAvailabilityListener(T listener);
51 * An {@link EventListener} used to track Operation implementations becoming (un)available
52 * to a {@link DOMOperationService}.
54 interface AvailabilityListener extends EventListener {
56 * Method invoked whenever an operation type becomes available or unavailable. There are two sets reported,
57 * removed and added. To reconstruct the state, first apply removed and then added operations, like this:
60 * Set<AvailableOperation<?>> operations;
61 * operations.removeAll(removed);
62 * operations.addAll(added);
65 * @param removed operations which disappeared
66 * @param added operations which became available
68 void onOperationsChanged(Set<DOMOperationInstance<?>> removed, Set<DOMOperationInstance<?>> added);
71 * Implementation filtering method. This method is useful for forwarding operation implementations,
72 * which need to ensure they do not re-announce their own implementations. Without this method
73 * a forwarder which registers an implementation would be notified of its own implementation,
74 * potentially re-exporting it as local -- hence creating a forwarding loop.
76 * @param impl Operation implementation being registered
77 * @return False if the implementation should not be reported, defaults to true.
79 default boolean acceptsImplementation(final DOMOperationImplementation impl) {