From 9d62ee898563bd9ff7e5cb48861ca0466dacf1da Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Fri, 8 Dec 2023 17:37:15 +0100 Subject: [PATCH] Deprecate ListenerRegistration for removal This interface brings very little to the table and binds to j.u.EventListener as if it were a good idea. Deprecate it for removal, guiding users towards ObjectRegistration instead. JIRA: YANGTOOLS-1551 Change-Id: Id621532b52bb7d9d4cea335d6841bf110a68af62 Signed-off-by: Robert Varga --- .../yangtools/concepts/AbstractListenerRegistration.java | 2 +- .../yangtools/concepts/ListenerRegistration.java | 2 ++ .../yangtools/concepts/NoOpListenerRegistration.java | 2 ++ .../opendaylight/yangtools/concepts/Registration.java | 9 +++++++++ 4 files changed, 14 insertions(+), 1 deletion(-) diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java index 872816affd..982e7c9e48 100644 --- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java +++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java @@ -10,9 +10,9 @@ package org.opendaylight.yangtools.concepts; import java.util.EventListener; import org.eclipse.jdt.annotation.NonNull; +@Deprecated(since = "12.0.0", forRemoval = true) public abstract class AbstractListenerRegistration extends AbstractObjectRegistration implements ListenerRegistration { - protected AbstractListenerRegistration(final @NonNull T listener) { super(listener); } diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java index 02d0d60925..7022292b44 100644 --- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java +++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java @@ -14,7 +14,9 @@ import java.util.EventListener; * guarantee that the process of unregistration cannot fail for predictable reasons. * * @param Type of registered listener + * @deprecated Use {@link ObjectRegistration} instead */ +@Deprecated(since = "12.0.0", forRemoval = true) public interface ListenerRegistration extends ObjectRegistration { /** * Unregister the listener. Note that invocations enqueued to the listener are not subject to synchronization diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/NoOpListenerRegistration.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/NoOpListenerRegistration.java index 26e2ca790f..73740e8dca 100644 --- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/NoOpListenerRegistration.java +++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/NoOpListenerRegistration.java @@ -14,8 +14,10 @@ import org.eclipse.jdt.annotation.NonNullByDefault; * Implementation of {@link ListenerRegistration} which does nothing in its {@link #close()} method. * * @param Type of registered listener + * @deprecated Use {@link NoOpObjectRegistration} instead */ @NonNullByDefault +@Deprecated(since = "12.0.0", forRemoval = true) public final class NoOpListenerRegistration extends NoOpObjectRegistration implements ListenerRegistration { private NoOpListenerRegistration(final T instance) { diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java index c166eb6394..cbf0a2aac9 100644 --- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java +++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java @@ -16,6 +16,15 @@ public interface Registration extends AutoCloseable { * Unregisters the object. This operation is required not to invoke blocking operations. Implementations which * require interaction with outside world must provide guarantees that any work is done behind the scenes and * the unregistration process looks as if it has already succeeded once this method returns. + * + *

+ * The above requirement does not necessarily mean that all interactions with the registered entity seize before + * this method returns, but they should complete within a reasonable time frame. + * + *

+ * While the interface contract allows an implementation to ignore the occurrence of RuntimeExceptions, + * implementations are strongly encouraged to deal with such exceptions internally and to ensure invocations of + * this method do not fail in such circumstances. */ @Override void close(); -- 2.36.6