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.SchemaPath;
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(SchemaPath, 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 listener {@link AvailabilityListener} instance to register
41 * @return A {@link ListenerRegistration} representing this registration. Performing a
42 * {@link ListenerRegistration#close()} will cancel it.
43 * @throws NullPointerException if {@code listener} is null
45 <T extends AvailabilityListener> ListenerRegistration<T> registerAvailabilityListener(T listener);
48 * An {@link EventListener} used to track Operation implementations becoming (un)available
49 * to a {@link DOMActionService}.
51 interface AvailabilityListener extends EventListener {
53 * Method invoked whenever an action type becomes available or unavailable. There are two sets reported,
54 * removed and added. To reconstruct the state, first apply removed and then added operations, like this:
57 * Set<DOMActionInstancelt;?>> operations;
58 * operations.removeAll(removed);
59 * operations.addAll(added);
62 * @param removed operations which disappeared
63 * @param added operations which became available
65 void onActionsChanged(Set<DOMActionInstance> removed, Set<DOMActionService> added);
68 * Implementation filtering method. This method is useful for forwarding operation implementations,
69 * which need to ensure they do not re-announce their own implementations. Without this method
70 * a forwarder which registers an implementation would be notified of its own implementation,
71 * potentially re-exporting it as local -- hence creating a forwarding loop.
73 * @param impl Operation implementation being registered
74 * @return False if the implementation should not be reported, defaults to true.
76 default boolean acceptsImplementation(final DOMActionImplementation impl) {