Add YangNetconfError

This is a yang-data-api specialization of a well-known RFC4741/6020
construct, which we have tried to model in yang.common.RpcError and
then via yang.common.YangError.

Unlike YangError, which is directly glued to exceptions,
YangNetconfError has a builder-based immutable implementation, which can
be attached to other objects via YangNetconfErrorAware.

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

diff --git a/data/yang-data-api/pom.xml b/data/yang-data-api/pom.xml
index d3bf30bd407190c4a934468271241880065785fb..9fe94b385ec57d72af232b1883a0e4ff7bbae74c 100644 (file)
--- a/data/yang-data-api/pom.xml
+++ b/data/yang-data-api/pom.xml
@@ -42,6 +42,10 @@
           <groupId>org.opendaylight.yangtools</groupId>
           <artifactId>yang-model-api</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.immutables</groupId>
+            <artifactId>value</artifactId>
+            <classifier>annotations</classifier>
+        </dependency>
     </dependencies>
-
 </project>

diff --git a/data/yang-data-api/src/main/java/module-info.java b/data/yang-data-api/src/main/java/module-info.java
index d53ca712153beae81829a7d1134d6292fb7e7d44..f6b69d22596a88c21666134ecb84a123102dca57 100644 (file)
--- a/data/yang-data-api/src/main/java/module-info.java
+++ b/data/yang-data-api/src/main/java/module-info.java
@@ -24,4 +24,5 @@ module org.opendaylight.yangtools.yang.data.api {
     // Annotations
     requires static transitive org.eclipse.jdt.annotation;
     requires static com.github.spotbugs.annotations;
+    requires static org.immutables.value.annotations;
 }

diff --git a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfError.java b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfError.java
new file mode 100644 (file)
index 0000000..fb29012
--- /dev/null
+++ b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfError.java
@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2021 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.data.api;
+
+import com.google.common.annotations.Beta;
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import java.util.List;
+import javax.annotation.processing.Generated;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.immutables.value.Value;
+import org.opendaylight.yangtools.yang.common.ErrorSeverity;
+import org.opendaylight.yangtools.yang.common.ErrorTag;
+import org.opendaylight.yangtools.yang.common.ErrorType;
+
+/**
+ * Baseline interface for metadata associated with a NETCONF notion of an 'error'. Except what NETCONF regards as
+ * an 'error', really means 'notable event' in that it can either be a warning or an error. No warnings were defined
+ * at the time this distinction was made.
+ */
+@Beta
+@NonNullByDefault
+@Value.Immutable(copy = false)
+@Value.Style(stagedBuilder = true, allowedClasspathAnnotations = {
+    SuppressWarnings.class, Generated.class, SuppressFBWarnings.class,
+})
+public interface YangNetconfError {
+    /**
+     * Return this error's severity.
+     *
+     * @return Error severity.
+     */
+    ErrorSeverity severity();
+
+    /**
+     * Return this error's type.
+     *
+     * @return Error type.
+     */
+    ErrorType type();
+
+    /**
+     * Return this error's tag.
+     *
+     * @return Error tag.
+     */
+    ErrorTag tag();
+
+    /**
+     * Return this errors's {@code error-message}, if available. This value is expected to be defined in a YANG model
+     * through a {@code error-message} statement.
+     *
+     * @return Event message, or null.
+     */
+    @Nullable String message();
+
+    /**
+     * Return this error's {@code error-app-tag}, if available. This value is expected to be defined in a YANG model
+     * through a {@code error-app-tag} statement.
+     *
+     * @return Application tag, or null.
+     */
+    @Nullable String appTag();
+
+    /**
+     * Return the path which triggered this error, if available.
+     *
+     * @return Triggering path, or null.
+     */
+    @Nullable YangInstanceIdentifier path();
+
+    /**
+     * Return this error's additional info.
+     *
+     * @return Additional info.
+     */
+    List<YangErrorInfo> info();
+}

diff --git a/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfErrorAware.java b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfErrorAware.java
new file mode 100644 (file)
index 0000000..c8139d3
--- /dev/null
+++ b/data/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/YangNetconfErrorAware.java
@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2021 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.data.api;
+
+import com.google.common.annotations.Beta;
+import java.util.List;
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * Interface exposed from objects which have some association with {@link YangNetconfError}.
+ */
+@Beta
+@NonNullByDefault
+public interface YangNetconfErrorAware {
+    /**
+     * Return the {@link YangNetconfError}s associated with this objects.
+     *
+     * @return Associated YangNetconfErrors
+     */
+    List<YangNetconfError> getNetconfErrors();
+}