Add SchemaSourceInfo

We typically need to organize SchemaSourceRepresentations in some way
and make consistency inferences against their linkage.

The RFCSs do not specifically call this out, but the information is kept
at the top of the YANG file, so that even a simple text parser can find
it quickly.

Our YANG text processing pipeline has this information available
whenever we need to build a YangModelDependencyInfo -- which is an
optional operation, but the implementation only needs IRSchemaSource.

This patch introduces SchemaSourceInfo, which is a RFC-based opinionated
version YangModelDependencyInfo.

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

diff --git a/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/ModuleSourceInfo.java b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/ModuleSourceInfo.java
new file mode 100644 (file)
index 0000000..23e9d53
--- /dev/null
+++ b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/ModuleSourceInfo.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2024 PANTHEON.tech, s.r.o. 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.yang.model.spi.source;
+
+import static java.util.Objects.requireNonNull;
+
+import com.google.common.collect.ImmutableSet;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.opendaylight.yangtools.yang.common.Revision;
+import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
+import org.opendaylight.yangtools.yang.common.XMLNamespace;
+import org.opendaylight.yangtools.yang.common.YangVersion;
+
+/**
+ * A {@link SourceInfo} about a {@code module}.
+ */
+@NonNullByDefault
+public record ModuleSourceInfo(
+        Unqualified name,
+        YangVersion yangVersion,
+        XMLNamespace namespace,
+        String prefix,
+        ImmutableSet<Revision> revisions,
+        ImmutableSet<Import> imports,
+        ImmutableSet<Include> includes) implements SourceInfo {
+    public ModuleSourceInfo {
+        requireNonNull(name);
+        requireNonNull(yangVersion);
+        requireNonNull(namespace);
+        requireNonNull(prefix);
+        requireNonNull(revisions);
+        requireNonNull(imports);
+        requireNonNull(includes);
+    }
+}

diff --git a/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SourceInfo.java b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SourceInfo.java
new file mode 100644 (file)
index 0000000..e159819
--- /dev/null
+++ b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SourceInfo.java
@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2024 PANTHEON.tech, s.r.o. 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.yang.model.spi.source;
+
+import static java.util.Objects.requireNonNull;
+
+import com.google.common.collect.ImmutableSet;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.opendaylight.yangtools.yang.common.Revision;
+import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
+import org.opendaylight.yangtools.yang.common.YangVersion;
+import org.opendaylight.yangtools.yang.model.api.source.SourceRepresentation;
+
+/**
+ * Linkage information about a particular {@link SourceRepresentation}. It has two specializations
+ * <ol>
+ *   <li>{@link ModuleSourceInfo} pertaining to {@link SourceRepresentation} which have {@code module} as its root
+ *       statement</li>
+ *   <li>{@link SubmoduleSourceInfo} pertaining to {@link SourceRepresentation} which have {@code submodule} as its root
+ *       statement</li>
+ * </ol>
+ *
+ * <p>
+ * This interface captures the basic metadata needed for interpretation and linkage of the source, as represented by the
+ * following ABNF constructs placed at the start of a YANG file:
+ * <ul>
+ *   <li>{@code module-header-stmts} or {@code submodule-header-stmts}</li>
+ *   <li>{@code linkage-stmts}</li>
+ *   <li>{@code revision-stmts}<li>
+ * </ul>
+ */
+@NonNullByDefault
+public sealed interface SourceInfo permits ModuleSourceInfo, SubmoduleSourceInfo {
+    record Import(Unqualified name, String prefix, @Nullable Revision revision) {
+        public Import {
+            requireNonNull(name);
+            requireNonNull(prefix);
+        }
+    }
+
+    record Include(Unqualified name, @Nullable Revision revision) {
+        public Include {
+            requireNonNull(name);
+        }
+    }
+
+    /**
+     * The name of this source, as expressed by the argument of {@code module} or {@code submodule} statement.
+     *
+     * @return name of this source.
+     */
+    Unqualified name();
+
+    /**
+     * {@link YangVersion} of the source. If no {@code yang-version} is present, this method will return
+     * {@link YangVersion#VERSION_1}.
+     *
+     * @return {@link YangVersion} of the source
+     */
+    YangVersion yangVersion();
+
+    ImmutableSet<Revision> revisions();
+
+    ImmutableSet<Import> imports();
+
+    ImmutableSet<Include> includes();
+}

diff --git a/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SubmoduleSourceInfo.java b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SubmoduleSourceInfo.java
new file mode 100644 (file)
index 0000000..2ad7a92
--- /dev/null
+++ b/model/yang-model-spi/src/main/java/org/opendaylight/yangtools/yang/model/spi/source/SubmoduleSourceInfo.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2024 PANTHEON.tech, s.r.o. 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.yang.model.spi.source;
+
+import static java.util.Objects.requireNonNull;
+
+import com.google.common.collect.ImmutableSet;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.opendaylight.yangtools.yang.common.Revision;
+import org.opendaylight.yangtools.yang.common.UnresolvedQName.Unqualified;
+import org.opendaylight.yangtools.yang.common.YangVersion;
+
+/**
+ * A {@link SourceInfo} about a {@code submodule}.
+ */
+@NonNullByDefault
+public record SubmoduleSourceInfo(
+        Unqualified name,
+        YangVersion yangVersion,
+        Unqualified belongsTo,
+        ImmutableSet<Revision> revisions,
+        ImmutableSet<Import> imports,
+        ImmutableSet<Include> includes) implements SourceInfo {
+    public SubmoduleSourceInfo {
+        requireNonNull(name);
+        requireNonNull(yangVersion);
+        requireNonNull(belongsTo);
+        requireNonNull(revisions);
+        requireNonNull(imports);
+        requireNonNull(includes);
+    }
+}