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