Package org.opendaylight.yangtools.binding

Interface DataObjectReference<T extends DataObject>

Type Parameters:

T - type of DataObject held in the last step.

All Superinterfaces:

Immutable, Serializable

All Known Subinterfaces:

DataObjectIdentifier<T>, DataObjectIdentifier.WithKey<T,K>, DataObjectReference.WithKey<T,K>

All Known Implementing Classes:

AbstractDataObjectReference, DataObjectIdentifierImpl, DataObjectIdentifierWithKey, DataObjectReferenceImpl, DataObjectReferenceWithKey, InstanceIdentifier, KeyedInstanceIdentifier

public sealed interface DataObjectReference<T extends DataObject>
extends Immutable, Serializable
permits DataObjectIdentifier<T>, DataObjectReference.WithKey<T,K>, AbstractDataObjectReference<T,S>

A reference to a DataObject with semantics partially overlapping with to YANG instance-identifier.

While this indirection is not something defined in YANG, this class hierarchy arises naturally from the Binding specification's Java footprint, which uses DataObject as the baseline self-sufficient addressable construct. This means users can use a KeyAware class without specifying the corresponding key -- resulting in an InexactDataObjectStep.

There are two kinds of a reference based on their treatment of such a InexactDataObjectStep:

1. DataObjectIdentifier, which accepts only ExactDataObjectSteps and represents a BindingInstanceIdentifier pointing to a DataObject
2. DataObjectReference, which accepts any DataObjectStep and represents path-based matching criteria for one or more DataObjectIdentifiers based on InexactDataObjectStep.matches(DataObjectStep).

An explicit conversion to DataObjectIdentifier can be attempted via toIdentifier() method.

The legacy InstanceIdentifier is implements the second kind via its class hierarchy, but indicates its compliance via isExact() method. Any DataObjectReference can be converted into an InstanceIdentifier via the toLegacy() method.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	DataObjectReference.Builder<T extends DataObject>	A builder of DataObjectReference objects.
static interface	DataObjectReference.WithKey<T extends EntryObject<T,K>,K extends Key<T>>	A DataObjectReference pointing to a EntryObject.

Method Summary

