From 109232877dcdf0a6771312b95234b6c9965e3ec3 Mon Sep 17 00:00:00 2001 From: Robert Varga Date: Mon, 21 May 2018 22:09:42 +0200 Subject: [PATCH] Add a few 3.0.0 FIXMEs Clarify thrown exceptions and nullness, as well as the need to use Optional. Change-Id: I8a960b2593b87552f24d0de3d28cb75a1d4fb040 Signed-off-by: Robert Varga --- .../schema/tree/DataTreeCandidateNode.java | 11 ++++++----- .../data/api/schema/tree/DataTreeTip.java | 19 +++++++++++-------- .../data/api/schema/tree/StoreTreeNode.java | 7 ++++--- .../api/schema/tree/spi/MutableTreeNode.java | 10 +++++++--- .../data/api/schema/tree/spi/TreeNode.java | 1 + 5 files changed, 29 insertions(+), 19 deletions(-) diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeCandidateNode.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeCandidateNode.java index 1f5ec6a47a..3f525aa0f2 100644 --- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeCandidateNode.java +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeCandidateNode.java @@ -15,13 +15,12 @@ import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgum import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; /** - * A single node within a {@link DataTreeCandidate}. The nodes are organized - * in tree hierarchy, reflecting the modification from which this candidate - * was created. The node itself exposes the before- and after-image of the - * tree restricted to the modified nodes. + * A single node within a {@link DataTreeCandidate}. The nodes are organized in tree hierarchy, reflecting + * the modification from which this candidate was created. The node itself exposes the before- and after-image + * of the tree restricted to the modified nodes. */ +// FIXME: 3.0.0: Use @NonNullByDefault public interface DataTreeCandidateNode { - /** * Get the node identifier. * @@ -43,6 +42,8 @@ public interface DataTreeCandidateNode { * @param childIdentifier Identifier of child node * @return Modified child or null if child was not modified. */ + // FIXME: 3.0.0: document NullPointerException being thrown + // FIXME: 3.0.0: return an Optional @Nullable DataTreeCandidateNode getModifiedChild(PathArgument childIdentifier); /** diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeTip.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeTip.java index 8f23488474..77c3142c5f 100644 --- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeTip.java +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeTip.java @@ -10,27 +10,30 @@ package org.opendaylight.yangtools.yang.data.api.schema.tree; import com.google.common.annotations.Beta; /** - * Tip of a data tree instance. It acts as a point to which modifications can - * be applied. + * Tip of a data tree instance. It acts as a point to which modifications can be applied. */ +// FIXME: 3.0.0: Use @NonNullByDefault @Beta public interface DataTreeTip { /** * Validate whether a particular modification can be applied to the data tree. - * @param modification - * Data tree modification. - * @throws DataValidationFailedException - * If modification data is not valid. + * + * @param modification Data tree modification. + * @throws DataValidationFailedException If modification data is not valid. */ + // FIXME: 3.0.0: document NullPointerException being thrown + // FIXME: 3.0.0: document IllegalArgumentException being thrown void validate(DataTreeModification modification) throws DataValidationFailedException; /** * Prepare a modification for commit. * - * @param modification - * Data tree modification. + * @param modification Data tree modification. * @return candidate data tree */ + // FIXME: 3.0.0: document NullPointerException being thrown + // FIXME: 3.0.0: document IllegalArgumentException being thrown + // FIXME: 3.0.0: throw DataValidationFailedException or similar DataTreeCandidateTip prepare(DataTreeModification modification); /** diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/StoreTreeNode.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/StoreTreeNode.java index 541dc60a8b..c8778f4377 100644 --- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/StoreTreeNode.java +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/StoreTreeNode.java @@ -11,18 +11,19 @@ import java.util.Optional; import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument; /** - * A tree node which has references to its child leaves. This are typically - * internal non-data leaves, such as containers, lists, etc. + * A tree node which has references to its child leaves. This are typically internal non-data leaves, such as + * containers, lists, etc. * * @param Final node type */ +// FIXME: 3.0.0: Use @NonNullByDefault public interface StoreTreeNode> { - /** * Returns a direct child of the node. * * @param child Identifier of child * @return Optional with node if the child is existing, {@link Optional#empty()} otherwise. */ + // FIXME: 3.0.0: document NullPointerException being thrown Optional getChild(PathArgument child); } diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/MutableTreeNode.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/MutableTreeNode.java index 933b7a1fdf..abdffe9068 100644 --- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/MutableTreeNode.java +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/MutableTreeNode.java @@ -12,16 +12,17 @@ import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode; import org.opendaylight.yangtools.yang.data.api.schema.tree.StoreTreeNode; /** - * A mutable tree node. This is a transient view materialized from a pre-existing - * node. Modifications are isolated. Once this object is {@link #seal()}-ed, - * any interactions with it will result in undefined behavior. + * A mutable tree node. This is a transient view materialized from a pre-existing node. Modifications are isolated. Once + * this object is {@link #seal()}ed, any interactions with it will result in undefined behavior. */ +// FIXME: 3.0.0: Use @NonNullByDefault public interface MutableTreeNode extends StoreTreeNode { /** * Set the data component of the node. * * @param data New data component, may not be null. */ + // FIXME: 3.0.0: document NullPointerException being thrown void setData(NormalizedNode data); /** @@ -30,6 +31,7 @@ public interface MutableTreeNode extends StoreTreeNode { * * @param subtreeVersion New subtree version. */ + // FIXME: 3.0.0: document NullPointerException being thrown void setSubtreeVersion(Version subtreeVersion); /** @@ -38,6 +40,7 @@ public interface MutableTreeNode extends StoreTreeNode { * * @param child New child node. */ + // FIXME: 3.0.0: document NullPointerException being thrown void addChild(TreeNode child); /** @@ -46,6 +49,7 @@ public interface MutableTreeNode extends StoreTreeNode { * * @param id Child identificator. */ + // FIXME: 3.0.0: document NullPointerException being thrown void removeChild(PathArgument id); /** diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/TreeNode.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/TreeNode.java index d8adb3b676..805c82d6f7 100644 --- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/TreeNode.java +++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/spi/TreeNode.java @@ -29,6 +29,7 @@ import org.opendaylight.yangtools.yang.data.api.schema.tree.StoreTreeNode; */ // FIXME: BUG-2399: clarify that versioning rules are not enforced for non-presence containers, as they are not // considered to be data nodes. +// FIXME: 3.0.0: Use @NonNullByDefault public interface TreeNode extends Identifiable, StoreTreeNode { /** * Get the data node version. This version is updated whenever the data representation of this particular node -- 2.36.6