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

   1 /*
   2  * Copyright (c) 2021 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.runtime.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.util.Collection;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.eclipse.jdt.annotation.Nullable;
  14 import org.opendaylight.mdsal.binding.model.api.JavaTypeName;
  15 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
  16
  17 /**
  18  * A {@link RuntimeType} associated with a {@code choice} statement.
  19  */
  20 @Beta
  21 public interface ChoiceRuntimeType extends CompositeRuntimeType, DataRuntimeType {
  22     @Override
  23     ChoiceEffectiveStatement statement();
  24
  25     /**
  26      * Returns resolved {@link CaseRuntimeType} for specified binding class name.
  27      *
  28      * @param typeName Binding class name
  29      * @return {@link CaseRuntimeType}, or null if absent
  30      * @throws NullPointerException if {@code typeName} is null
  31      */
  32     @Nullable CaseRuntimeType bindingCaseChild(JavaTypeName typeName);
  33
  34     /**
  35      * Return the runtime type for the original manifestation of this type's {@code choice} statement.
  36      * Returns {@code null} if this type is the original.
  37      *
  38      * @return Original manifestatation, or {@code null} if this is the original manifestation.
  39      */
  40     @Nullable ChoiceRuntimeType originalType();
  41
  42     /**
  43      * Return all {@link CaseRuntimeType} valid at this type's statement.
  44      *
  45      * @return Valid {@link CaseRuntimeType}s
  46      */
  47     @NonNull Collection<CaseRuntimeType> validCaseChildren();
  48
  49     /**
  50      * Return any additional {@link CaseRuntimeType}s which may be encountered when dealing with DataObjects supported
  51      * by this type. These are not strictly valid in YANG view of modeled data, but may have potentially-equivalent
  52      * representation, such as in the following case:
  53      * <pre>
  54      *   <code>
  55      *     grouping one {
  56      *       container foo {
  57      *         choice bar;
  58      *       }
  59      *     }
  60      *
  61      *     container foo {
  62      *       uses grp;
  63      *     }
  64      *
  65      *     container bar {
  66      *       uses grp;
  67      *     }
  68      *
  69      *     augment /foo/foo/bar {
  70      *       case baz
  71      *     }
  72      *
  73      *     augment /bar/foo/bar {
  74      *       case xyzzy;
  75      *     }
  76      *   </code>
  77      * </pre>
  78      * and, more notably, the two augments being in different modules. Since {@code choice bar}'s is part of a reusable
  79      * construct, {@code grouping one}, DataObjects' copy builders can propagate them without translating them to the
  80      * appropriate manifestation -- and they can do nothing about that as they lack the complete view of the effecitve
  81      * model.
  82      *
  83      * @return Additional {@link CaseRuntimeType}s
  84      */
  85     @NonNull Collection<CaseRuntimeType> additionalCaseChildren();
  86 }