binding2/mdsal-binding2-dom-codec/src/main/java/org/opendaylight/mdsal/binding/javav2/dom/codec/api/BindingTreeNodeCodec.java

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