binding/mdsal-binding-runtime-api/src/main/java/org/opendaylight/mdsal/binding/runtime/api/BindingRuntimeTypes.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, s.r.o.  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.runtime.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Optional;
  12 import java.util.Set;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.eclipse.jdt.annotation.Nullable;
  15 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
  16 import org.opendaylight.mdsal.binding.model.api.JavaTypeName;
  17 import org.opendaylight.yangtools.concepts.Immutable;
  18 import org.opendaylight.yangtools.yang.common.QName;
  19 import org.opendaylight.yangtools.yang.common.YangDataName;
  20 import org.opendaylight.yangtools.yang.model.api.EffectiveModelContextProvider;
  21 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
  22
  23 /**
  24  * The result of BindingGenerator run. Contains mapping between Types and SchemaNodes.
  25  */
  26 @Beta
  27 public interface BindingRuntimeTypes extends EffectiveModelContextProvider, RuntimeTypeContainer, Immutable {
  28     /**
  29      * Lookup {@link IdentityRuntimeType} by its QNamme.
  30      *
  31      * @param qname Identity name
  32      * @return {@link IdentityRuntimeType} or {@code null}
  33      * @throws NullPointerException if {@code qname} is {@code null}
  34      */
  35     @Nullable IdentityRuntimeType identityChild(@NonNull QName qname);
  36
  37     Optional<RuntimeType> findSchema(JavaTypeName typeName);
  38
  39     Optional<InputRuntimeType> findRpcInput(QName rpcName);
  40
  41     Optional<OutputRuntimeType> findRpcOutput(QName rpcName);
  42
  43     Optional<YangDataRuntimeType> findYangData(YangDataName templateName);
  44
  45     default @Nullable RuntimeType schemaTreeChild(final Absolute path) {
  46         final var it = path.getNodeIdentifiers().iterator();
  47         var tmp = schemaTreeChild(it.next());
  48         while (it.hasNext() && tmp instanceof RuntimeTypeContainer container) {
  49             tmp = container.schemaTreeChild(it.next());
  50         }
  51         return tmp;
  52     }
  53
  54     /**
  55      * Lookup to all {@link CaseRuntimeType}s related to a {@link ChoiceRuntimeType}. This is important when dealing
  56      * with sharing incurred by Binding Spec's reuse of constructs defined in a {@code grouping}.
  57      *
  58      * <p>
  59      * As an example, consider {@link ChoiceRuntimeType} and {@link CaseRuntimeType} relationship to
  60      * {@link GeneratedType}s in the following model:
  61      * <pre>
  62      *   <code>
  63      *     grouping grp {
  64      *       container foo {
  65      *         choice bar;
  66      *       }
  67      *     }
  68      *
  69      *     container foo {
  70      *       uses grp;
  71      *     }
  72      *
  73      *     container bar {
  74      *       uses grp;
  75      *     }
  76      *
  77      *     augment /foo/foo/bar {
  78      *       case baz
  79      *     }
  80      *
  81      *     augment /bar/foo/bar {
  82      *       case xyzzy;
  83      *     }
  84      *   </code>
  85      * </pre>
  86      * YANG view of what is valid in {@code /foo/foo/bar} differs from what is valid in {@code /bar/foo/bar}, but this
  87      * difference is not reflected in generated Java constructs. More notably, the two augments being in different
  88      * modules. Since {@code choice bar}'s is part of a reusable construct, {@code grouping one}, DataObjects' copy
  89      * builders can propagate them without translating them to the appropriate manifestation -- and they can do nothing
  90      * about that as they lack the complete view of the effective model.
  91      *
  92      * <p>
  93      * This method provides a bridge between a particular instantiation of a {@code choice} to {@link CaseRuntimeType}s
  94      * valid in all instantiations.
  95      *
  96      * @param choiceType A ChoiceRuntimeType
  97      * @return The set of {@link CaseRuntimeType}s known to this instance
  98      * @throws NullPointerException if {@code ChoiceRuntimeType} is null
  99      */
 100     @NonNull Set<CaseRuntimeType> allCaseChildren(ChoiceRuntimeType choiceType);
 101 }