Propagate EffectiveModelContext to more places

[yangtools.git] / yang / yang-data-api / src / main / java / org / opendaylight / yangtools / yang / data / api / schema / tree / DataTreeFactory.java

diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeFactory.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeFactory.java
index 84f50179c7f0ad5b0df7653bb42d7ea2a39a9c0e..2a3055ae57694305d700b6923d6316b6988cb484 100644 (file)
--- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeFactory.java
+++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/tree/DataTreeFactory.java
@@ -7,14 +7,56 @@
  */
 package org.opendaylight.yangtools.yang.data.api.schema.tree;
 
+import org.eclipse.jdt.annotation.NonNull;
+import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNodeContainer;
+import org.opendaylight.yangtools.yang.model.api.EffectiveModelContext;
+
 /**
  * Factory interface for creating data trees.
  */
 public interface DataTreeFactory {
     /**
-     * Create a new data tree.
+     * Create a new data tree based on specified configuration, with a best-guess root. Use this method only if you
+     * do not have a corresponding SchemaContext handy. Mandatory nodes whose enforcement point is the root node will
+     * not be enforced even if some are present in the SchemaContext and validation is requested in configuration.
+     *
+     * <p>
+     * Correctness note: this method may not accurately initialize the root node in certain non-root scenarios due to
+     * the impossibility to accurately derive root type from plain YangInstanceIdentifier. Using
+     * {@link #create(DataTreeConfiguration, EffectiveModelContext)} is recommended, as it does not suffer from this
+     * shortcoming.
+     *
+     * @param treeConfig
+     *          Tree configuration.
+     * @return A data tree instance.
+     * @throws NullPointerException if treeConfig is null
+     */
+    @NonNull DataTree create(DataTreeConfiguration treeConfig);
+
+    /**
+     * Create a new data tree based on specified configuration, with a root node derived from the schema context lookup
+     * of the configuration. Mandatory nodes whose enforcement point is the root node will not be enforced even if some
+     * are present in the SchemaContext and validation is requested in configuration.
+     *
+     * @param treeConfig
+     *          Tree configuration.
+     * @return A data tree instance.
+     * @throws NullPointerException if any of the arguments are null
+     * @throws IllegalArgumentException if tree configuration does not match the SchemaContext, for example by root path
+     *                                  referring to a node which does not exist in the SchemaContext
+     */
+    @NonNull DataTree create(DataTreeConfiguration treeConfig, EffectiveModelContext initialSchemaContext);
+
+    /**
+     * Create a new data tree based on specified configuration, with the specified node.
      *
+     * @param treeConfig
+     *          Tree configuration.
      * @return A data tree instance.
+     * @throws DataValidationFailedException if initial root is not valid according to the schema context
+     * @throws NullPointerException if any of the arguments are null
+     * @throws IllegalArgumentException if a mismatch between the arguments is detected
      */
-    DataTree create();
+    @NonNull DataTree create(DataTreeConfiguration treeConfig, EffectiveModelContext initialSchemaContext,
+            NormalizedNodeContainer<?, ?, ?> initialRoot) throws DataValidationFailedException;
 }