Introduce HierarchicalIdentifier to replace Path

Path is always combined with Identifier, and it really is an extension
of Identifier contract. Add a new interface to capture that contract
and deprecate Path, so we get out of java.nio.file.Path's way.

JIRA: YANGTOOLS-1344
Change-Id: Ida2f28b1f2d349b67115611eac843e7da8628f42
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/HierarchicalIdentifier.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/HierarchicalIdentifier.java
new file mode 100644 (file)
index 0000000..8f404d2
--- /dev/null
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/HierarchicalIdentifier.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
+ * Copyright (c) 2021 PANTHEON.tech, s.r.o.
+ *
+ * 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;
+
+/**
+ * An {@link Identifier} tied to some tree-like structure, similar to how {@link java.nio.file.Path} is tied to a
+ * conceptual file system. In addition to equivalence class implied by Identifier, the hierarchical nature of these
+ * identifiers also introduces a notion of containment: a HierarchicalIdentifier is said to contain another
+ * HierarchicalIdentifier if the former points to an ancestor node of the node pointed to by the latter in the same
+ * instance of the tree-like structure they are defined on. This property is expressed through
+ * {@link #contains(HierarchicalIdentifier)}.
+ */
+public interface HierarchicalIdentifier<T extends HierarchicalIdentifier<T>> extends Identifier, Path<T> {
+    /**
+     * Check if this identifier contains some other identifier. If we take HierarchicalIdentifier to be similar to a
+     * {@link java.nio.file.Path}, this is method is the equivalent of {@code other.startsWith(this)}.
+     *
+     * @param other Other identifier, may not be null
+     * @return True if this identifier contains the other identifier
+     * @throws NullPointerException if {@code other} is null
+     */
+    @Override
+    boolean contains(T other);
+}

diff --git a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Path.java b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Path.java
index c0e6621769b9e9faaf2392450027cc66d10a5d15..bce6a92708da627f846d7477d494405db32d6898 100644 (file)
--- a/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Path.java
+++ b/common/concepts/src/main/java/org/opendaylight/yangtools/concepts/Path.java
@@ -17,7 +17,10 @@ import org.eclipse.jdt.annotation.NonNull;
  * identified by the former contains all elements of the data set represented by later.
  *
  * @param <P> Path equivalence class
+ * @deprecated This interface does not completely capture the modeling intent. Use {@link HierarchicalIdentifier}
+ *             instead.
  */
+@Deprecated(since = "7.0.9", forRemoval = true)
 public interface Path<P extends Path<P>> {
     /**
      * Check if this path contains some other.

diff --git a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangInstanceIdentifier.java b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangInstanceIdentifier.java
index a7539e9167f08cb0917ba2b532e12f22e925194e..31ea97a0279cd82d1fe737eb7f5915f1be12390c 100644 (file)
--- a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangInstanceIdentifier.java
+++ b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangInstanceIdentifier.java
@@ -41,8 +41,8 @@ import java.util.function.Function;
 import org.eclipse.jdt.annotation.NonNull;
 import org.eclipse.jdt.annotation.Nullable;
 import org.opendaylight.yangtools.concepts.Builder;
+import org.opendaylight.yangtools.concepts.HierarchicalIdentifier;
 import org.opendaylight.yangtools.concepts.Immutable;
-import org.opendaylight.yangtools.concepts.Path;
 import org.opendaylight.yangtools.util.HashCodeBuilder;
 import org.opendaylight.yangtools.util.ImmutableOffsetMap;
 import org.opendaylight.yangtools.util.SingletonSet;
@@ -79,7 +79,7 @@ import org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode;
 // FIXME: 7.0.0: this concept needs to be moved to yang-common, as parser components need the ability to refer
 //               to data nodes -- most notably XPath expressions and {@code default} statement arguments need to be able
 //               to represent these.
-public abstract class YangInstanceIdentifier implements Path<YangInstanceIdentifier>, Immutable, Serializable {
+public abstract class YangInstanceIdentifier implements HierarchicalIdentifier<YangInstanceIdentifier> {
     private static final AtomicReferenceFieldUpdater<YangInstanceIdentifier, String> TOSTRINGCACHE_UPDATER =
             AtomicReferenceFieldUpdater.newUpdater(YangInstanceIdentifier.class, String.class, "toStringCache");
     private static final long serialVersionUID = 4L;