Fix a javadoc typo

[yangtools.git] / yang / yang-parser-spi / src / main / java / org / opendaylight / yangtools / yang / parser / spi / meta / NamespaceBehaviour.java

diff --git a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/NamespaceBehaviour.java b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/NamespaceBehaviour.java
index 487175e51f091faaedbbf1b7f6715b2de8af493c..20782e2b8ac1cd167e8ed2bf1dbd8a7f005af060 100644 (file)
--- a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/NamespaceBehaviour.java
+++ b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/NamespaceBehaviour.java
@@ -9,7 +9,7 @@ package org.opendaylight.yangtools.yang.parser.spi.meta;
 
 import static java.util.Objects.requireNonNull;
 
-import com.google.common.base.MoreObjects;
+import com.google.common.annotations.Beta;
 import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.base.Verify;
 import java.util.Map;
@@ -17,8 +17,13 @@ import java.util.Map.Entry;
 import java.util.Optional;
 import org.eclipse.jdt.annotation.NonNull;
 import org.eclipse.jdt.annotation.Nullable;
-import org.opendaylight.yangtools.concepts.Identifiable;
+import org.opendaylight.yangtools.concepts.AbstractIdentifiable;
+import org.opendaylight.yangtools.yang.common.QName;
+import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
+import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
 import org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace;
+import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeAwareEffectiveStatement;
+import org.opendaylight.yangtools.yang.parser.spi.SchemaTreeNamespace;
 
 /**
  * Definition / implementation of specific Identifier Namespace behaviour. A namespace behaviour is built on top
@@ -33,7 +38,8 @@ import org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace;
  * @param <V> Value type
  * @param <N> Namespace Type
  */
-public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K, V>> implements Identifiable<Class<N>> {
+public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K, V>>
+        extends AbstractIdentifiable<Class<N>> {
 
     public enum StorageNodeType {
         /**
@@ -43,7 +49,7 @@ public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K,
         /**
          * Storage of the root statement of a particular source and any sources it is importing.
          */
-        // FIXME: 3.0.0: this is a misnomer and should be renamed
+        // FIXME: 7.0.0: this is a misnomer and should be renamed
         SOURCE_LOCAL_SPECIAL,
         /**
          * Storage of a single statement.
@@ -107,10 +113,38 @@ public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K,
                 V value);
     }
 
-    private final @NonNull Class<N> identifier;
+    /**
+     * Interface implemented by {@link NamespaceStorageNode}s which support dynamic addition of child elements as they
+     * are requested. This means that such a node can, defer creation of child namespace storage nodes, in effect lazily
+     * expanding this namespace on an if-needed basis.
+     */
+    @Beta
+    public interface OnDemandSchemaTreeStorageNode extends NamespaceStorageNode {
+        /**
+         * Request that a new member of this node's schema tree statement be added. Implementations are required to
+         * perform lookup in their internal structure and create a child if tractable. Resulting node is expected to
+         * have been registered with local storage, so that it is accessible through
+         * {@link #getFromLocalStorage(Class, Object)}.
+         *
+         * <p>
+         * This method must not change its mind about a child's presence -- once it returns non-present, it has to be
+         * always returning non-present.
+         *
+         * <p>
+         * The results produced by this method are expected to be consistent with
+         * {@link SchemaTreeAwareEffectiveStatement#findSchemaTreeNode(QName)} and
+         * {@link SchemaTreeNamespace#getFrom(NamespaceStorageNode, QName)}.
+         *
+         * @param qname node identifier of the child being requested
+         * @return Requested child, if it is present.
+         * @throws NullPointerException in {@code qname} is null
+         */
+        <D extends DeclaredStatement<QName>, E extends EffectiveStatement<QName, D>>
+            @Nullable StmtContext<QName, D, E> requestSchemaTreeChild(QName qname);
+    }
 
     protected NamespaceBehaviour(final Class<N> identifier) {
-        this.identifier = requireNonNull(identifier);
+        super(identifier);
     }
 
     /**
@@ -242,11 +276,6 @@ public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K,
      */
     public abstract void addTo(NamespaceStorageNode storage, K key, V value);
 
-    @Override
-    public Class<N> getIdentifier() {
-        return identifier;
-    }
-
     protected final V getFromLocalStorage(final NamespaceStorageNode storage, final K key) {
         return storage.getFromLocalStorage(getIdentifier(), key);
     }
@@ -260,7 +289,7 @@ public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K,
     }
 
     static final class StorageSpecific<K, V, N extends IdentifierNamespace<K, V>> extends NamespaceBehaviour<K, V, N> {
-        StorageNodeType storageType;
+        private final StorageNodeType storageType;
 
         StorageSpecific(final Class<N> identifier, final StorageNodeType type) {
             super(identifier);
@@ -344,11 +373,7 @@ public abstract class NamespaceBehaviour<K, V, N extends IdentifierNamespace<K,
     }
 
     @Override
-    public final String toString() {
-        return addToStringAttributes(MoreObjects.toStringHelper(this)).toString();
-    }
-
     protected ToStringHelper addToStringAttributes(final ToStringHelper helper) {
-        return helper.add("identifier", identifier.getName());
+        return helper.add("identifier", getIdentifier().getName());
     }
 }