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