BUG-432: Start fixing the Registration contract

Registration should be a generic construct, not tied to a particular
object. Unfortunately that requires API-level breakage which needs to be
orchestrated with the users.

As a first step introduce ObjectRegistration concept which is equivalent
with the current Registration concept and gently nudge the users towards
it.

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

diff --git a/code-generator/binding-generator-impl/src/main/java/org/opendaylight/yangtools/sal/binding/generator/impl/ModuleInfoBackedContext.java b/code-generator/binding-generator-impl/src/main/java/org/opendaylight/yangtools/sal/binding/generator/impl/ModuleInfoBackedContext.java
index fb70c8f06cb95d85d4a0097d769bde1fcbb7dc05..687b3a33361632b8dbaf4301b286f364600392ed 100644 (file)
--- a/code-generator/binding-generator-impl/src/main/java/org/opendaylight/yangtools/sal/binding/generator/impl/ModuleInfoBackedContext.java
+++ b/code-generator/binding-generator-impl/src/main/java/org/opendaylight/yangtools/sal/binding/generator/impl/ModuleInfoBackedContext.java
@@ -15,7 +15,7 @@ import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 
 import org.opendaylight.yangtools.concepts.AbstractObjectRegistration;
-import org.opendaylight.yangtools.concepts.Registration;
+import org.opendaylight.yangtools.concepts.ObjectRegistration;
 import org.opendaylight.yangtools.sal.binding.generator.util.ClassLoaderUtils;
 import org.opendaylight.yangtools.yang.binding.YangModuleInfo;
 import org.opendaylight.yangtools.yang.binding.util.BindingReflections;
@@ -144,7 +144,7 @@ public class ModuleInfoBackedContext extends GeneratedClassLoadingStrategy //
         }
     }
 
-    public Registration<YangModuleInfo> registerModuleInfo(YangModuleInfo yangModuleInfo) {
+    public ObjectRegistration<YangModuleInfo> registerModuleInfo(YangModuleInfo yangModuleInfo) {
         YangModuleInfoRegistration registration = new YangModuleInfoRegistration(yangModuleInfo, this);
 
         resolveModuleInfo(yangModuleInfo);

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 fa7318973b0e125871252e8d5df05c8a6d536e1d..7c322ac3e2c2b6682fede9fdbfec038e8758df52 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/AbstractObjectRegistration.java
@@ -13,7 +13,7 @@ package org.opendaylight.yangtools.concepts;
  * Invoking the close() method triggers unregistration of the state the method
  * installed.
  */
-public abstract class AbstractObjectRegistration<T> extends AbstractRegistration implements Registration<T> {
+public abstract class AbstractObjectRegistration<T> extends AbstractRegistration implements ObjectRegistration<T> {
     private final T instance;
 
     protected AbstractObjectRegistration(final T instance) {

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 646b462199aa37c83862e7e912eb8ac5f9f91e25..8fe2d8ff8b1bfce523077599f315e5038196f54e 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/ListenerRegistration.java
@@ -14,7 +14,7 @@ import java.util.EventListener;
  * 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> {
+public interface ListenerRegistration<T extends EventListener> extends ObjectRegistration<T> {
     /**
      * Unregister the listener. No events should be delivered to the listener
      * once this method returns successfully. While the interface contract

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/ObjectRegistration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/ObjectRegistration.java
new file mode 100644 (file)
index 0000000..7725829
--- /dev/null
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/ObjectRegistration.java
@@ -0,0 +1,35 @@
+/*
+ * 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;
+
+/**
+ * Class representing a registration of an object. Such a registration is
+ * a proper resource and should be cleaned up when no longer required, so
+ * references to the object can be removed. This mechanism lies above the
+ * usual Java reference mechanism, as the entity where the object is
+ * registered may reside outside of the Java Virtual Machine.
+ */
+public interface ObjectRegistration<T> extends Registration<T> {
+    /**
+     * Return the object instance.
+     *
+     * @return Registered object.
+     */
+    @Override
+    T getInstance();
+
+    /**
+     * 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.
+     */
+    @Override
+    void close() throws Exception;
+}

diff --git a/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java b/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java
index 051200c18d09140e0d1b7c2a95b7c1e7225348e0..8b2631f7531bd4ffae50d1b6c5734d7e6f0b1223 100644 (file)
--- a/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java
+++ b/concepts/src/main/java/org/opendaylight/yangtools/concepts/Registration.java
@@ -19,7 +19,15 @@ public interface Registration<T> extends AutoCloseable {
      * Return the object instance.
      *
      * @return Registered object.
+     *
+     * @deprecated This class is currently deprecated pending its rework for
+     *             general-purpose registration. This rework will remove the
+     *             getInstance() method, such that the registration is no
+     *             longer tied to a particular object. Please use
+     *             {@link ObjectRegistration} to ensure your code does not
+     *             break when that happens.
      */
+    @Deprecated
     T getInstance();
 
     /**

diff --git a/yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/impl/util/URLSchemaContextResolver.java b/yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/impl/util/URLSchemaContextResolver.java
index 3d704931af748d4dd51d3acfad233f53c29d135b..fe32493b120efbe97cd3df5a3b7f426a8c6c4e51 100644 (file)
--- a/yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/impl/util/URLSchemaContextResolver.java
+++ b/yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/impl/util/URLSchemaContextResolver.java
@@ -7,6 +7,8 @@
  */
 package org.opendaylight.yangtools.yang.parser.impl.util;
 
+import static com.google.common.base.Preconditions.checkArgument;
+
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URL;
@@ -18,7 +20,7 @@ import java.util.concurrent.ConcurrentMap;
 
 import org.opendaylight.yangtools.concepts.AbstractObjectRegistration;
 import org.opendaylight.yangtools.concepts.Identifiable;
-import org.opendaylight.yangtools.concepts.Registration;
+import org.opendaylight.yangtools.concepts.ObjectRegistration;
 import org.opendaylight.yangtools.yang.model.api.Module;
 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
 import org.opendaylight.yangtools.yang.model.util.repo.AdvancedSchemaSourceProvider;
@@ -31,8 +33,6 @@ import com.google.common.base.Optional;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableMap.Builder;
 
-import static com.google.common.base.Preconditions.checkArgument;
-
 public class URLSchemaContextResolver implements AdvancedSchemaSourceProvider<InputStream> {
 
     private static final Logger LOG = LoggerFactory.getLogger(URLSchemaContextResolver.class);
@@ -41,7 +41,7 @@ public class URLSchemaContextResolver implements AdvancedSchemaSourceProvider<In
     private YangSourceContext currentSourceContext;
     private Optional<SchemaContext> currentSchemaContext = Optional.absent();
 
-    public Registration<URL> registerSource(URL source) {
+    public ObjectRegistration<URL> registerSource(URL source) {
         checkArgument(source != null, "Supplied source must not be null");
         InputStream yangStream = getInputStream(source);
         YangModelDependencyInfo modelInfo = YangModelDependencyInfo.fromInputStream(yangStream);
@@ -93,6 +93,7 @@ public class URLSchemaContextResolver implements AdvancedSchemaSourceProvider<In
             this.dependencyInfo = modelInfo;
         }
 
+        @Override
         public SourceIdentifier getIdentifier() {
             return identifier;
         }