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<YangDataRuntimeType> findYangData(YangDataName templateName);
  40
  41     default @Nullable RuntimeType schemaTreeChild(final Absolute path) {
  42         final var it = path.getNodeIdentifiers().iterator();
  43         var tmp = schemaTreeChild(it.next());
  44         while (it.hasNext() && tmp instanceof RuntimeTypeContainer container) {
  45             tmp = container.schemaTreeChild(it.next());
  46         }
  47         return tmp;
  48     }
  49
  50     /**
  51      * Lookup to all {@link CaseRuntimeType}s related to a {@link ChoiceRuntimeType}. This is important when dealing
  52      * with sharing incurred by Binding Spec's reuse of constructs defined in a {@code grouping}.
  53      *
  54      * <p>
  55      * As an example, consider {@link ChoiceRuntimeType} and {@link CaseRuntimeType} relationship to
  56      * {@link GeneratedType}s in the following model:
  57      * <pre>
  58      *   <code>
  59      *     grouping grp {
  60      *       container foo {
  61      *         choice bar;
  62      *       }
  63      *     }
  64      *
  65      *     container foo {
  66      *       uses grp;
  67      *     }
  68      *
  69      *     container bar {
  70      *       uses grp;
  71      *     }
  72      *
  73      *     augment /foo/foo/bar {
  74      *       case baz
  75      *     }
  76      *
  77      *     augment /bar/foo/bar {
  78      *       case xyzzy;
  79      *     }
  80      *   </code>
  81      * </pre>
  82      * YANG view of what is valid in {@code /foo/foo/bar} differs from what is valid in {@code /bar/foo/bar}, but this
  83      * difference is not reflected in generated Java constructs. More notably, the two augments being in different
  84      * modules. Since {@code choice bar}'s is part of a reusable construct, {@code grouping one}, DataObjects' copy
  85      * builders can propagate them without translating them to the appropriate manifestation -- and they can do nothing
  86      * about that as they lack the complete view of the effective model.
  87      *
  88      * <p>
  89      * This method provides a bridge between a particular instantiation of a {@code choice} to {@link CaseRuntimeType}s
  90      * valid in all instantiations.
  91      *
  92      * @param choiceType A ChoiceRuntimeType
  93      * @return The set of {@link CaseRuntimeType}s known to this instance
  94      * @throws NullPointerException if {@code ChoiceRuntimeType} is null
  95      */
  96     @NonNull Set<CaseRuntimeType> allCaseChildren(ChoiceRuntimeType choiceType);
  97 }