binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingCodecTreeNode.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 com.google.common.annotations.Beta;
  11 import com.google.common.base.Optional;
  12 import com.google.common.collect.ImmutableCollection;
  13 import java.util.List;
  14 import javax.annotation.Nonnull;
  15 import javax.annotation.Nullable;
  16 import org.opendaylight.yangtools.yang.binding.BindingStreamEventWriter;
  17 import org.opendaylight.yangtools.yang.binding.DataObject;
  18 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  20 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
  21
  22 /**
  23  * Subtree codec specific to model subtree between Java Binding and
  24  * NormalizedNode.
  25  *
  26  */
  27 @Beta
  28 public interface BindingCodecTreeNode<T extends DataObject> extends BindingNormalizedNodeCodec<T>,
  29         org.opendaylight.yangtools.binding.data.codec.api.BindingCodecTreeNode<T> {
  30
  31     /**
  32      *
  33      * Returns binding class of interface which represents API of current
  34      * schema node.
  35      *
  36      * The result is same as invoking {@link DataObject#getImplementedInterface()}
  37      * on instance of data.
  38      *
  39      * @return interface which defines API of binding representation of data.
  40      */
  41     @Override
  42     @Nonnull
  43     Class<T> getBindingClass();
  44
  45     /**
  46      *
  47      * Returns child context as if it was walked by
  48      * {@link BindingStreamEventWriter}. This means that to enter case, one must
  49      * issue getChild(ChoiceClass).getChild(CaseClass).
  50      *
  51      * @param childClass Child class by Biding Stream navigation
  52      * @return Context of child
  53      * @throws IllegalArgumentException
  54      *             If supplied child class is not valid in specified context.
  55      */
  56     @Override
  57     @Nonnull
  58     <E extends DataObject> BindingCodecTreeNode<E> streamChild(@Nonnull Class<E> childClass);
  59
  60     /**
  61      *
  62      * Returns child context as if it was walked by
  63      * {@link BindingStreamEventWriter}. This means that to enter case, one must
  64      * issue getChild(ChoiceClass).getChild(CaseClass).
  65      *
  66      * This method differs from {@link #streamChild(Class)}, that is less
  67      * stricter for interfaces representing augmentation and cases, that
  68      * may return {@link BindingCodecTreeNode} even if augmentation interface
  69      * containing same data was supplied and does not represent augmentation
  70      * of this node.
  71      *
  72      * @param childClass
  73      * @return Context of child or Optional absent is supplied class is not
  74      *         applicable in context.
  75      */
  76     @Override
  77     <E extends DataObject> Optional<? extends BindingCodecTreeNode<E>> possibleStreamChild(@Nonnull Class<E> childClass);
  78
  79     /**
  80      * Returns nested node context using supplied YANG Instance Identifier
  81      *
  82      * @param child
  83      *            Yang Instance Identifier Argument
  84      * @return Context of child
  85      * @throws IllegalArgumentException
  86      *             If supplied argument does not represent valid child.
  87      */
  88     @Override
  89     @Nonnull
  90     BindingCodecTreeNode<?> yangPathArgumentChild(@Nonnull YangInstanceIdentifier.PathArgument child);
  91
  92     /**
  93      * Returns nested node context using supplied Binding Instance Identifier
  94      * and adds YANG instance identifiers to supplied list.
  95      *
  96      * @param arg
  97      *            Binding Instance Identifier Argument
  98      * @param builder
  99      *            Mutable instance of list, which is appended by YangInstanceIdentifiers
 100      *            as tree is walked. Use null if such side-product is not needed.
 101      * @return Context of child
 102      * @throws IllegalArgumentException
 103      *             If supplied argument does not represent valid child.
 104      */
 105     @Override
 106     @Nonnull
 107     BindingCodecTreeNode<?> bindingPathArgumentChild(@Nonnull InstanceIdentifier.PathArgument arg,
 108             @Nullable List<YangInstanceIdentifier.PathArgument> builder);
 109
 110     /**
 111      *
 112      * Returns codec which uses caches serialization / deserialization results
 113      *
 114      * Caching may introduce performance penalty to serialization / deserialization
 115      * but may decrease use of heap for repetitive objects.
 116      *
 117      *
 118      * @param cacheSpecifier Set of objects, for which cache may be in place
 119      * @return Codec whihc uses cache for serialization / deserialization.
 120      */
 121     @Override
 122     @Nonnull
 123     BindingNormalizedNodeCachingCodec<T> createCachingCodec(@Nonnull
 124             ImmutableCollection<Class<? extends DataObject>> cacheSpecifier);
 125
 126     @Override
 127     @Beta
 128     void writeAsNormalizedNode(T data, NormalizedNodeStreamWriter writer);
 129
 130     /**
 131      * Serializes path argument for current node.
 132      *
 133      * @param arg Binding Path Argument, may be null if Binding Instance Identifier does not have
 134      *        representation for current node (e.g. choice or case).
 135      * @return Yang Path Argument, may be null if Yang Instance Identifier does not have
 136      *         representation for current node (e.g. case).
 137      * @throws IllegalArgumentException If supplied {@code arg} is not valid.
 138      */
 139     @Override
 140     @Beta
 141     @Nullable YangInstanceIdentifier.PathArgument serializePathArgument(@Nullable InstanceIdentifier.PathArgument arg);
 142
 143     /**
 144      * Deserializes path argument for current node.
 145      *
 146      * @param arg Yang Path Argument, may be null if Yang Instance Identifier does not have
 147      *         representation for current node (e.g. case).
 148      * @return Binding Path Argument, may be null if Binding Instance Identifier does not have
 149      *        representation for current node (e.g. choice or case).
 150      * @throws IllegalArgumentException If supplied {@code arg} is not valid.
 151      */
 152     @Override
 153     @Beta
 154     @Nullable InstanceIdentifier.PathArgument deserializePathArgument(@Nullable YangInstanceIdentifier.PathArgument arg);
 155
 156     @Override
 157     Object getSchema();
 158 }