BUG-4268: clarify API contract of range constraints

The API definition is not clear whether the constraints show the
declared or effective view of range constraints.

Implementations have been returning the effective view, e.g. including
ranges from base types, which is the API intent. Clarify the API.

Change-Id: I6edecae04b9cba3b1452584b7cf7645dfcc5e57b
Signed-off-by: Robert Varga <robert.varga@pantheon.sk>

diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/DecimalTypeDefinition.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/DecimalTypeDefinition.java
index edf42c4d4bfb4287e53128fbb71e2502a509280d..66bc99fc80e5b7894e64fb4a70ecda7f3b658479 100644 (file)
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/DecimalTypeDefinition.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/DecimalTypeDefinition.java
@@ -8,35 +8,35 @@
 package org.opendaylight.yangtools.yang.model.api.type;
 
 import java.util.List;
-
+import javax.annotation.Nonnull;
 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
 
 /**
  * Contains methods for getting data from the YANG <code>type</code>
  * substatement for <code>decimal64</code> built-in type.
- * 
+ *
  */
 public interface DecimalTypeDefinition extends TypeDefinition<DecimalTypeDefinition> {
 
     /**
      * Returns range constraints for instance of this type.
-     * 
+     *
      * @return list of range constraints which are specified as the argument of
      *         the <code>range</code> which is substatement of the
      *         <code>type</code> statement
      */
-    List<RangeConstraint> getRangeConstraints();
+    @Nonnull List<RangeConstraint> getRangeConstraints();
 
     /**
      * Returns integer between 1 and 18 inclusively. <br>
      * <br>
-     * 
+     *
      * The "fraction-digits" statement controls the size of the minimum
      * difference between values of a decimal64 type, by restricting the value
      * space to numbers that are expressible as "i x 10^-n" where n is the
      * fraction-digits argument.
-     * 
+     *
      * @return number of fraction digits
      */
-    Integer getFractionDigits();
+    @Nonnull Integer getFractionDigits();
 }

diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/IntegerTypeDefinition.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/IntegerTypeDefinition.java
index 3bc928cf58fb5428b41b740d9239541b2e254dd0..dd53bb74e2af7b0ba364e55ab616c83b08844de3 100644 (file)
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/IntegerTypeDefinition.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/IntegerTypeDefinition.java
@@ -8,6 +8,7 @@
 package org.opendaylight.yangtools.yang.model.api.type;
 
 import java.util.List;
+import javax.annotation.Nonnull;
 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
 
 /**
@@ -25,9 +26,10 @@ import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
 public interface IntegerTypeDefinition extends TypeDefinition<IntegerTypeDefinition> {
 
     /**
-     * Returns Range Constraints defined for given Integer Type.
+     * Returns Range Constraints defined for given Integer Type. These are the effective constraints, e.g. they include
+     * any range constraints imposed by base types.
      *
      * @return Range Constraints defined for given Integer Type.
      */
-    List<RangeConstraint> getRangeConstraints();
+    @Nonnull List<RangeConstraint> getRangeConstraints();
 }

diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/UnsignedIntegerTypeDefinition.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/UnsignedIntegerTypeDefinition.java
index b380044651022a4569e4b917e74bd666213606ed..20c04acc9579dc795c9163ade1fc93dafeff7b7c 100644 (file)
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/UnsignedIntegerTypeDefinition.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/type/UnsignedIntegerTypeDefinition.java
@@ -8,24 +8,22 @@
 package org.opendaylight.yangtools.yang.model.api.type;
 
 import java.util.List;
-
+import javax.annotation.Nonnull;
 import org.opendaylight.yangtools.yang.model.api.TypeDefinition;
 
 /**
- * 
  * Contains the method for getting detail data about unsigned integer.
- * 
+ *
  * Specifically it is the method for getting the range value.
- * 
  */
 public interface UnsignedIntegerTypeDefinition extends TypeDefinition<UnsignedIntegerTypeDefinition> {
-
     /**
      * Returns range data of the instance of the type
-     * <code>UnsignedIntegerTypeDefinition</code>.
-     * 
+     * <code>UnsignedIntegerTypeDefinition</code>. These are the effective constraints, e.g. they include
+     * any range constraints imposed by base types.
+     *
      * @return list of <code>RangeConstraint</code> which represents the YANG
      *         <code>range</code> substatement arguments.
      */
-    List<RangeConstraint> getRangeConstraints();
+    @Nonnull List<RangeConstraint> getRangeConstraints();
 }