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.data.api.schema.ContainerNode;
16 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
19 * An {@link DOMActionServiceExtension} exposed by {@link DOMActionService}s which allow their users to listen
20 * for actions are becoming available.
22 * @author Robert Varga
26 public interface DOMActionAvailabilityExtension extends DOMActionServiceExtension {
28 * Register a {@link AvailabilityListener} with this service to receive notifications about operation
29 * implementations becoming (un)available. The listener will be invoked with the current implementations reported
30 * and will be kept uptodate as implementations come and go.
33 * Users should note that using a listener does not necessarily mean that
34 * {@link DOMActionService#invokeAction(Absolute, DOMDataTreeIdentifier, ContainerNode)} will not report
35 * a failure due to {@link DOMActionNotAvailableException} and need to be ready to handle it.
38 * Implementations are encouraged to take reasonable precautions to prevent this scenario from occurring.
40 * @param <T> Listener type
41 * @param listener {@link AvailabilityListener} instance to register
42 * @return A {@link ListenerRegistration} representing this registration. Performing a
43 * {@link ListenerRegistration#close()} will cancel it.
44 * @throws NullPointerException if {@code listener} is null
46 <T extends AvailabilityListener> ListenerRegistration<T> registerAvailabilityListener(T listener);
49 * An {@link EventListener} used to track Operation implementations becoming (un)available
50 * to a {@link DOMActionService}.
52 interface AvailabilityListener extends EventListener {
54 * Method invoked whenever an action type becomes available or unavailable. There are two sets reported,
55 * removed and added. To reconstruct the state, first apply removed and then added operations, like this:
58 * Set<DOMActionInstancelt;?>> operations;
59 * operations.removeAll(removed);
60 * operations.addAll(added);
63 * @param removed operations which disappeared
64 * @param added operations which became available
66 void onActionsChanged(Set<DOMActionInstance> removed, Set<DOMActionInstance> added);
69 * Implementation filtering method. This method is useful for forwarding operation implementations,
70 * which need to ensure they do not re-announce their own implementations. Without this method
71 * a forwarder which registers an implementation would be notified of its own implementation,
72 * potentially re-exporting it as local -- hence creating a forwarding loop.
74 * @param impl Operation implementation being registered
75 * @return False if the implementation should not be reported, defaults to true.
77 default boolean acceptsImplementation(final DOMActionImplementation impl) {