Modifier and Type	Method	Description
default @NonNull DataObjectReference.Builder<T>	builder()	Deprecated. Use toBuilder() instead.
static <C extends ChoiceIn<? extends DataRoot<?>> & DataObject, N extends EntryObject<N, K> & ChildOf<? super C>, K extends Key<N>> @NonNull DataObjectReference.Builder.WithKey<N,K>	builder(@NonNull Class<C> caze, @NonNull Class<N> listItem, @NonNull K listKey)
static <C extends ChoiceIn<? extends DataRoot<?>> & DataObject, T extends ChildOf<? super C>> @NonNull DataObjectReference.Builder<T>	builder(@NonNull Class<C> caze, @NonNull Class<T> container)
static <T extends ChildOf<? extends DataRoot<?>>> @NonNull DataObjectReference.Builder<T>	builder(@NonNull Class<T> container)
static <N extends EntryObject<N, K> & ChildOf<? extends DataRoot<?>>, K extends Key<N>> @NonNull DataObjectReference.Builder.WithKey<N,K>	builder(Class<N> listItem, K listKey)
static <R extends DataRoot<R>, N extends EntryObject<N, K> & ChildOf<? super R>, K extends Key<N>> @NonNull DataObjectReference.Builder.WithKey<N,K>	builderOfInherited(@NonNull Class<R> root, @NonNull Class<N> listItem, @NonNull K listKey)
static <R extends DataRoot<R>, T extends ChildOf<? super R>> @NonNull DataObjectReference.Builder<T>	builderOfInherited(@NonNull Class<R> root, @NonNull Class<T> container)
static <R extends DataRoot<R>, C extends ChoiceIn<? super R> & DataObject, N extends EntryObject<N, K> & ChildOf<? super C>, K extends Key<N>> @NonNull DataObjectReference.Builder.WithKey<N,K>	builderOfInherited(Class<R> root, Class<C> caze, Class<N> listItem, K listKey)
static <R extends DataRoot<R>, C extends ChoiceIn<? super R> & DataObject, T extends ChildOf<? super C>> @NonNull DataObjectReference.Builder<T>	builderOfInherited(Class<R> root, Class<C> caze, Class<T> container)
default <E extends EntryObject<E, K>, K extends Key<E>> Optional<K>	findFirstKeyOf(Class<@NonNull E> listItem)	Returns an Optional containing the Key associated with the first component of specified type in this reference.
<E extends EntryObject<E, K>, K extends Key<E>> @Nullable K	firstKeyOf(Class<@NonNull E> listItem)	Returns the Key associated with the first component of specified type in this reference.
default <E extends EntryObject<E, K>, K extends Key<E>> @NonNull K	getFirstKeyOf(Class<@NonNull E> listItem)	Returns the Key associated with the first component of specified type in this reference, throwing NoSuchElementException if no match is found.
default @NonNull Iterable<? extends @NonNull DataObjectStep<?>>	getPathArguments()	Deprecated. Use steps() instead.
default boolean	isExact()	Returns true if this reference is composed solely of ExactDataObjectSteps.
default boolean	isWildcarded()	Deprecated. Use negated result of isExact() instead
@NonNull DataObjectStep<T>	lastStep()	Return the last step of this reference.
static @NonNull DataObjectReference<?>	ofUnsafeSteps(ImmutableList<? extends @NonNull DataObjectStep<?>> steps)
static @NonNull DataObjectReference<?>	ofUnsafeSteps(Iterable<? extends @NonNull DataObjectStep<?>> steps)
static @NonNull DataObjectReference<?>	ofUnsafeSteps(List<? extends @NonNull DataObjectStep<?>> steps)
@NonNull Iterable<? extends @NonNull DataObjectStep<?>>	steps()	Return the steps of this reference.
@NonNull DataObjectReference.Builder<T>	toBuilder()	Create a new DataObjectReference.Builder initialized to produce a reference equal to this one.
@NonNull DataObjectIdentifier<T>	toIdentifier()	Return a DataObjectIdentifier view of this reference, if possible.
default @NonNull InstanceIdentifier<T>	toLegacy()	Return a legacy InstanceIdentifier for this reference.

Method Details

builder

@Deprecated(since="14.0.0")
default @NonNull DataObjectReference.Builder<T> builder()

Deprecated.

Use toBuilder() instead.

Create a new DataObjectReference.Builder initialized to produce a reference equal to this one.

Returns:

A builder instance

builder

static <T extends ChildOf<? extends DataRoot<?>>>
@NonNull DataObjectReference.Builder<T> builder(@NonNull Class<T> container)

builder

static <C extends ChoiceIn<? extends DataRoot<?>> & DataObject,
T extends ChildOf<? super C>>
@NonNull DataObjectReference.Builder<T> builder(@NonNull Class<C> caze,
 @NonNull Class<T> container)

builder

static <N extends EntryObject<N,
K> & ChildOf<? extends DataRoot<?>>,
K extends Key<N>>
@NonNull DataObjectReference.Builder.WithKey<N,K> builder(Class<N> listItem,
 K listKey)

builder

static <C extends ChoiceIn<? extends DataRoot<?>> & DataObject,
N extends EntryObject<N,
K> & ChildOf<? super C>,
K extends Key<N>>
@NonNull DataObjectReference.Builder.WithKey<N,K> builder(@NonNull Class<C> caze,
 @NonNull Class<N> listItem,
 @NonNull K listKey)

builderOfInherited

static <R extends DataRoot<R>,
T extends ChildOf<? super R>>
@NonNull DataObjectReference.Builder<T> builderOfInherited(@NonNull Class<R> root,
 @NonNull Class<T> container)

builderOfInherited

static <R extends DataRoot<R>,
C extends ChoiceIn<? super R> & DataObject,
T extends ChildOf<? super C>>
@NonNull DataObjectReference.Builder<T> builderOfInherited(Class<R> root,
 Class<C> caze,
 Class<T> container)

builderOfInherited

static <R extends DataRoot<R>,
N extends EntryObject<N,
K> & ChildOf<? super R>,
K extends Key<N>>
@NonNull DataObjectReference.Builder.WithKey<N,K> builderOfInherited(@NonNull Class<R> root,
 @NonNull Class<N> listItem,
 @NonNull K listKey)

