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