binding/mdsal-binding-dom-codec/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingDataObjectCodecTreeNode.java

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