Document and change the ListenerRegistration contract

Add text clarifying the role of this class. Also change the API contract
such that the close() method does not throw checked exceptions. Also
change the API contract such that the thread-safety is ensured via an
AtomicBoolean rather than a synchronized block.

Change-Id: Id29337ded87b812af98852decd677e3243f2179d
Signed-off-by: Robert Varga <rovarga@cisco.com>

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java
index 7bc17a07cdb082efa4f2930ad43ccabd31e875f4..879f9ba967c9594b7158666ffc16e407c9171d25 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractListenerRegistration.java
@@ -12,8 +12,8 @@ import java.util.EventListener;
 public abstract class AbstractListenerRegistration<T extends EventListener> extends AbstractObjectRegistration<T>
         implements ListenerRegistration<T> {
     
-    public AbstractListenerRegistration(T listener) {
+    protected AbstractListenerRegistration(final T listener) {
         super(listener);
     }
-
 }
+

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java
index 03ae939a7b430c11d484af230aba72abcea205ca..fa7318973b0e125871252e8d5df05c8a6d536e1d 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java
@@ -1,30 +1,28 @@
-/*\r
- * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.\r
- *\r
- * This program and the accompanying materials are made available under the\r
- * terms of the Eclipse Public License v1.0 which accompanies this distribution,\r
- * and is available at http://www.eclipse.org/legal/epl-v10.html\r
- */\r
-package org.opendaylight.yangtools.concepts;\r
-\r
-/**\r
- * Utility registration handle. It is a convenience for register-style method\r
- * which can return an AutoCloseable realized by a subclass of this class.\r
- * Invoking the close() method triggers unregistration of the state the method\r
- * installed.\r
- */\r
-public abstract class AbstractObjectRegistration<T> extends AbstractRegistration implements Registration<T> {\r
-\r
-    \r
-    private final T instance;\r
-\r
-    public AbstractObjectRegistration(T instance) {\r
-        this.instance = instance;\r
-    }\r
-\r
-    @Override\r
-    public final T getInstance() {\r
-        return instance;\r
-    }\r
-\r
-}\r
+/*
+ * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.concepts;
+
+/**
+ * Utility registration handle. It is a convenience for register-style method
+ * which can return an AutoCloseable realized by a subclass of this class.
+ * Invoking the close() method triggers unregistration of the state the method
+ * installed.
+ */
+public abstract class AbstractObjectRegistration<T> extends AbstractRegistration implements Registration<T> {
+    private final T instance;
+
+    protected AbstractObjectRegistration(final T instance) {
+        this.instance = instance;
+    }
+
+    @Override
+    public final T getInstance() {
+        return instance;
+    }
+}
+

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractRegistration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractRegistration.java
index 9f68d0fd7d6792a3c1dc6eef3080f91cf1dc633a..50f19fc9e3ef596c56754909889b3d308a66e673 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractRegistration.java
@@ -7,6 +7,8 @@
  */
 package org.opendaylight.yangtools.concepts;
 
+import java.util.concurrent.atomic.AtomicBoolean;
+
 /**
  * Utility registration handle. It is a convenience for register-style method
  * which can return an AutoCloseable realized by a subclass of this class.
@@ -14,8 +16,7 @@ package org.opendaylight.yangtools.concepts;
  * installed.
  */
 public abstract class AbstractRegistration implements AutoCloseable {
-
-    private boolean closed = false;
+    private AtomicBoolean closed = new AtomicBoolean();
     
     /**
      * Remove the state referenced by this registration. This method is
@@ -25,9 +26,8 @@ public abstract class AbstractRegistration implements AutoCloseable {
     protected abstract void removeRegistration();
 
     @Override
-    public synchronized void close() throws Exception {
-        if (!closed) {
-            closed = true;
+    public final void close() {
+        if (closed.compareAndSet(false, true)) {
             removeRegistration();
         }
     }

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java
index f9fff4bb79adc12539f346928221bb83974b3f6b..646b462199aa37c83862e7e912eb8ac5f9f91e25 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java
@@ -1,14 +1,28 @@
-/*\r
- * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.\r
- *\r
- * This program and the accompanying materials are made available under the\r
- * terms of the Eclipse Public License v1.0 which accompanies this distribution,\r
- * and is available at http://www.eclipse.org/legal/epl-v10.html\r
- */\r
-package org.opendaylight.yangtools.concepts;\r
-\r
-import java.util.EventListener;\r
-\r
-public interface ListenerRegistration<T extends EventListener> extends Registration<T> {\r
-\r
-}\r
+/*
+ * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.concepts;
+
+import java.util.EventListener;
+
+/**
+ * Class representing a {@link Registration} of an {@link EventListener}. This
+ * is interface provides the additional guarantee that the process of
+ * unregistration cannot fail for predictable reasons.
+ */
+public interface ListenerRegistration<T extends EventListener> extends Registration<T> {
+    /**
+     * Unregister the listener. No events should be delivered to the listener
+     * once this method returns successfully. While the interface contract
+     * allows an implementation to ignore the occurence 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();
+}