org.opendaylight.yangtools.yang.binding

Class InstanceIdentifier<T extends DataObject>

java.lang.Object

org.opendaylight.yangtools.yang.binding.InstanceIdentifier<T>

All Implemented Interfaces:

Serializable, org.opendaylight.yangtools.concepts.Immutable, org.opendaylight.yangtools.concepts.MutationBehaviour<org.opendaylight.yangtools.concepts.Immutable>, org.opendaylight.yangtools.concepts.Path<InstanceIdentifier<? extends DataObject>>

Direct Known Subclasses:

KeyedInstanceIdentifier

public class InstanceIdentifier<T extends DataObject>
extends Object
implements org.opendaylight.yangtools.concepts.Path<InstanceIdentifier<? extends DataObject>>, org.opendaylight.yangtools.concepts.Immutable, Serializable

This instance identifier uniquely identifies a specific DataObject in the data tree modeled by YANG.

For Example let's say you were trying to refer to a node in inventory which was modeled in YANG as follows,

 module opendaylight-inventory {
      ....

      container nodes {
        list node {
            key "id";
            ext:context-instance "node-context";

            uses node;
        }
    }

 }
 

You can create an instance identifier as follows to get to a node with id "openflow:1": InstanceIdentifierBuilder.builder(Nodes.class).child(Node.class, new NodeKey(new NodeId("openflow:1")).build();

This would be the same as using a path like so, "/nodes/node/openflow:1" to refer to the openflow:1 node

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	InstanceIdentifier.IdentifiableItem<I extends Identifiable<T> & DataObject,T extends Identifier<I>> An IdentifiableItem represents a object that is usually present in a collection and can be identified uniquely by a key.
static interface	InstanceIdentifier.InstanceIdentifierBuilder<T extends DataObject>
static class	InstanceIdentifier.Item<T extends DataObject> An Item represents an object that probably is only one of it's kind.
static interface	InstanceIdentifier.PathArgument Path argument of InstanceIdentifier.

Method Summary

Modifier and Type	Method and Description
protected com.google.common.base.MoreObjects.ToStringHelper	addToStringAttributes(com.google.common.base.MoreObjects.ToStringHelper toStringHelper) Add class-specific toString attributes.
<N extends DataObject & Augmentation<? super T>> InstanceIdentifier<N>	augmentation(Class<N> container) Create an InstanceIdentifier for a child augmentation.
InstanceIdentifier.InstanceIdentifierBuilder<T>	builder() Create a builder rooted at this key.
static <C extends ChoiceIn<? extends DataRoot> & DataObject,N extends Identifiable<K> & ChildOf<? super C>,K extends Identifier<N>> InstanceIdentifier.InstanceIdentifierBuilder<N>	builder(Class<C> caze, Class<N> listItem, K listKey) Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an InstanceIdentifier.IdentifiableItem in a grouping used in the case statement.
static <C extends ChoiceIn<? extends DataRoot> & DataObject,T extends ChildOf<? super C>> InstanceIdentifier.InstanceIdentifierBuilder<T>	builder(Class<C> caze, Class<T> container) Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container in a grouping used in the case statement.
static <N extends Identifiable<K> & ChildOf<? extends DataRoot>,K extends Identifier<N>> InstanceIdentifier.InstanceIdentifierBuilder<N>	builder(Class<N> listItem, K listKey) Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an InstanceIdentifier.IdentifiableItem.
static <T extends ChildOf<? extends DataRoot>> InstanceIdentifier.InstanceIdentifierBuilder<T>	builder(Class<T> container) Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container.
<C extends ChoiceIn<? super T> & DataObject,N extends ChildOf<? super C>> InstanceIdentifier<N>	child(Class<C> caze, Class<N> container) Create an InstanceIdentifier for a child container.
<C extends ChoiceIn<? super T> & DataObject,K extends Identifier<N>,N extends Identifiable<K> & ChildOf<? super C>> KeyedInstanceIdentifier<N,K>	child(Class<C> caze, Class<N> listItem, K listKey) Create an InstanceIdentifier for a child list item.
<N extends ChildOf<? super T>> InstanceIdentifier<N>	child(Class<N> container) Create an InstanceIdentifier for a child container.
<N extends Identifiable<K> & ChildOf<? super T>,K extends Identifier<N>> KeyedInstanceIdentifier<N,K>	child(Class<N> listItem, K listKey) Create an InstanceIdentifier for a child list item.
boolean	contains(InstanceIdentifier<? extends DataObject> other) Check whether an identifier is contained in this identifier.
boolean	containsWildcarded(InstanceIdentifier<?> other) Check whether this instance identifier contains the other identifier after wildcard expansion.
static <T extends DataObject> InstanceIdentifier<T>	create(Class<T> type) Create an instance identifier for a very specific object type.
static InstanceIdentifier<?>	create(Iterable<? extends InstanceIdentifier.PathArgument> pathArguments) Create an instance identifier for a very specific object type.
boolean	equals(Object obj)
protected boolean	fastNonEqual(InstanceIdentifier<?> other) Perform class-specific fast checks for non-equality.
<I extends DataObject> InstanceIdentifier<I>	firstIdentifierOf(Class<I> type) Return an instance identifier trimmed at the first occurrence of a specific component type.
<N extends Identifiable<K> & DataObject,K extends Identifier<N>> K	firstKeyOf(Class<N> listItem) Return the key associated with the first component of specified type in an identifier.
Iterable<InstanceIdentifier.PathArgument>	getPathArguments() Return the path argument chain which makes up this instance identifier.
Class<T>	getTargetType() Return the type of data which this InstanceIdentifier identifies.
int	hashCode()
boolean	isWildcarded() Check whether an instance identifier contains any wildcards.
static <N extends Identifiable<K> & DataObject,K extends Identifier<N>> K	keyOf(InstanceIdentifier<N> id) Return the key associated with the last component of the specified identifier.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getTargetType

public final Class<T> getTargetType()

Return the type of data which this InstanceIdentifier identifies.

Returns:

Target type

getPathArguments

public final Iterable<InstanceIdentifier.PathArgument> getPathArguments()

Return the path argument chain which makes up this instance identifier.

Returns:

Path argument chain. Immutable and does not contain nulls.

isWildcarded

public final boolean isWildcarded()

Check whether an instance identifier contains any wildcards. A wildcard is an path argument which has a null key.

Returns:

true if any of the path arguments has a null key.

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

fastNonEqual

protected boolean fastNonEqual(InstanceIdentifier<?> other)

Perform class-specific fast checks for non-equality. This allows subclasses to avoid iterating over the pathArguments by performing quick checks on their specific fields.

Parameters:

other - The other identifier, guaranteed to be the same class

Returns:

true if the other identifier cannot be equal to this one.

toString

public final String toString()

Overrides:

toString in class Object

addToStringAttributes

protected com.google.common.base.MoreObjects.ToStringHelper addToStringAttributes(com.google.common.base.MoreObjects.ToStringHelper toStringHelper)

Add class-specific toString attributes.

Parameters:

toStringHelper - ToStringHelper instance

Returns:

ToStringHelper instance which was passed in

firstIdentifierOf

public final <I extends DataObject> InstanceIdentifier<I> firstIdentifierOf(Class<I> type)

Return an instance identifier trimmed at the first occurrence of a specific component type.

For example let's say an instance identifier was built like so,

      identifier = InstanceIdentifierBuilder.builder(Nodes.class).child(Node.class,
                   new NodeKey(new NodeId("openflow:1")).build();
 

And you wanted to obtain the Instance identifier which represented Nodes you would do it like so,

      identifier.firstIdentifierOf(Nodes.class)
 

Parameters:

type - component type

Returns:

trimmed instance identifier, or null if the component type is not present.

firstKeyOf

public final <N extends Identifiable<K> & DataObject,K extends Identifier<N>> K firstKeyOf(Class<N> listItem)

Return the key associated with the first component of specified type in an identifier.

Parameters:

listItem - component type

Returns:

key associated with the component, or null if the component type is not present.

contains

public final boolean contains(InstanceIdentifier<? extends DataObject> other)

Check whether an identifier is contained in this identifier. This is a strict subtree check, which requires all PathArguments to match exactly.

The contains method checks if the other identifier is fully contained within the current identifier. It does this by looking at only the types of the path arguments and not by comparing the path arguments themselves.

To illustrate here is an example which explains the working of this API. Let's say you have two instance identifiers as follows: this = /nodes/node/openflow:1 other = /nodes/node/openflow:2 then this.contains(other) will return false.

Specified by:

contains in interface org.opendaylight.yangtools.concepts.Path<InstanceIdentifier<? extends DataObject>>

Parameters:

other - Potentially-container instance identifier

Returns:

True if the specified identifier is contained in this identifier.

containsWildcarded

public final boolean containsWildcarded(InstanceIdentifier<?> other)

Check whether this instance identifier contains the other identifier after wildcard expansion. This is similar to contains(InstanceIdentifier), with the exception that a wildcards are assumed to match the their non-wildcarded PathArgument counterpart.

Parameters:

other - Identifier which should be checked for inclusion.

Returns:

true if this identifier contains the other object

child

public final <N extends ChildOf<? super T>> InstanceIdentifier<N> child(Class<N> container)

Create an InstanceIdentifier for a child container. This method is a more efficient equivalent to builder().child(container).build().

Type Parameters:

N - Container type

Parameters:

container - Container to append

Returns:

An InstanceIdentifier.

Throws:

NullPointerException - if container is null

child

public final <N extends Identifiable<K> & ChildOf<? super T>,K extends Identifier<N>> KeyedInstanceIdentifier<N,K> child(Class<N> listItem,
                                                                                                                         K listKey)

Create an InstanceIdentifier for a child list item. This method is a more efficient equivalent to builder().child(listItem, listKey).build().

Type Parameters:

N - List type

K - Key type

Parameters:

listItem - List to append

listKey - List key

Returns:

An InstanceIdentifier.

Throws:

NullPointerException - if any argument is null

child

public final <C extends ChoiceIn<? super T> & DataObject,N extends ChildOf<? super C>> InstanceIdentifier<N> child(Class<C> caze,
                                                                                                                   Class<N> container)

Create an InstanceIdentifier for a child container. This method is a more efficient equivalent to builder().child(caze, container).build().

Type Parameters:

C - Case type

N - Container type

Parameters:

caze - Choice case class

container - Container to append

Returns:

An InstanceIdentifier.

Throws:

NullPointerException - if any argument is null

child

public final <C extends ChoiceIn<? super T> & DataObject,K extends Identifier<N>,N extends Identifiable<K> & ChildOf<? super C>> KeyedInstanceIdentifier<N,K> child(Class<C> caze,
                                                                                                                                                                    Class<N> listItem,
                                                                                                                                                                    K listKey)

Create an InstanceIdentifier for a child list item. This method is a more efficient equivalent to builder().child(caze, listItem, listKey).build().

Type Parameters:

C - Case type

N - List type

K - Key type

Parameters:

caze - Choice case class

listItem - List to append

listKey - List key

Returns:

An InstanceIdentifier.

Throws:

NullPointerException - if any argument is null

augmentation

public final <N extends DataObject & Augmentation<? super T>> InstanceIdentifier<N> augmentation(Class<N> container)

Create an InstanceIdentifier for a child augmentation. This method is a more efficient equivalent to builder().augmentation(container).build().

Type Parameters:

N - Container type

Parameters:

container - Container to append

Returns:

An InstanceIdentifier.

Throws:

NullPointerException - if container is null

builder

public InstanceIdentifier.InstanceIdentifierBuilder<T> builder()

Create a builder rooted at this key.

Returns:

A builder instance

builder

public static <T extends ChildOf<? extends DataRoot>> InstanceIdentifier.InstanceIdentifierBuilder<T> builder(Class<T> container)

Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container.

Type Parameters:

T - Type of the container

Parameters:

container - Base container

Returns:

A new InstanceIdentifier.InstanceIdentifierBuilder

Throws:

NullPointerException - if container is null

builder

public static <C extends ChoiceIn<? extends DataRoot> & DataObject,T extends ChildOf<? super C>> InstanceIdentifier.InstanceIdentifierBuilder<T> builder(Class<C> caze,
                                                                                                                                                         Class<T> container)

Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier as specified by container in a grouping used in the case statement.

Type Parameters:

C - Case type

T - Type of the container

Parameters:

caze - Choice case class

container - Base container

Returns:

A new InstanceIdentifier.InstanceIdentifierBuilder

Throws:

NullPointerException - if any argument is null

builder

public static <N extends Identifiable<K> & ChildOf<? extends DataRoot>,K extends Identifier<N>> InstanceIdentifier.InstanceIdentifierBuilder<N> builder(Class<N> listItem,
                                                                                                                                                        K listKey)

Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an InstanceIdentifier.IdentifiableItem.

Type Parameters:

N - List type

K - List key

Parameters:

listItem - list item class

listKey - key value

Returns:

A new InstanceIdentifier.InstanceIdentifierBuilder

Throws:

NullPointerException - if any argument is null

builder

public static <C extends ChoiceIn<? extends DataRoot> & DataObject,N extends Identifiable<K> & ChildOf<? super C>,K extends Identifier<N>> InstanceIdentifier.InstanceIdentifierBuilder<N> builder(Class<C> caze,
                                                                                                                                                                                                   Class<N> listItem,
                                                                                                                                                                                                   K listKey)

Create an InstanceIdentifierBuilder for a specific type of InstanceIdentifier which represents an InstanceIdentifier.IdentifiableItem in a grouping used in the case statement.

Type Parameters:

C - Case type

N - List type

K - List key

Parameters:

caze - Choice case class

listItem - list item class

listKey - key value

Returns:

A new InstanceIdentifier.InstanceIdentifierBuilder

Throws:

NullPointerException - if any argument is null

create

public static InstanceIdentifier<?> create(Iterable<? extends InstanceIdentifier.PathArgument> pathArguments)

Create an instance identifier for a very specific object type.

Example:

  List<PathArgument> path = Arrays.asList(new Item(Nodes.class))
  new InstanceIdentifier(path);
 

Parameters:

pathArguments - The path to a specific node in the data tree

Returns:

InstanceIdentifier instance

Throws:

IllegalArgumentException - if pathArguments is empty or contains a null element.

create

public static <T extends DataObject> InstanceIdentifier<T> create(Class<T> type)

Create an instance identifier for a very specific object type.

For example

      new InstanceIdentifier(Nodes.class)
 

would create an InstanceIdentifier for an object of type Nodes

Parameters:

type - The type of the object which this instance identifier represents

Returns:

InstanceIdentifier instance

keyOf

public static <N extends Identifiable<K> & DataObject,K extends Identifier<N>> K keyOf(InstanceIdentifier<N> id)

Return the key associated with the last component of the specified identifier.

Parameters:

id - instance identifier

Returns:

key associated with the last component

Throws:

IllegalArgumentException - if the supplied identifier type cannot have a key.

NullPointerException - if id is null.