Add yang-binding interfaces for annotations

Binding users are interested in having a way to access RFC7952
metadata. While the actual codegen/runtime implementation requires
some work, we know what Binding Specification extension we will
need to support the generated classes.

This patch introduces Annotation and AnnotationAware, so a future
codegen version can bind to it.

JIRA: MDSAL-357
Change-Id: I2fed30ea34b21c36b626388bb37890cc73875176
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit 4bd8c8ccb296b0982fe2b5b287976a55610511f8)

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/Annotation.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/Annotation.java
new file mode 100644 (file)
index 0000000..0e625ec
--- /dev/null
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/Annotation.java
@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2019 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.binding;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * Base marker interface implemented by all YANG-defined annotations through the facilities provided by
+ * <a href="https://tools.ietf.org/html/rfc7952">RFC7952</a>. This interface is not meant to be directly implemented,
+ * but rather serves as a hook for generated code.
+ *
+ * <p>
+ * An Annotation is a cross between a {@link TypeObject}, a {@link DataObject} and an {@link Augmentation}:
+ * <ul>
+ * <li>Similar to a {@code TypeObject} it can only hold a single scalar value, which has to be present.</li>
+ * <li>Similar to most {@code TypeObject}s, the value is available through {@link #getValue()} method</li>
+ * <li>Similar to a {@code DataObject}, the return type of {@link #getValue()} can point to a generated
+ *     {@code TypeObject}, not only a base YANG type</li>
+ * <li>Similar to an {@code Augmentation} it can be attached to other objects via {@link AnnotationAware} interface.
+ *     Unlike augmentations, though, annotations do not have a strict tie to the object they attach to.</li>
+ * </ul>
+ *
+ * @param <T> Value type
+ */
+@Beta
+public interface Annotation<T> extends BindingObject, ValueAware<T> {
+
+}

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/AnnotationAware.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/AnnotationAware.java
new file mode 100644 (file)
index 0000000..52b9d93
--- /dev/null
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/AnnotationAware.java
@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2019 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.binding;
+
+import com.google.common.annotations.Beta;
+import java.util.Optional;
+
+/**
+ * Interface mixin for {@link BindingObject}s which can hold additional metadata, as specified by
+ * <a href="https://tools.ietf.org/html/rfc7952">RFC7952</a>. It exposes this metadata as individual annotations via
+ * {@link #annotation(Class)} method. This similar to how {@link Augmentable} works, with the notable difference that
+ * there is no strong tie between an annotation and its bearer object.
+ */
+@Beta
+public interface AnnotationAware {
+    /**
+     * Returns an instance of a requested annotation type.
+     *
+     * @param annotationType Type of annotation to be returned.
+     * @param <A$$> Type capture for augmentation type
+     * @return instance of annotation, or empty if the annotation is not present.
+     */
+    // A$$ is an identifier which cannot be generated from models.
+    @SuppressWarnings("checkstyle:methodTypeParameterName")
+    <A$$ extends Annotation<?>> Optional<A$$> annotation(Class<A$$> annotationType);
+}

diff --git a/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/ValueAware.java b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/ValueAware.java
new file mode 100644 (file)
index 0000000..02d5884
--- /dev/null
+++ b/binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/ValueAware.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) 2019 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.binding;
+
+import com.google.common.annotations.Beta;
+import org.eclipse.jdt.annotation.NonNull;
+
+/**
+ * Simple interface for reuse with BindingObjects which expose a single value in some representation. This interface
+ * is not meant to be directly implemented.
+ *
+ * @param <T> value type
+ */
+@Beta
+public interface ValueAware<T> {
+    /**
+     * Return the value associated with this object.
+     *
+     * @return This object's value.
+     */
+    @NonNull T getValue();
+}