builderOfInherited

static <R extends DataRoot<R>,
C extends ChoiceIn<? super R> & DataObject,
N extends EntryObject<N,
K> & ChildOf<? super C>,
K extends Key<N>>
@NonNull DataObjectReference.Builder.WithKey<N,K> builderOfInherited(Class<R> root,
 Class<C> caze,
 Class<N> listItem,
 K listKey)

ofUnsafeSteps

static @NonNull DataObjectReference<?> ofUnsafeSteps(Iterable<? extends @NonNull DataObjectStep<?>> steps)

ofUnsafeSteps

static @NonNull DataObjectReference<?> ofUnsafeSteps(List<? extends @NonNull DataObjectStep<?>> steps)

ofUnsafeSteps

static @NonNull DataObjectReference<?> ofUnsafeSteps(ImmutableList<? extends @NonNull DataObjectStep<?>> steps)

steps

@NonNull Iterable<? extends @NonNull DataObjectStep<?>> steps()

Return the steps of this reference. Returned Iterable does not support removals and contains one or more non-null items.

Returns:

the steps of this reference

lastStep

@NonNull DataObjectStep<T> lastStep()

Return the last step of this reference.

Returns:

the last step

toBuilder

@NonNull DataObjectReference.Builder<T> toBuilder()

Create a new DataObjectReference.Builder initialized to produce a reference equal to this one.

Returns:

A builder instance

toIdentifier

@NonNull DataObjectIdentifier<T> toIdentifier()

Return a DataObjectIdentifier view of this reference, if possible.

Returns:

A DataObjectIdentifier

Throws:

UnsupportedOperationException - if this reference is not compatible with DataObjectIdentifier

isExact

default boolean isExact()

Returns true if this reference is composed solely of ExactDataObjectSteps.

Returns:

true if this reference is composed solely of ExactDataObjectSteps

Implementation Note:

The default implementation returns false to simplify implementation hierarchy.

toLegacy

default @NonNull InstanceIdentifier<T> toLegacy()

Return a legacy InstanceIdentifier for this reference.

Returns:

An InstanceIdentifier.

getPathArguments

@Deprecated(since="14.0.0")
default @NonNull Iterable<? extends @NonNull DataObjectStep<?>> getPathArguments()

Deprecated.

Use steps() instead.

Return the steps of this reference. Returned Iterable does not support removals and contains one or more non-null ite,s.

Returns:

the steps of this reference

isWildcarded

@Deprecated(since="14.0.0")
default boolean isWildcarded()

Deprecated.

Use negated result of isExact() instead

Returns true if this reference contains an InexactDataObjectSteps.

Returns:

true if this reference contains an InexactDataObjectStep

Implementation Requirements:

The default implementation returns true to simplify implementation hierarchy.

firstKeyOf

<E extends EntryObject<E,
K>,
K extends Key<E>>
@Nullable K firstKeyOf(Class<@NonNull E> listItem)

Returns the Key associated with the first component of specified type in this reference.

Type Parameters:

E - entry type

K - key type

Parameters:

listItem - entry type class

Returns:

the Key associated with the component, or {code null} if the component type is not present

Throws:

NullPointerException - if listItem is null

findFirstKeyOf

default <E extends EntryObject<E,
K>,
K extends Key<E>>
Optional<K> findFirstKeyOf(Class<@NonNull E> listItem)

Returns an Optional containing the Key associated with the first component of specified type in this reference.

Type Parameters:

E - entry type

K - key type

Parameters:

listItem - entry type class

Returns:

an optional Key

Throws:

NullPointerException - if listItem is null

getFirstKeyOf

default <E extends EntryObject<E,
K>,
K extends Key<E>>
@NonNull K getFirstKeyOf(Class<@NonNull E> listItem)

Returns the Key associated with the first component of specified type in this reference, throwing NoSuchElementException if no match is found.

Type Parameters:

E - entry type

K - key type

Parameters:

listItem - entry type class

Returns:

the Key associated with the component

Throws:

NullPointerException - if listItem is null

NoSuchElementException - if the component type is not present