Refactor InstanceIdentifier.create(Iterable)

This method is for things like binding/dom codec and similar users who
know what they are doing. Rename the method to 'unsafeOf()', so that the
compilation failures from the change in InstanceIdentifier.create(Class)'s
signature do not produce confusing guidance by pointing to this arcane
method.

Also document this method's purpose, with significant warning and update
it to take a List.

JIRA: MDSAL-730
Change-Id: I9def3750f16d87c11d12809e0f067daf0bf352b9
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/BindingCodecContext.java b/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/BindingCodecContext.java
index ff51f42affe92ae5766aebbcce5f6a8f92047d33..a8537dab27dbc4a5e8abbf4f773299ad059dceaa 100644 (file)
--- a/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/BindingCodecContext.java
+++ b/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/BindingCodecContext.java
@@ -550,7 +550,7 @@ public final class BindingCodecContext extends AbstractBindingNormalizedNodeSeri
         }
 
         final DataObject lazyObj = codec.deserialize(data);
-        final InstanceIdentifier<?> bindingPath = InstanceIdentifier.create(builder);
+        final InstanceIdentifier<?> bindingPath = InstanceIdentifier.unsafeOf(builder);
         return Map.entry(bindingPath, lazyObj);
     }
 

diff --git a/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/InstanceIdentifierCodec.java b/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/InstanceIdentifierCodec.java
index 2138c777bddab94602ac5e9e8a5698d0279f700a..3a906784495cb6381b603707c8457e13f1b0a6d3 100644 (file)
--- a/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/InstanceIdentifierCodec.java
+++ b/binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/impl/InstanceIdentifierCodec.java
@@ -42,9 +42,8 @@ final class InstanceIdentifierCodec implements BindingInstanceIdentifierCodec,
             // which is not binding representable.
             return null;
         }
-        @SuppressWarnings("unchecked")
-        final InstanceIdentifier<T> ret = (InstanceIdentifier<T>) InstanceIdentifier.create(builder);
-        return ret;
+
+        return InstanceIdentifier.unsafeOf(builder);
     }
 
     @Override

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
index 0c89142533d5c337fc8a503337f7b5b949fc8177..bea92bf979b99108df8ad16ff61dfaa5ea859295 100644 (file)
--- a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifier.java
@@ -15,13 +15,13 @@ import static java.util.Objects.requireNonNull;
 import com.google.common.base.MoreObjects;
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.base.VerifyException;
-import com.google.common.collect.ImmutableCollection;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Iterables;
 import java.io.ObjectStreamException;
 import java.io.Serializable;
 import java.util.Collections;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
 import org.eclipse.jdt.annotation.NonNull;
@@ -556,29 +556,26 @@ public class InstanceIdentifier<T extends DataObject>
     }
 
     /**
-     * Create an instance identifier for a very specific object type.
+     * Create an instance identifier for a sequence of {@link PathArgument} steps. The steps are required to be formed
+     * of classes extending either {@link ChildOf} or {@link Augmentation} contracts. This method does not check whether
+     * or not the sequence is structurally sound, for example that an {@link Augmentation} follows an
+     * {@link Augmentable} step. Furthermore the compile-time indicated generic type of the returned object does not
+     * necessarily match the contained state.
      *
      * <p>
-     * Example:
-     * <pre>
-     *  List&lt;PathArgument&gt; path = Arrays.asList(new Item(Nodes.class))
-     *  new InstanceIdentifier(path);
-     * </pre>
+     * Failure to observe precautions to validate the list's contents may yield an object which mey be rejected at
+     * run-time or lead to undefined behaviour.
      *
      * @param pathArguments The path to a specific node in the data tree
      * @return InstanceIdentifier instance
-     * @throws IllegalArgumentException if pathArguments is empty or
-     *         contains a null element.
+     * @throws NullPointerException if {@code pathArguments} is, or contains an item which is, {@code null}
+     * @throws IllegalArgumentException if {@code pathArguments} is empty or contains an item which does not represent
+     *                                  a valid addressing step.
      */
-    // FIXME: rename to 'unsafeOf()'
-    public static @NonNull InstanceIdentifier<?> create(final Iterable<? extends PathArgument> pathArguments) {
-        if (pathArguments instanceof ImmutableCollection) {
-            @SuppressWarnings("unchecked")
-            final var immutableArguments = (ImmutableCollection<PathArgument>) pathArguments;
-            return internalCreate(immutableArguments);
-        }
-
-        return internalCreate(ImmutableList.copyOf(pathArguments));
+    @SuppressWarnings("unchecked")
+    public static <T extends DataObject> @NonNull InstanceIdentifier<T> unsafeOf(
+            final List<? extends PathArgument> pathArguments) {
+        return (InstanceIdentifier<T>) internalCreate(ImmutableList.copyOf(pathArguments));
     }
 
     /**

diff --git a/binding/yang-binding/src/test/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifierTest.java b/binding/yang-binding/src/test/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifierTest.java
index 1270d340ea36e65e910eb573b76d5a21e8f41f85..5696abd8d34b0d1e887b5c145f8aa373f0f482d9 100644 (file)
--- a/binding/yang-binding/src/test/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifierTest.java
+++ b/binding/yang-binding/src/test/java/org/opendaylight/yangtools/yang/binding/InstanceIdentifierTest.java
@@ -149,7 +149,7 @@ public class InstanceIdentifierTest {
         Whitebox.setInternalState(instanceIdentifier5, "hash", instanceIdentifier1.hashCode());
         Whitebox.setInternalState(instanceIdentifier5, "wildcarded", false);
 
-        assertNotNull(InstanceIdentifier.create(ImmutableList.copyOf(instanceIdentifier1.getPathArguments())));
+        assertNotNull(InstanceIdentifier.unsafeOf(ImmutableList.copyOf(instanceIdentifier1.getPathArguments())));
         assertNotNull(InstanceIdentifier.create(Nodes.class).child(Node.class));
         assertNotNull(InstanceIdentifier.create(Nodes.class).child(Node.class, new NodeKey(5)));
         assertNotNull(instanceIdentifier5.augmentation(NodeAugmentation.class));