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.collect.ImmutableCollection;
  12 import java.util.List;
  13 import java.util.Optional;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.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 Class<T> getBindingClass();
  36
  37     /**
  38      * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
  39      * one must issue getChild(ChoiceClass).getChild(CaseClass).
  40      *
  41      * @param childClass Child class by Biding Stream navigation
  42      * @return Context of child
  43      * @throws IllegalArgumentException
  44      *             If supplied child class is not valid in specified context.
  45      */
  46     // FIXME: this may return null in some implementations...
  47     <E extends DataObject> @NonNull BindingCodecTreeNode<E> streamChild(@NonNull Class<E> childClass);
  48
  49     /**
  50      * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
  51      * one must issue getChild(ChoiceClass).getChild(CaseClass).
  52      *
  53      * <p>
  54      * This method differs from {@link #streamChild(Class)}, that is less strict for interfaces representing
  55      * augmentation and cases, that may return {@link BindingCodecTreeNode} even if augmentation interface containing
  56      * same data was supplied and does not represent augmentation of this node.
  57      *
  58      * @param childClass
  59      * @return Context of child or Optional.empty is supplied class is not
  60      *         applicable in context.
  61      */
  62     <E extends DataObject> Optional<? extends BindingCodecTreeNode<E>> possibleStreamChild(
  63             @NonNull Class<E> childClass);
  64
  65     /**
  66      * Returns nested node context using supplied YANG Instance Identifier.
  67      *
  68      * @param child
  69      *            Yang Instance Identifier Argument
  70      * @return Context of child
  71      * @throws IllegalArgumentException
  72      *             If supplied argument does not represent valid child.
  73      */
  74     @NonNull BindingCodecTreeNode<?> yangPathArgumentChild(YangInstanceIdentifier.@NonNull PathArgument child);
  75
  76     /**
  77      * Returns nested node context using supplied Binding Instance Identifier and adds YANG instance identifiers to
  78      * the supplied list.
  79      *
  80      * @param arg
  81      *            Binding Instance Identifier Argument
  82      * @param builder
  83      *            Mutable instance of list, which is appended by YangInstanceIdentifiers
  84      *            as tree is walked. Use null if such side-product is not needed.
  85      * @return Context of child
  86      * @throws IllegalArgumentException
  87      *             If supplied argument does not represent valid child.
  88      */
  89     @NonNull BindingCodecTreeNode<?> bindingPathArgumentChild(InstanceIdentifier.@NonNull PathArgument arg,
  90             @Nullable List<YangInstanceIdentifier.PathArgument> builder);
  91
  92     /**
  93      * Returns codec which uses caches serialization / deserialization results.
  94      *
  95      * <p>
  96      * Caching may introduce performance penalty to serialization / deserialization
  97      * but may decrease use of heap for repetitive objects.
  98      *
  99      * @param cacheSpecifier Set of objects, for which cache may be in place
 100      * @return Codec whihc uses cache for serialization / deserialization.
 101      */
 102     @NonNull BindingNormalizedNodeCachingCodec<T> createCachingCodec(
 103             @NonNull ImmutableCollection<Class<? extends DataObject>> cacheSpecifier);
 104
 105     @Beta
 106     void writeAsNormalizedNode(T data, NormalizedNodeStreamWriter writer);
 107
 108     /**
 109      * Serializes path argument for current node.
 110      *
 111      * @param arg Binding Path Argument, may be null if Binding Instance Identifier does not have
 112      *        representation for current node (e.g. choice or case).
 113      * @return Yang Path Argument, may be null if Yang Instance Identifier does not have
 114      *         representation for current node (e.g. case).
 115      * @throws IllegalArgumentException If supplied {@code arg} is not valid.
 116      */
 117     @Beta
 118     YangInstanceIdentifier.@Nullable PathArgument serializePathArgument(InstanceIdentifier.@Nullable PathArgument arg);
 119
 120     /**
 121      * Deserializes path argument for current node.
 122      *
 123      * @param arg Yang Path Argument, may be null if Yang Instance Identifier does not have
 124      *         representation for current node (e.g. case).
 125      * @return Binding Path Argument, may be null if Binding Instance Identifier does not have
 126      *        representation for current node (e.g. choice or case).
 127      * @throws IllegalArgumentException If supplied {@code arg} is not valid.
 128      */
 129     @Beta
 130     InstanceIdentifier.@Nullable PathArgument deserializePathArgument(
 131             YangInstanceIdentifier.@Nullable PathArgument arg);
 132
 133     /**
 134      * Return the schema node associated with this node.
 135      *
 136      * @return A schema node.
 137      */
 138     @NonNull WithStatus getSchema();
 139
 140     /**
 141      * Return a summary of addressability of potential children. Binding specification does not allow all DOM tree
 142      * elements to be directly addressed, which means some recursive tree operations, like data tree changes do not
 143      * have a one-to-one mapping from DOM to binding in all cases. This method provides an optimization hint to guide
 144      * translation of data structures, allowing for fast paths when all children are known to either be addressable
 145      * or non-addressable.
 146      *
 147      * @return Summary children addressability.
 148      */
 149     @NonNull ChildAddressabilitySummary getChildAddressabilitySummary();
 150
 151     /**
 152      * Enumeration of possible addressability attribute of all children.
 153      */
 154     enum ChildAddressabilitySummary {
 155         /**
 156          * All children are addressable.
 157          */
 158         ADDRESSABLE,
 159         /**
 160          * All children are non-addressable, including the case when this node does not have any children.
 161          */
 162         UNADDRESSABLE,
 163         /**
 164          * Mixed children, some are addressable and some are not.
 165          */
 166         MIXED
 167     }
 168 }