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