From 5665bba160d3c8e731a2d2b010a7d725c2ce55af Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Sat, 12 Mar 2022 13:41:25 +0100 Subject: [PATCH] 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 --- .../dom/codec/impl/BindingCodecContext.java | 2 +- .../codec/impl/InstanceIdentifierCodec.java | 5 ++- .../yang/binding/InstanceIdentifier.java | 33 +++++++++---------- .../yang/binding/InstanceIdentifierTest.java | 2 +- 4 files changed, 19 insertions(+), 23 deletions(-) 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 ff51f42aff..a8537dab27 100644 --- 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 2138c777bd..3a90678449 100644 --- 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 ret = (InstanceIdentifier) 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 0c89142533..bea92bf979 100644 --- 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 } /** - * 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. * *

- * Example: - * 

-     *  List<PathArgument> path = Arrays.asList(new Item(Nodes.class))
-     *  new InstanceIdentifier(path);
-     *
+ * 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 pathArguments) { - if (pathArguments instanceof ImmutableCollection) { - @SuppressWarnings("unchecked") - final var immutableArguments = (ImmutableCollection) pathArguments; - return internalCreate(immutableArguments); - } - - return internalCreate(ImmutableList.copyOf(pathArguments)); + @SuppressWarnings("unchecked") + public static @NonNull InstanceIdentifier unsafeOf( + final List pathArguments) { + return (InstanceIdentifier) 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 1270d340ea..5696abd8d3 100644 --- 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)); -- 2.36.6