import org.opendaylight.yangtools.yang.common.QName;
+/**
+ *
+ * Container of attributes, which may be attached to {@link Node}
+ *
+ */
public interface AttributesContainer {
+ /**
+ * Returns immutable map of QName and value of the attribute.
+ *
+ * @return immutable map of attribute names and values.
+ */
Map<QName, String> getAttributes();
- Object getAttributeValue(QName value);
+ /**
+ * Returns attribute value by supplied QName
+ *
+ *
+ * @param name Attribute name
+ * @return Value of attribute if present, null otherwise.
+ */
+ Object getAttributeValue(QName name);
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import org.opendaylight.yangtools.concepts.Immutable;
import org.opendaylight.yangtools.concepts.Path;
import org.opendaylight.yangtools.yang.common.QName;
-import org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode;
-import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
-import org.opendaylight.yangtools.yang.data.api.schema.LeafNode;
import org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode;
-import org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode;
import com.google.common.base.Optional;
import com.google.common.base.Preconditions;
import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;
+/**
+ * Unique identifier of a partical node instance in the data tree.
+ *
+ *
+ * <p>
+ * Java representation of YANG Built-in type <code>instance-identifier</code>,
+ * which conceptually is XPath expression minimised to uniquely identify element
+ * in data tree which conforms to constraints maintained by YANG Model,
+ * effectively this makes Instance Identifier a path to element in data tree.
+ * <p>
+ * Constraints put in YANG specification on instance-identifier allowed it to be
+ * effectively represented in Java and it's evaluation does not require
+ * full-blown XPath processor.
+ * <p>
+ * <h3>Path Arguments</h3>
+ * Path to the node represented in instance identifier consists of
+ * {@link PathArgument} which carries necessary information to uniquely identify
+ * node on particular level in the subtree.
+ * <p>
+ * <ul>
+ * <li>{@link NodeIdentifier} - Identifier of node, which has cardinality
+ * <code>0..1</code> in particular subtree in data tree.</li>
+ * <li>{@link NodeIdentifierWithPredicates} - Identifier of node (list item),
+ * which has cardinality <code>0..n</code>.</li>
+ * <li>{@link NodeWithValue} - Identifier of instance <code>leaf</code> node or
+ * <code>leaf-list</code> node.</li>
+ * <li>{@link AugmentationIdentifier} - Identifier of instance of
+ * <code>augmentation</code> node.</li>
+ * </ul>
+ *
+ *
+ * @see http://tools.ietf.org/html/rfc6020#section-9.13
+ *
+ *
+ */
public class InstanceIdentifier implements Path<InstanceIdentifier>, Immutable, Serializable {
private static final long serialVersionUID = 8467409862384206193L;
private transient String toStringCache = null;
private transient Integer hashCodeCache = null;
+ /**
+ *
+ * Returns a list of path arguments.
+ *
+ * @deprecated Use {@link #getPathArguments()} instead.
+ * @return Immutable list of path arguments.
+ */
+ @Deprecated
public List<PathArgument> getPath() {
return path;
}
+ /**
+ *
+ * Returns a ordered iteration of path arguments.
+ *
+ * @return Immutable iteration of path arguments.
+ */
+ public Iterable<PathArgument> getPathArguments() {
+ return path;
+ }
+
+ /**
+ *
+ *
+ * @deprecated Use {@link #create(Iterable)} instead.
+ * @param path
+ */
+ @Deprecated
public InstanceIdentifier(final List<? extends PathArgument> path) {
this.path = ImmutableList.copyOf(path);
}
+ private InstanceIdentifier(final Iterable<? extends PathArgument> path) {
+ Preconditions.checkNotNull(path, "path must not be null.");
+ this.path = ImmutableList.copyOf(path);
+ }
+
private InstanceIdentifier(final NodeIdentifier nodeIdentifier) {
this.path = ImmutableList.<PathArgument> of(nodeIdentifier);
}
+ public static final InstanceIdentifier create(final Iterable<? extends PathArgument> path) {
+ return new InstanceIdentifier(path);
+ }
+
@Override
public int hashCode() {
/*
* The hashCodeCache is safe, since the object contract requires
* immutability of the object and all objects referenced from this
* object.
- *
* Used lists, maps are immutable. Path Arguments (elements) are also
* immutable, since the PathArgument contract requires immutability.
- *
* The cache is thread-safe - if multiple computations occurs at the
* same time, cache will be overwritten with same result.
*/
if (hashCodeCache == null) {
final int prime = 31;
int result = 1;
- result = prime * result + ((path == null) ? 0 : path.hashCode());
+ result = prime * result + path.hashCode();
hashCodeCache = result;
}
return hashCodeCache;
return true;
}
+ /**
+ *
+ * Constructs a new Instance Identifier with new {@link NodeIdentifier} added to the end of path arguments
+ *
+ * @param name QName of {@link NodeIdentifier}
+ * @return Instance Identifier with additional path argument added to the end.
+ */
public InstanceIdentifier node(final QName name) {
return node(new NodeIdentifier(name));
}
+ /**
+ *
+ * Constructs a new Instance Identifier with new {@link PathArgument} added to the end of path arguments
+ *
+ * @param arg Path argument which should be added to the end
+ * @return Instance Identifier with additional path argument added to the end.
+ */
public InstanceIdentifier node(final PathArgument arg) {
- return new InstanceIdentifier(ImmutableList.<PathArgument>builder().addAll(path).add(arg).build());
+ return create(ImmutableList.<PathArgument> builder().addAll(path).add(arg).build());
}
/**
- * Get the relative path from an ancestor. This method attempts to perform the reverse
+ * Get the relative path from an ancestor. This method attempts to perform
+ * the reverse
* of concatenating a base (ancestor) and a path.
*
- * @param ancestor Ancestor against which the relative path should be calculated
- * @return This object's relative path from parent, or Optional.absent() if the
+ * @param ancestor
+ * Ancestor against which the relative path should be calculated
+ * @return This object's relative path from parent, or Optional.absent() if
+ * the
* specified parent is not in fact an ancestor of this object.
*/
public Optional<InstanceIdentifier> relativeTo(final InstanceIdentifier ancestor) {
}
}
- static int hashCode( Object value ) {
- if( value == null ) {
+ static int hashCode(final Object value) {
+ if (value == null) {
return 0;
}
- if( value.getClass().equals( byte[].class ) ) {
- return Arrays.hashCode( (byte[])value );
+ if (value.getClass().equals(byte[].class)) {
+ return Arrays.hashCode((byte[]) value);
}
- if( value.getClass().isArray() ) {
+ if (value.getClass().isArray()) {
int hash = 0;
- int length = Array.getLength( value );
- for( int i = 0; i < length; i++ ) {
- hash += Objects.hashCode( Array.get( value, i ) );
+ int length = Array.getLength(value);
+ for (int i = 0; i < length; i++) {
+ hash += Objects.hashCode(Array.get(value, i));
}
return hash;
}
- return Objects.hashCode( value );
+ return Objects.hashCode(value);
}
// Static factories & helpers
+ /**
+ *
+ * Returns a new InstanceIdentifier with only one path argument of type {@link NodeIdentifier} with supplied QName
+ *
+ * @param name QName of first node identifier
+ * @return Instance Identifier with only one path argument of type {@link NodeIdentifier}
+ */
public static InstanceIdentifier of(final QName name) {
return new InstanceIdentifier(new NodeIdentifier(name));
}
+ /**
+ *
+ * Returns new builder for InstanceIdentifier with empty path arguments.
+ *
+ * @return new builder for InstanceIdentifier with empty path arguments.
+ */
static public InstanceIdentifierBuilder builder() {
return new BuilderImpl();
}
+ /**
+ *
+ * Returns new builder for InstanceIdentifier with path arguments copied from original instance identifier.
+ *
+ * @param origin Instace Identifier from which path arguments are copied.
+ * @return new builder for InstanceIdentifier with path arguments copied from original instance identifier.
+ */
static public InstanceIdentifierBuilder builder(final InstanceIdentifier origin) {
return new BuilderImpl(origin.getPath());
}
-
+ /**
+ *
+ * Returns new builder for InstanceIdentifier with first path argument set to {@link NodeIdentifier}.
+ *
+ * @param node QName of first {@link NodeIdentifier} path argument.
+ * @return new builder for InstanceIdentifier with first path argument set to {@link NodeIdentifier}.
+ */
public static InstanceIdentifierBuilder builder(final QName node) {
return builder().node(node);
}
+ /**
+ *
+ * Path argument / component of InstanceIdentifier
+ *
+ * Path argument uniquelly identifies node in data tree on particular
+ * level.
+ * <p>
+ * This interface itself is used as common parent for actual
+ * path arguments types and should not be implemented by user code.
+ * <p>
+ * Path arguments SHOULD contain only minimum of information
+ * required to uniquely identify node on particular subtree level.
+ *
+ * For actual path arguments types see:
+ * <ul>
+ * <li>{@link NodeIdentifier} - Identifier of container or leaf
+ * <li>{@link NodeIdentifierWithPredicates} - Identifier of list entries, which have key defined
+ * <li>{@link AugmentationIdentifier} - Identifier of augmentation
+ * <li>{@link NodeWithValue} - Identifier of leaf-list entry
+ * </ul>
+ *
+ *
+ *
+ */
public interface PathArgument extends Immutable, Serializable {
/**
}
+ /**
+ *
+ * Fluent Builder of Instance Identifier instances
+ *
+ * @
+ *
+ */
public interface InstanceIdentifierBuilder extends Builder<InstanceIdentifier> {
+
+ /**
+ *
+ * Adds {@link NodeIdentifier} with supplied QName to path arguments of resulting instance identifier.
+ *
+ * @param nodeType QName of {@link NodeIdentifier} which will be added
+ * @return this builder
+ */
InstanceIdentifierBuilder node(QName nodeType);
+ /**
+ *
+ * Adds {@link NodeIdentifierWithPredicates} with supplied QName and key values to path arguments of resulting instance identifier.
+ *
+ * @param nodeType QName of {@link NodeIdentifierWithPredicates} which will be added
+ * @param keyValues Map of key components and their respective values for {@link NodeIdentifierWithPredicates}
+ * @return this builder
+ */
InstanceIdentifierBuilder nodeWithKey(QName nodeType, Map<QName, Object> keyValues);
+ /**
+ *
+ * Adds {@link NodeIdentifierWithPredicates} with supplied QName and key, value.
+ *
+ * @param nodeType QName of {@link NodeIdentifierWithPredicates} which will be added
+ * @param key QName of key which will be added
+ * @param value value of key which will be added
+ * @return this builder
+ */
InstanceIdentifierBuilder nodeWithKey(QName nodeType, QName key, Object value);
+ /**
+ *
+ * @return
+ * @deprecated use {@link #build()}
+ *
+ */
@Deprecated
InstanceIdentifier getIdentifier();
+ /**
+ *
+ * Builds an {@link InstanceIdentifier} with path arguments from this builder
+ *
+ * @return {@link InstanceIdentifier}
+ */
InstanceIdentifier build();
}
/**
- * Simple path argument identifying a {@link ContainerNode} or {@link LeafNode} leaf
- * overall data tree.
+ * Simple path argument identifying a {@link org.opendaylight.yangtools.yang.data.api.schema.ContainerNode} or
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} leaf in particular subtree.
*/
public static final class NodeIdentifier implements PathArgument, Comparable<NodeIdentifier> {
private static final long serialVersionUID = -2255888212390871347L;
}
/**
- * Composite path argument identifying a {@link MapEntryNode} leaf
+ * Composite path argument identifying a {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} leaf
* overall data tree.
*/
public static final class NodeIdentifierWithPredicates implements PathArgument {
}
public NodeIdentifierWithPredicates(final QName node, final QName key, final Object value) {
- this( node, ImmutableMap.of(key, value) );
+ this(node, ImmutableMap.of(key, value));
}
@Override
private int hashKeyValues() {
int hash = 0;
- for( Entry<QName,Object> entry: keyValues.entrySet() ) {
- hash += Objects.hashCode( entry.getKey() ) + InstanceIdentifier.hashCode( entry.getValue() );
+ for (Entry<QName, Object> entry : keyValues.entrySet()) {
+ hash += Objects.hashCode(entry.getKey()) + InstanceIdentifier.hashCode(entry.getValue());
}
return hash;
return true;
}
- private boolean keyValuesEquals( Map<QName, Object> otherKeyValues ) {
- if( otherKeyValues == null || keyValues.size() != otherKeyValues.size() ) {
+ private boolean keyValuesEquals(final Map<QName, Object> otherKeyValues) {
+ if (otherKeyValues == null || keyValues.size() != otherKeyValues.size()) {
return false;
}
boolean result = true;
- for( Entry<QName,Object> entry: keyValues.entrySet() ) {
- if( !otherKeyValues.containsKey( entry.getKey() ) ||
- !Objects.deepEquals( entry.getValue(), otherKeyValues.get( entry.getKey() ) ) ) {
+ for (Entry<QName, Object> entry : keyValues.entrySet()) {
+ if (!otherKeyValues.containsKey(entry.getKey())
+ || !Objects.deepEquals(entry.getValue(), otherKeyValues.get(entry.getKey()))) {
result = false;
break;
public int hashCode() {
final int prime = 31;
int result = 1;
- result = prime * result + ((value == null) ? 0 : InstanceIdentifier.hashCode( value ) );
+ result = prime * result + ((value == null) ? 0 : InstanceIdentifier.hashCode(value));
result = prime * result + ((nodeType == null) ? 0 : nodeType.hashCode());
return result;
}
}
/**
- * Composite path argument identifying a {@link AugmentationNode} leaf
- * overall data tree.
+ * Composite path argument identifying a {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode} node in
+ * particular subtree.
+ *
+ * Augmentation is uniquely identified by set of all possible child nodes.
+ * This is possible
+ * to identify instance of augmentation,
+ * since RFC6020 states that <code>augment</code> that augment
+ * statement must not add multiple nodes from same namespace
+ * / module to the target node.
+ *
+ *
+ * @see http://tools.ietf.org/html/rfc6020#section-7.15
*/
public static final class AugmentationIdentifier implements PathArgument {
private static final long serialVersionUID = -8122335594681936939L;
throw new UnsupportedOperationException("Augmentation node has no QName");
}
+ /**
+ *
+ * Construct new augmentation identifier using supplied set of possible
+ * child nodes
+ *
+ * @param childNames
+ * Set of possible child nodes.
+ */
public AugmentationIdentifier(final Set<QName> childNames) {
this.childNames = ImmutableSet.copyOf(childNames);
}
/**
* Augmentation node has no QName
+ *
+ * @deprecated Use
+ * {@link AugmentationIdentifier#AugmentationIdentifier(Set)}
+ * instead.
*/
@Deprecated
public AugmentationIdentifier(final QName nodeType, final Set<QName> childNames) {
this(childNames);
}
+ /**
+ *
+ * Returns set of all possible child nodes
+ *
+ * @return set of all possible child nodes.
+ */
public Set<QName> getPossibleChildNames() {
return childNames;
}
* The toStringCache is safe, since the object contract requires
* immutability of the object and all objects referenced from this
* object.
- *
* Used lists, maps are immutable. Path Arguments (elements) are also
* immutable, since the PathArgument contract requires immutability.
- *
* The cache is thread-safe - if multiple computations occurs at the
* same time, cache will be overwritten with same result.
*/
* Returns parent node
*
* @return parent node
+ * @deprecated Unused, Deprecated because reference to parent disallows of sharing one instance
+ * in multiple trees / subtress.
*/
@Deprecated
CompositeNode getParent();
import org.opendaylight.yangtools.concepts.Codec;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier;
-
+/**
+ *
+ * Codec which serializes / deserializes InstanceIdentifier
+ *
+ * @param <T> Target type
+ */
public interface InstanceIdentifierCodec<T> extends Codec<T,InstanceIdentifier> {
@Override
T serialize(InstanceIdentifier data);
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.AugmentationIdentifier;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument;
+import org.opendaylight.yangtools.yang.model.api.AugmentationSchema;
-import com.google.common.base.Optional;
/**
*
- * Node representing Augmentation.
+ * Data instance of <code>augment</code> assiociated with parent node.
+ *
+ * Augmentation is addition of subtree defined by other external YANG Model and
+ * is schema for subtree is described by instance of {@link AugmentationSchema}
+ * associated with parent node of this node.
*
* Augmentation node MUST NOT be direct child of other augmentation node.
*
DataContainerNode<AugmentationIdentifier>,
DataContainerChild<InstanceIdentifier.AugmentationIdentifier, Iterable<DataContainerChild<? extends PathArgument, ?>>> {
+ /**
+ * Gets identifier of augmentation node
+ *
+ * Returned identifier of augmentation node contains all possible
+ * direct child QNames.
+ *
+ * This is sufficient to identify instance of augmentation,
+ * since RFC6020 states that <code>augment</code> that augment
+ * statement must not add multiple nodes from same namespace
+ * / module
+ * to the target node.
+ *
+ * @return Identifier which uniquelly identifies augmentation in particular subtree.
+ *
+ */
@Override
- Iterable<DataContainerChild<? extends PathArgument, ?>> getValue();
-
- @Override
- Optional<DataContainerChild<? extends PathArgument, ?>> getChild(PathArgument child);
-
- @Override
- AugmentationIdentifier getIdentifier();
+ public AugmentationIdentifier getIdentifier();
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument;
-import com.google.common.base.Optional;
-
/**
*
- * Node representing choice.
+ * Node representing data instance of <code>choice</code>.
*
- * @author Tony Tkacik
+ * Choice node is instance of one of possible alternatives, from which
+ * only one is allowed to exist at one time in particular context of parent node.
+ YANG Model and
+ * schema for choice is described by instance of {@link org.opendaylight.yangtools.yang.model.api.ChoiceNode}.
+ * Valid alternatives of subtree are described by instances of {@link org.opendaylight.yangtools.yang.model.api.ChoiceCaseNode}
+ * which are retrieved via {@link org.opendaylight.yangtools.yang.model.api.ChoiceNode#getCases()}.
*
*/
public interface ChoiceNode extends //
DataContainerNode<NodeIdentifier>,
DataContainerChild<NodeIdentifier, Iterable<DataContainerChild<? extends PathArgument, ?>>> {
- @Override
- NodeIdentifier getIdentifier();
-
- @Override
- Optional<DataContainerChild<? extends PathArgument, ?>> getChild(PathArgument child);
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument;
-import com.google.common.base.Optional;
-
+/**
+ * Data subtree with cardinality 0..1 in the context of parent node
+ *
+ * Node which does not have value but contains valid {@link DataContainerChild} nodes.
+ *
+ * Schema of this node is described by instance of {@link org.opendaylight.yangtools.yang.model.api.ContainerSchemaNode}.
+ *
+ */
public interface ContainerNode extends //
AttributesContainer,
DataContainerNode<NodeIdentifier>,
DataContainerChild<NodeIdentifier, Iterable<DataContainerChild<? extends PathArgument, ?>>> {
- @Override
- NodeIdentifier getIdentifier();
-
- @Override
- Optional<DataContainerChild<? extends PathArgument, ?>> getChild(PathArgument child);
}
/**
*
* Marker interface for direct children of {@link DataContainerNode}.
- *
- * Implementation notes:
+ *
+ * <h3>Implementation notes</h3>
* This interface should not be implemented directly, but rather using one
* of its subinterfaces:
*
+ * <ul>
+ * <li>{@link LeafNode}
+ * <li>{@link ContainerNode}
+ * <li>{@link ChoiceNode}
+ * <li>{@link MapNode}
+ * <li>{@link AugmentationNode}
+ *</ul>
*
- * {@link LeafNode}
- * {@link ContainerNode}
- * {@link ChoiceNode}
- * {@link MapNode}
- * {@link AugmentationNode}
- *
- * @param <K>
- * @param <V>
+ * @param <K> Path Argument Type which is used to identify node
+ * @param <V> Value type
*/
public interface DataContainerChild<K extends PathArgument,V> extends NormalizedNode<K, V> {
+
@Override
K getIdentifier();
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument;
-import com.google.common.base.Optional;
-
+/**
+ *
+ * Abstract node which does not have value but contains valid {@link DataContainerChild} nodes.
+ *
+ * Schema of this node is described by instance of {@link org.opendaylight.yangtools.yang.model.api.DataNodeContainer}.
+ *
+ * <h2>Implementation notes</h2>
+ * This interface should not be implemented directly, but rather implementing one of it's subclasses
+ * <ul>
+ * <li>{@link ContainerNode}
+ * <li>{@link MapEntryNode}
+ * <li>{@link UnkeyedListEntryNode}
+ * <li>{@link ChoiceNode}
+ * <li>{@link AugmentationNode}
+ * </ul>
+ *
+ * @param <K> {@link PathArgument} which identifies instance of {@link DataContainerNode}
+ */
public interface DataContainerNode<K extends PathArgument> extends //
NormalizedNodeContainer<K, PathArgument, DataContainerChild<? extends PathArgument, ?>> {
- @Override
- K getIdentifier();
+ /**
+ * Returns iteration of all child nodes
+ *
+ * Order of returned child nodes may be defined by subinterfaces.
+ *
+ * <b>Implementation Notes:</b>
+ * <p>
+ * All nodes returned in this iterable, MUST also be accessible via
+ * {@link #getChild(PathArgument)} using their associated identifier.
+ *
+ * @return Iteration of all child nodes
+ */
@Override
Iterable<DataContainerChild<? extends PathArgument, ?>> getValue();
-
- @Override
- Optional<DataContainerChild<? extends PathArgument, ?>> getChild(PathArgument child);
}
import org.opendaylight.yangtools.yang.data.api.AttributesContainer;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
+/**
+ *
+ * Leaf node with multiplicity 0..1
+ *
+ * Leaf node has a value, but no child nodes in the data tree, schema
+ * for leaf node and its value is described by {@link org.opendaylight.yangtools.yang.model.api.LeafSchemaNode}.
+ *
+ * @param <T> Value type
+ */
public interface LeafNode<T> extends //
AttributesContainer,
DataContainerChild<NodeIdentifier, T> {
+
+
+ /**
+ *
+ * Returns value of this leaf node
+ *
+ * @return Returned value of this leaf node. Value SHOULD meet criteria defined by schema.
+ *
+ */
@Override
- NodeIdentifier getIdentifier();
+ T getValue();
+
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import org.opendaylight.yangtools.yang.data.api.AttributesContainer;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeWithValue;
-public interface LeafSetEntryNode<T> extends
- AttributesContainer,
- NormalizedNode<NodeWithValue, T> {
+/**
+ *
+ * Leaf node with multiplicity 0...n
+ *
+ * Leaf node has a value, but no child nodes in the data tree, schema
+ * for leaf node and its value is described by
+ * {@link org.opendaylight.yangtools.yang.model.api.LeafListSchemaNode}.
+ *
+ * @param <T>
+ * Value type
+ */
+public interface LeafSetEntryNode<T> extends AttributesContainer, NormalizedNode<NodeWithValue, T> {
+
+ /**
+ * Returns {@link NodeWithValue} which identifies this leaf set entry.
+ *
+ * Returned {@link NodeWithValue} contains same value as this node.
+ *
+ * <h3>Implementation notes</h3> Invocation of
+ * {@link NodeWithValue#getValue()} on returned instance of
+ * {@link NodeWithValue} must returns
+ * same value as invocation of {@link #getValue()}, such as
+ * following condition is allways met:
+ * <code>true == this.getIdentifier().getValue().equals(this.getValue())</code>
+ *
+ *
+ * @return {@link NodeWithValue} which identifies this leaf set entry.
+ */
@Override
NodeWithValue getIdentifier();
+
+ /**
+ *
+ * Returns value of this leaf node
+ *
+ * <h3>Implementation notes</h3> Invocation of {@link #getValue()} must
+ * provides same value as value in {@link #getIdentifier()}.
+ * <code>true == this.getIdentifier().getValue().equals(this.getValue())</code>
+ *
+ * @return Returned value of this leaf node. Value SHOULD meet criteria
+ * defined by schema.
+ *
+ */
+ @Override
+ public T getValue();
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeWithValue;
-import com.google.common.base.Optional;
-
+/**
+ *
+ * Node representing set of simple leaf nodes.
+ *
+ * Node containing instances of {@link LeafSetEntryNode}
+ *
+ * Schema and semantics of this node are described by instance of {@link org.opendaylight.yangtools.yang.model.api.LeafListSchema}.
+ *
+ *
+ * @param <T> Type of leaf node values.
+ */
public interface LeafSetNode<T> extends
MixinNode, //
DataContainerChild<NodeIdentifier, Iterable<LeafSetEntryNode<T>>>, //
NormalizedNodeContainer<NodeIdentifier, NodeWithValue,LeafSetEntryNode<T>> {
- @Override
- NodeIdentifier getIdentifier();
-
- @Override
- Iterable<LeafSetEntryNode<T>> getValue();
-
- @Override
- Optional<LeafSetEntryNode<T>> getChild(NodeWithValue child);
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import org.opendaylight.yangtools.yang.data.api.AttributesContainer;
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifierWithPredicates;
-public interface MapEntryNode extends
- AttributesContainer,
- DataContainerNode<NodeIdentifierWithPredicates> {
+/**
+ *
+ * Instance of Map entry, this node does not contains value, but child nodes.
+ *
+ */
+public interface MapEntryNode extends AttributesContainer, DataContainerNode<NodeIdentifierWithPredicates> {
+ /**
+ *
+ * Returns identifier of this node in parent map node
+ *
+ * Contents of identifier is defined by <code>key</code> (
+ * {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.ListSchemaNode#getKeyDefinition()}
+ * ) statement in YANG schema for associated list item and child {@link LeafNode}s
+ * values with {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier}
+ * as defined in the schema.
+ *
+ * @return identifier of this node in the context of parent node
+ */
@Override
NodeIdentifierWithPredicates getIdentifier();
+
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifierWithPredicates;
/**
- * Containment node, which contains {@link MapEntryNode} of the same type.
+ * Containment node, which contains {@link MapEntryNode} of the same type, which may
+ * be quickly retrieved using key.
*
- * This node maps to the list node in YANG schema.
+ * This node maps to the list node in YANG schema, schema and semantics of this node,
+ * its children and key construction is defined by YANG <code>list</code>
+ * statement and its <code>key</code> and <code>ordered-by</code> substatements.
*
*/
public interface MapNode extends //
DataContainerChild<NodeIdentifier, Iterable<MapEntryNode>>,
NormalizedNodeContainer<NodeIdentifier, NodeIdentifierWithPredicates, MapEntryNode> {
- @Override
- NodeIdentifier getIdentifier();
}
+/*
+ * Copyright (c) 2014 Cisco Systems, Inc. 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.data.api.schema;
import org.opendaylight.yangtools.concepts.Identifiable;
* Node which is normalized according to the YANG schema
* is identifiable by {@link InstanceIdentifier}.
*
- *
- * @author Tony Tkacik
+ * See subinterfaces of this interface for concretization
+ * of node.
*
* @param <K> Local identifier of node
* @param <V> Value of node
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import com.google.common.base.Optional;
/**
- *
- * @param <I> Node Identifier type
- * @param <K> Child Node Identifier type
- * @param <V> Child Node type
+ * Node which is not leaf, but has child {@link NormalizedNode}s as its valzue.
+ *
+ *
+ * NormalizedNodeContainer does not have a value, but it has a child
+ * nodes. Definition of possible and valid child nodes is introduced
+ * in subclasses of this interface.
+ *
+ * This interface should not be used directly, but rather use of of derived subinterfaces
+ * such as {@link DataContainerNode}, {@link MapNode}, {@link LeafSetNode}.
+ *
+ * @param <I>
+ * Node Identifier type
+ * @param <K>
+ * Child Node Identifier type
+ * @param <V>
+ * Child Node type
*/
public interface NormalizedNodeContainer<I extends PathArgument, K extends PathArgument, V extends NormalizedNode<? extends K, ?>>
extends NormalizedNode<I, Iterable<V>> {
@Override
I getIdentifier();
+ /**
+ * Returns immutable iteration of child nodes of this node.
+ *
+ */
@Override
Iterable<V> getValue();
/**
- *
- *
+ * Returns child node identified by provided key.
+ *
* @param child
- * @return
+ * Path argument identifying child node
+ * @return Optional with child node if child exists.
+ * {@link Optional#absent()} if child does not exists.
*/
Optional<V> getChild(K child);
}
*/
package org.opendaylight.yangtools.yang.data.api.schema;
+
+/**
+ *
+ * Leaf set node which preserves user-supplied ordering.
+ *
+ * This node represents a data instance of <code>leaf-list</code> with
+ * <code>ordered-by user;</code> substatement.
+ *
+ * Except preserving user-ordering all other semantics and behaviour is same
+ * as in {@link LeafSetNode}.
+ *
+ * @param <T> Value type of Leaf entries
+ */
public interface OrderedLeafSetNode<T> extends LeafSetNode<T>, OrderedNodeContainer<LeafSetEntryNode<T>> {
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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.data.api.schema;
+/**
+ *
+ * Map node which preserves user-supplied ordering.
+ *
+ * <p>
+ * This node represents a data instance of <code>list</code> with
+ * <code>ordered-by user;</code> substatement and <code>key</code> definition.
+ *
+ * <p>
+ * Except preserving user-ordering all other semantics and behaviour is same as
+ * in {@link MapNode}.
+ *
+ */
public interface OrderedMapNode extends MapNode, OrderedNodeContainer<MapEntryNode> {
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
+/**
+ *
+ * Normalized Node container which preserves user supplied ordering
+ * and allows addressing of child elements by positiion.
+ *
+ * @param <V>
+ */
public interface OrderedNodeContainer<V extends NormalizedNode<?, ?>> extends MixinNode, NormalizedNode<NodeIdentifier, Iterable<V>> {
+
+ /**
+ * Returns child node by position
+ *
+ * @param position Position of child node
+ * @return Child Node
+ * @throws IndexOutOfBoundsException
+ */
V getChild(int position);
+
+ /**
+ * Returns count of child nodes
+ *
+ * @return count of child nodes.
+ */
int getSize();
}
/*
- * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
- *
+ * Copyright (c) 2014 Cisco Systems, Inc. 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
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
+/**
+ * List entry node, which does not have value, but child nodes.
+ *
+ * Represents an instance of data, which schema is instance of
+ * {@link org.opendaylight.yangtools.yang.model.api.ListSchemaNode} with key undefined.
+ *
+ * This nodes itself does not contain any ordering information, user supplied
+ * ordering is preserved by parent node, which is instance of {@link UnkeyedListNode}.
+ *
+ *
+ */
public interface UnkeyedListEntryNode extends DataContainerNode<NodeIdentifier> {
}
import org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier;
+
+/**
+ *
+ * Containment node, which contains {@link UnkeyedListEntryNode} of the same type, which may
+ * be quickly retrieved using key.
+ *
+ * <p>
+ * This node maps to the <code>list</code> statement in YANG schema,
+ * which did not define <code>key</code> substatement.
+ *
+ * <p>
+ * Ordering of the elements is user-defined during construction of instance of this
+ * interface. Ordered view of elements (iteration)
+ * is provided by {@link #getValue()} call.
+ *
+ */
public interface UnkeyedListNode extends
DataContainerChild<NodeIdentifier, Iterable<UnkeyedListEntryNode>>,
OrderedNodeContainer<UnkeyedListEntryNode> {
--- /dev/null
+/**
+ *
+ * Definition of normalized YANG DOM Model
+ *
+ * Normalized DOM Model brings more direct mapping between YANG Model, DOM
+ * representation of data
+ *
+ * <h2>Normalized DOM Model</h2>
+ *
+ * <h3>Node Types</h3>
+ * <ul>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode} -
+ * Base type representing a node in a tree structure; all nodes are derived from
+ * it, it contains a leaf identifier and a value.
+ * <ul>
+ * <li>
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} -
+ * Node which contains multiple leafs; it does not have a direct representation
+ * in the YANG syntax.
+ * <ul>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ContainerNode} -
+ * Node, which represents a leaf which can occur only once per parent node; it
+ * contains multiple child leaves and maps to the <i>container</i> statement in
+ * YANG.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} -
+ * Node which represents a leaf, which can occur multiple times; a leave is
+ * uniquely identified by the value of its key. A MapEntryNode may contain
+ * multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
+ * YANG.</li>
+ * <li>
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListEntryNode}
+ * - Node which represents a leaf, which can occur multiple times; a leave is
+ * uniquely identified by the value of its key. A MapEntryNode may contain
+ * multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
+ * YANG.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} - Node
+ * which represents a leaf, which occurs mostly once per parent node, but
+ * possible values could have different types. Maps to <i>choice</i> statement.
+ * Types maps to the <i>case</i> statements for that <i>choice</i>.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode}
+ * - Node which represents a leaf, which occurs mostly once per parent node.</li>
+ * </ul>
+ * </li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} - Node
+ * which represents a leaf, which occurs mostly once per parent node. Contains
+ * simple value.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}
+ * - Node which represents a leaf, which type could occurs multiple times per
+ * parent node. Maps to to the instances of <i>leaf-list</i> in YANG.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} -
+ * Special node, which can occur only once per parent node; its leaves are
+ * LeafSetEntryNode nodes of specified type. Maps into the <i>leaf-list</i> in
+ * YANG.</li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} - Special
+ * node, which can occur only once per parent node; its leaves are MapEntryNode
+ * nodes.
+ * <ul>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedMapNode} -
+ * Special node, which can occur only once per parent node; its leaves are
+ * MapEntryNode nodes.</li>
+ * </ul>
+ * </li>
+ * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListNode} -
+ * Special node, which can occur only once per parent node; its leaves are
+ * MapEntryNode nodes.</li>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * <h3>Tree / subtree structure</h3> <h4>Grammar representation</h4>
+ *
+ * <pre>
+ * {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument}*
+ * {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.PathArgument} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier}| {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifierWithPredicates}| {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeWithValue} | {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.AugmentationIdentifier}
+ *
+ * TreeRoot = {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} = ( {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode})*
+ * ContainerDataNode = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
+ *
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier} SimpleValue
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.AugmentationIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode}
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifierWithPredicates} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
+ *
+ * // Special nodes
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}*
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode} = {@link org.opendaylight.yangtools.yang.data.api.InstanceIdentifier.NodeWithValue} SimpleValue
+ * </pre>
+ *
+ * The resulting tree organization is following:
+ *
+ * <ul>
+ * <li>(DataContainerNode)
+ * <ul>
+ * <li>(0..n) LeafNode</li>
+ * <li>(0..n) LeafSetNode
+ * <ul>
+ * <li>(0..n) LeafSetEntryNode</li>
+ * </ul>
+ * </li>
+ * <li>(0..n) ContainerNode
+ * <ul>
+ * <li>(Same as DataContainerNode)</li>
+ * </ul>
+ * </li>
+ * <li>(0..n) ContainerNode
+ * <ul>
+ * <li>(Same as DataContainerNode)</li>
+ * </ul>
+ * </li>
+ * <li>(0..n) MapNode
+ * <ul>
+ * <li>(0..n) MapEntryNode
+ * <ul>
+ * <li>(Same as DataContainerNode)</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * </li>
+ * <li>(0..n) AugmentationNode
+ * <ul>
+ * <li>(Same as DataContainerNode)</li>
+ * </ul>
+ * </li>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * <h3>Ordering of child nodes</h3>
+ *
+ * Ordering of child nodes is not enforced by this API definition, unless
+ * explicitly stated by subclasses of
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer}
+ * which marks nodes with semantic constrain to preserve user-supplied ordering.
+ * <p>
+ * Clients should not expect any specific ordering of child nodes for interfaces
+ * from this package which does not extend
+ * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer},
+ * since implementations are not required to have well-defined order, which
+ * allows for more efficient implementations. If such ordering is required by
+ * clients for serialization / debugability it SHOULD be done externally in
+ * code using these interfaces.
+ *
+ */
+package org.opendaylight.yangtools.yang.data.api.schema;
\ No newline at end of file
Code Review / yangtools.git / commitdiff