binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractAugmentGenerator.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.generator.impl.reactor;
   9
  10 import static com.google.common.base.Verify.verify;
  11 import static com.google.common.base.Verify.verifyNotNull;
  12 import static java.util.Objects.requireNonNull;
  13
  14 import java.util.Comparator;
  15 import java.util.Iterator;
  16 import java.util.List;
  17 import org.eclipse.jdt.annotation.NonNull;
  18 import org.opendaylight.mdsal.binding.generator.impl.reactor.CollisionDomain.Member;
  19 import org.opendaylight.mdsal.binding.generator.impl.rt.DefaultAugmentRuntimeType;
  20 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
  21 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder;
  22 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilderBase;
  23 import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
  24 import org.opendaylight.mdsal.binding.runtime.api.AugmentRuntimeType;
  25 import org.opendaylight.mdsal.binding.runtime.api.CaseRuntimeType;
  26 import org.opendaylight.mdsal.binding.runtime.api.RuntimeType;
  27 import org.opendaylight.yangtools.odlext.model.api.AugmentIdentifierEffectiveStatement;
  28 import org.opendaylight.yangtools.yang.common.AbstractQName;
  29 import org.opendaylight.yangtools.yang.common.QName;
  30 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  31 import org.opendaylight.yangtools.yang.model.api.stmt.AugmentEffectiveStatement;
  32 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
  33 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeAwareEffectiveStatement;
  34 import org.opendaylight.yangtools.yang.model.util.SchemaInferenceStack;
  35
  36 /**
  37  * A generator corresponding to a {@code augment} statement. This class is further specialized for the two distinct uses
  38  * an augment is used.
  39  */
  40 abstract class AbstractAugmentGenerator
  41         extends AbstractCompositeGenerator<AugmentEffectiveStatement, AugmentRuntimeType> {
  42     /**
  43      * Comparator comparing target path length. This is useful for quickly determining order the order in which two
  44      * (or more) {@link AbstractAugmentGenerator}s need to be evaluated. This is necessary when augments are layered on
  45      * top of each other:
  46      *
  47      * <p>
  48      * <pre>
  49      *   <code>
  50      *     container foo;
  51      *
  52      *     augment /foo/bar {
  53      *       container baz;
  54      *     }
  55      *
  56      *     augment /foo {
  57      *       container bar;
  58      *     }
  59      *   </code>
  60      * </pre>
  61      *
  62      * <p>
  63      * Evaluating these in the order of increasing argument component count solves this without having to perform a full
  64      * analysis.
  65      *
  66      * <p>
  67      * Another problem we are solving here is augmentation target stability, as the declared order in YANG text may
  68      * change, which does not really change the semantics. If we only relied on length of argument, such a move would
  69      * result in changing the results of {@link #createMember(CollisionDomain)} and make upgrades rather unpredictable.
  70      * We solve this by using {@link QName#compareTo(QName)} to determine order.
  71      */
  72     static final Comparator<? super AbstractAugmentGenerator> COMPARATOR = (o1, o2) -> {
  73         final Iterator<QName> thisIt = o1.statement().argument().getNodeIdentifiers().iterator();
  74         final Iterator<QName> otherIt = o2.statement().argument().getNodeIdentifiers().iterator();
  75
  76         while (thisIt.hasNext()) {
  77             if (!otherIt.hasNext()) {
  78                 return 1;
  79             }
  80
  81             final int comp = thisIt.next().compareTo(otherIt.next());
  82             if (comp != 0) {
  83                 return comp;
  84             }
  85         }
  86
  87         return otherIt.hasNext() ? -1 : 0;
  88     };
  89
  90     private AbstractCompositeGenerator<?, ?> targetGen;
  91
  92     AbstractAugmentGenerator(final AugmentEffectiveStatement statement, final AbstractCompositeGenerator<?, ?> parent) {
  93         super(statement, parent);
  94     }
  95
  96     @Override
  97     final void pushToInference(final SchemaInferenceStack dataTree) {
  98         dataTree.enterSchemaTree(statement().argument());
  99     }
 100
 101     @Override
 102     final AbstractQName localName() {
 103         throw new UnsupportedOperationException();
 104     }
 105
 106     @Override
 107     ClassPlacement classPlacement() {
 108         // if the target is a choice we are NOT creating an explicit augmentation, but we still need a phantom to
 109         // reserve the appropriate package name
 110         final AbstractCompositeGenerator<?, ?> target = targetGenerator();
 111         return target instanceof ChoiceGenerator ? ClassPlacement.PHANTOM : super.classPlacement();
 112     }
 113
 114     @Override
 115     final Member createMember(final CollisionDomain domain) {
 116         final AbstractQName explicitIdentifier = statement()
 117             .findFirstEffectiveSubstatementArgument(AugmentIdentifierEffectiveStatement.class).orElse(null);
 118         if (explicitIdentifier != null) {
 119             return domain.addPrimary(this, new CamelCaseNamingStrategy(StatementNamespace.DEFAULT, explicitIdentifier));
 120         }
 121
 122         final Member target = targetGenerator().getMember();
 123         int offset = 1;
 124         for (Generator gen : getParent()) {
 125             if (gen == this) {
 126                 break;
 127             }
 128             if (gen instanceof AbstractAugmentGenerator
 129                 && target.equalRoot(((AbstractAugmentGenerator) gen).targetGenerator().getMember())) {
 130                 offset++;
 131             }
 132         }
 133
 134         return domain.addSecondary(this, target, String.valueOf(offset), statement().argument());
 135     }
 136
 137     @Override
 138     final GeneratedType createTypeImpl(final TypeBuilderFactory builderFactory) {
 139         final GeneratedTypeBuilder builder = builderFactory.newGeneratedTypeBuilder(typeName());
 140
 141         builder.addImplementsType(BindingTypes.augmentation(targetGenerator().getGeneratedType(builderFactory)));
 142         addUsesInterfaces(builder, builderFactory);
 143         addConcreteInterfaceMethods(builder);
 144
 145         addGetterMethods(builder, builderFactory);
 146         annotateDeprecatedIfNecessary(builder);
 147
 148         return builder.build();
 149     }
 150
 151     boolean matchesInstantiated(final AugmentEffectiveStatement statement) {
 152         return statement().equals(statement);
 153     }
 154
 155     final void fillRuntimeCasesIn(final AugmentResolver resolver, final ChoiceEffectiveStatement stmt,
 156             final List<CaseRuntimeType> toList) {
 157         toList.addAll(createBuilder(effectiveIn(stmt)).populate(resolver, this).getCaseChilden());
 158     }
 159
 160     final @NonNull AugmentRuntimeType runtimeTypeIn(final AugmentResolver resolver,
 161             final EffectiveStatement<?, ?> stmt) {
 162         verify(stmt instanceof SchemaTreeAwareEffectiveStatement, "Unexpected target statement %s", stmt);
 163         return verifyNotNull(createInternalRuntimeType(resolver,
 164             effectiveIn((SchemaTreeAwareEffectiveStatement<?, ?>) stmt)));
 165     }
 166
 167     abstract @NonNull TargetAugmentEffectiveStatement effectiveIn(SchemaTreeAwareEffectiveStatement<?, ?> target);
 168
 169     @Override
 170     final void addAsGetterMethod(final GeneratedTypeBuilderBase<?> builder, final TypeBuilderFactory builderFactory) {
 171         // Augments are never added as getters, as they are handled via Augmentable mechanics
 172     }
 173
 174     @Override
 175     CompositeRuntimeTypeBuilder<AugmentEffectiveStatement, AugmentRuntimeType> createBuilder(
 176             final AugmentEffectiveStatement statement) {
 177         return new CompositeRuntimeTypeBuilder<>(statement) {
 178             @Override
 179             AugmentRuntimeType build(final GeneratedType type, final AugmentEffectiveStatement statement,
 180                     final List<RuntimeType> children, final List<AugmentRuntimeType> augments) {
 181                 // 'augment' cannot be targeted by augment
 182                 verify(augments.isEmpty(), "Unexpected augments %s", augments);
 183                 return new DefaultAugmentRuntimeType(type, statement, children);
 184             }
 185         };
 186     }
 187
 188     final void setTargetGenerator(final AbstractCompositeGenerator<?, ?> targetGenerator) {
 189         verify(targetGen == null, "Attempted to relink %s, already have target %s", this, targetGen);
 190         targetGen = requireNonNull(targetGenerator);
 191     }
 192
 193     final @NonNull AbstractCompositeGenerator<?, ?> targetGenerator() {
 194         return verifyNotNull(targetGen, "No target for %s", this);
 195     }
 196 }