binding/mdsal-binding-dom-codec-api/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingCodecTree.java

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.mdsal.binding.dom.codec.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.eclipse.jdt.annotation.Nullable;
  14 import org.opendaylight.yangtools.yang.binding.Augmentation;
  15 import org.opendaylight.yangtools.yang.binding.DataObject;
  16 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  17 import org.opendaylight.yangtools.yang.binding.YangData;
  18 import org.opendaylight.yangtools.yang.common.Empty;
  19 import org.opendaylight.yangtools.yang.common.YangDataName;
  20 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  21 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
  22
  23 /**
  24  * Navigable tree representing hierarchy of Binding to Normalized Node codecs. This navigable tree is associated to
  25  * a concrete set of YANG models, represented by SchemaContext and provides access to subtree specific serialization
  26  * context.
  27  */
  28 // TODO: Add more detailed documentation
  29 public interface BindingCodecTree extends BindingDataObjectCodecTreeParent<Empty> {
  30     /**
  31      * A DTO holding a {@link CommonDataObjectCodecTreeNode} and the corresponding {@link YangInstanceIdentifier}.
  32      *
  33      * @param <T> {@link DataObject} type
  34      * @param codec A CommonDataObjectCodecTreeNode handling the translation
  35      * @param path A {@link YangInstanceIdentifier} corresponding to the backing Normalized Node
  36      */
  37     record CodecWithPath<T extends DataObject>(
  38             @NonNull CommonDataObjectCodecTreeNode<T> codec,
  39             @NonNull YangInstanceIdentifier path) {
  40         public CodecWithPath {
  41             requireNonNull(codec);
  42             requireNonNull(path);
  43         }
  44     }
  45
  46     /**
  47      * Look up the codec for specified augmentation path.
  48      *
  49      * @param <A> DataObject type
  50      * @param path Binding path
  51      * @return A {@link BindingAugmentationCodecTreeNode}
  52      * @throws NullPointerException if {@code path} is {@code null}
  53      * @throws IllegalArgumentException if the codec cannot be resolved
  54      */
  55     <A extends Augmentation<?>> @NonNull BindingAugmentationCodecTreeNode<A> getAugmentationCodec(
  56         InstanceIdentifier<A> path);
  57
  58     /**
  59      * Look up the codec for specified ordinary DataObject path.
  60      *
  61      * @param <T> DataObject type
  62      * @param path Binding path
  63      * @return A {@link BindingDataObjectCodecTreeNode}
  64      * @throws NullPointerException if {@code path} is {@code null}
  65      * @throws IllegalArgumentException if the codec cannot be resolved or refers to an Augmentation
  66      */
  67     <T extends DataObject> @NonNull BindingDataObjectCodecTreeNode<T> getDataObjectCodec(InstanceIdentifier<T> path);
  68
  69     /**
  70      * Look up the codec for specified path, constructing the {@link YangInstanceIdentifier} corresponding to it.
  71      *
  72      * @param <T> DataObject type
  73      * @param path Binding path
  74      * @return A {@link CodecWithPath}
  75      * @throws NullPointerException if {@code path} is {@code null}
  76      * @throws IllegalArgumentException if the codec cannot be resolved
  77      */
  78     <T extends DataObject> @NonNull CodecWithPath<T> getSubtreeCodecWithPath(InstanceIdentifier<T> path);
  79
  80     /**
  81      * Look up the codec for specified path.
  82      *
  83      * @param <T> DataObject type
  84      * @param path Binding path
  85      * @return A {@link BindingDataObjectCodecTreeNode}
  86      * @throws NullPointerException if {@code path} is {@code null}
  87      * @throws IllegalArgumentException if the codec cannot be resolved
  88      */
  89     <T extends DataObject> @NonNull CommonDataObjectCodecTreeNode<T> getSubtreeCodec(InstanceIdentifier<T> path);
  90
  91     /**
  92      * Look up a codec by its {@link YangInstanceIdentifier} path.
  93      *
  94      * @param path A non-empty {@link YangInstanceIdentifier}
  95      * @return A {@link BindingCodecTreeNode}
  96      * @throws NullPointerException if {@code path} is {@code null}
  97      * @throws IllegalArgumentException if {@code path} is empty
  98      */
  99     @Nullable BindingCodecTreeNode getSubtreeCodec(YangInstanceIdentifier path);
 100
 101     // FIXME: NonNull and throwing exception
 102     @Nullable BindingCodecTreeNode getSubtreeCodec(Absolute path);
 103
 104     /**
 105      * Get the {@link BindingIdentityCodec} associated with this tree.
 106      *
 107      * @return A BindingIdentityCodec instance.
 108      */
 109     @NonNull BindingIdentityCodec getIdentityCodec();
 110
 111     /**
 112      * Get the {@link BindingInstanceIdentifierCodec} associated with this tree.
 113      *
 114      * @return A BindingInstanceIdentifierCodec instance.
 115      */
 116     @NonNull BindingInstanceIdentifierCodec getInstanceIdentifierCodec();
 117
 118     /**
 119      * Get the {@link BindingYangDataCodecTreeNode} corresponding to a particular generated {@link YangData} type.
 120      *
 121      * @param <T> {@link YangData} type
 122      * @param yangDataClass Class object of {@link YangData} type
 123      * @return A {@link BindingYangDataCodecTreeNode}
 124      * @throws NullPointerException if {@code yangDataClass} is {@code null}
 125      * @throws IllegalArgumentException if the specified type is not known
 126      */
 127     <T extends YangData<T>> @NonNull BindingYangDataCodecTreeNode<T> getYangDataCodec(Class<T> yangDataClass);
 128
 129     /**
 130      * Get the {@link BindingYangDataCodecTreeNode} corresponding to a particular {@link YangDataName}.
 131      *
 132      * @param yangDataName a {@link YangDataName}
 133      * @return A {@link BindingYangDataCodecTreeNode}
 134      * @throws NullPointerException if {@code yangDataName} is {@code null}
 135      * @throws IllegalArgumentException if the specified name is not known
 136      */
 137     @NonNull BindingYangDataCodecTreeNode<?> getYangDataCodec(YangDataName yangDataName);
 138 }