binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractCompositeGenerator.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.ArrayList;
  15 import java.util.Iterator;
  16 import java.util.List;
  17 import java.util.stream.Collectors;
  18 import org.eclipse.jdt.annotation.NonNull;
  19 import org.eclipse.jdt.annotation.Nullable;
  20 import org.opendaylight.mdsal.binding.model.api.Enumeration;
  21 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject;
  22 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
  23 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder;
  24 import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
  25 import org.opendaylight.yangtools.yang.common.QName;
  26 import org.opendaylight.yangtools.yang.common.QNameModule;
  27 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
  28 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
  29 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  30 import org.opendaylight.yangtools.yang.model.api.stmt.ActionEffectiveStatement;
  31 import org.opendaylight.yangtools.yang.model.api.stmt.AnydataEffectiveStatement;
  32 import org.opendaylight.yangtools.yang.model.api.stmt.AnyxmlEffectiveStatement;
  33 import org.opendaylight.yangtools.yang.model.api.stmt.AugmentEffectiveStatement;
  34 import org.opendaylight.yangtools.yang.model.api.stmt.CaseEffectiveStatement;
  35 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
  36 import org.opendaylight.yangtools.yang.model.api.stmt.ContainerEffectiveStatement;
  37 import org.opendaylight.yangtools.yang.model.api.stmt.GroupingEffectiveStatement;
  38 import org.opendaylight.yangtools.yang.model.api.stmt.IdentityEffectiveStatement;
  39 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
  40 import org.opendaylight.yangtools.yang.model.api.stmt.LeafEffectiveStatement;
  41 import org.opendaylight.yangtools.yang.model.api.stmt.LeafListEffectiveStatement;
  42 import org.opendaylight.yangtools.yang.model.api.stmt.ListEffectiveStatement;
  43 import org.opendaylight.yangtools.yang.model.api.stmt.NotificationEffectiveStatement;
  44 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
  45 import org.opendaylight.yangtools.yang.model.api.stmt.RpcEffectiveStatement;
  46 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier;
  47 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeEffectiveStatement;
  48 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
  49 import org.opendaylight.yangtools.yang.model.api.stmt.UsesEffectiveStatement;
  50 import org.opendaylight.yangtools.yang.model.ri.type.TypeBuilder;
  51 import org.slf4j.Logger;
  52 import org.slf4j.LoggerFactory;
  53
  54 /**
  55  * A composite generator. Composite generators may contain additional children, which end up being mapped into
  56  * the naming hierarchy 'under' the composite generator. To support this use case, each composite has a Java package
  57  * name assigned.
  58  */
  59 abstract class AbstractCompositeGenerator<T extends EffectiveStatement<?, ?>> extends AbstractExplicitGenerator<T> {
  60     private static final Logger LOG = LoggerFactory.getLogger(AbstractCompositeGenerator.class);
  61
  62     private final @NonNull CollisionDomain domain = new CollisionDomain(this);
  63     private final List<Generator> children;
  64
  65     private List<AbstractAugmentGenerator> augments = List.of();
  66     private List<GroupingGenerator> groupings;
  67
  68     // Performance optimization: if this is true, we have ascertained our original definition as well that of all our
  69     // children
  70     private boolean originalsResolved;
  71
  72     AbstractCompositeGenerator(final T statement) {
  73         super(statement);
  74         children = createChildren(statement);
  75     }
  76
  77     AbstractCompositeGenerator(final T statement, final AbstractCompositeGenerator<?> parent) {
  78         super(statement, parent);
  79         children = createChildren(statement);
  80     }
  81
  82     @Override
  83     public final Iterator<Generator> iterator() {
  84         return children.iterator();
  85     }
  86
  87     @Override
  88     final boolean isEmpty() {
  89         return children.isEmpty();
  90     }
  91
  92     final @Nullable AbstractExplicitGenerator<?> findGenerator(final List<EffectiveStatement<?, ?>> stmtPath) {
  93         return findGenerator(MatchStrategy.identity(), stmtPath, 0);
  94     }
  95
  96     final @Nullable AbstractExplicitGenerator<?> findGenerator(final MatchStrategy childStrategy,
  97             // TODO: Wouldn't this method be nicer with Deque<EffectiveStatement<?, ?>> ?
  98             final List<EffectiveStatement<?, ?>> stmtPath, final int offset) {
  99         final EffectiveStatement<?, ?> stmt = stmtPath.get(offset);
 100
 101         // Try direct children first, which is simple
 102         AbstractExplicitGenerator<?> ret = childStrategy.findGenerator(stmt, children);
 103         if (ret != null) {
 104             final int next = offset + 1;
 105             if (stmtPath.size() == next) {
 106                 // Final step, return child
 107                 return ret;
 108             }
 109             if (ret instanceof AbstractCompositeGenerator) {
 110                 // We know how to descend down
 111                 return ((AbstractCompositeGenerator<?>) ret).findGenerator(childStrategy, stmtPath, next);
 112             }
 113             // Yeah, don't know how to continue here
 114             return null;
 115         }
 116
 117         // At this point we are about to fork for augments or groupings. In either case only schema tree statements can
 118         // be found this way. The fun part is that if we find a match and need to continue, we will use the same
 119         // strategy for children as well. We now know that this (and subsequent) statements need to have a QName
 120         // argument.
 121         if (stmt instanceof SchemaTreeEffectiveStatement) {
 122             // grouping -> uses instantiation changes the namespace to the local namespace of the uses site. We are
 123             // going the opposite direction, hence we are changing namespace from local to the grouping's namespace.
 124             for (GroupingGenerator gen : groupings) {
 125                 final MatchStrategy strat = MatchStrategy.grouping(gen);
 126                 ret = gen.findGenerator(strat, stmtPath, offset);
 127                 if (ret != null) {
 128                     return ret;
 129                 }
 130             }
 131
 132             // All augments are dead simple: they need to match on argument (which we expect to be a QName)
 133             final MatchStrategy strat = MatchStrategy.augment();
 134             for (AbstractAugmentGenerator gen : augments) {
 135                 ret = gen.findGenerator(strat, stmtPath, offset);
 136                 if (ret != null) {
 137                     return ret;
 138                 }
 139             }
 140         }
 141         return null;
 142     }
 143
 144     final @NonNull CollisionDomain domain() {
 145         return domain;
 146     }
 147
 148     final void linkUsesDependencies(final GeneratorContext context) {
 149         // We are resolving 'uses' statements to their corresponding 'grouping' definitions
 150         final List<GroupingGenerator> tmp = new ArrayList<>();
 151         for (EffectiveStatement<?, ?> stmt : statement().effectiveSubstatements()) {
 152             if (stmt instanceof UsesEffectiveStatement) {
 153                 tmp.add(context.resolveTreeScoped(GroupingGenerator.class, ((UsesEffectiveStatement) stmt).argument()));
 154             }
 155         }
 156         groupings = List.copyOf(tmp);
 157     }
 158
 159     final void addAugment(final AbstractAugmentGenerator augment) {
 160         if (augments.isEmpty()) {
 161             augments = new ArrayList<>(2);
 162         }
 163         augments.add(requireNonNull(augment));
 164     }
 165
 166     @Override
 167     long linkOriginalGenerator() {
 168         if (originalsResolved) {
 169             return 0;
 170         }
 171
 172         long remaining = super.linkOriginalGenerator();
 173         if (remaining == 0) {
 174             for (Generator child : children) {
 175                 if (child instanceof AbstractExplicitGenerator) {
 176                     remaining += ((AbstractExplicitGenerator<?>) child).linkOriginalGenerator();
 177                 }
 178             }
 179             if (remaining == 0) {
 180                 originalsResolved = true;
 181             }
 182         }
 183         return remaining;
 184     }
 185
 186     @Override
 187     final AbstractCompositeGenerator<?> getOriginal() {
 188         return (AbstractCompositeGenerator<?>) super.getOriginal();
 189     }
 190
 191     final @NonNull OriginalLink getOriginalChild(final QName childQName) {
 192         // First try groupings/augments ...
 193         final AbstractExplicitGenerator<?> found = findInferredGenerator(childQName);
 194         if (found != null) {
 195             return OriginalLink.partial(found);
 196         }
 197
 198         // ... no luck, we really need to start looking at our origin
 199         final AbstractExplicitGenerator<?> prev = verifyNotNull(previous(),
 200             "Failed to find %s in scope of %s", childQName, this);
 201
 202         final QName prevQName = childQName.bindTo(prev.getQName().getModule());
 203         return verifyNotNull(prev.findSchemaTreeGenerator(prevQName),
 204             "Failed to find child %s (proxy for %s) in %s", prevQName, childQName, prev).originalLink();
 205     }
 206
 207     @Override
 208     final AbstractExplicitGenerator<?> findSchemaTreeGenerator(final QName qname) {
 209         final AbstractExplicitGenerator<?> found = super.findSchemaTreeGenerator(qname);
 210         return found != null ? found : findInferredGenerator(qname);
 211     }
 212
 213     private @Nullable AbstractExplicitGenerator<?> findInferredGenerator(final QName qname) {
 214         // First search our local groupings ...
 215         for (GroupingGenerator grouping : groupings) {
 216             final AbstractExplicitGenerator<?> gen = grouping.findSchemaTreeGenerator(
 217                 qname.bindTo(grouping.statement().argument().getModule()));
 218             if (gen != null) {
 219                 return gen;
 220             }
 221         }
 222         // ... next try local augments, which may have groupings themselves
 223         for (AbstractAugmentGenerator augment : augments) {
 224             final AbstractExplicitGenerator<?> gen = augment.findSchemaTreeGenerator(qname);
 225             if (gen != null) {
 226                 return gen;
 227             }
 228         }
 229         return null;
 230     }
 231
 232     final @NonNull AbstractExplicitGenerator<?> resolveSchemaNode(final SchemaNodeIdentifier path) {
 233         // This is not quite straightforward. 'path' works on top of schema tree, which is instantiated view. Since we
 234         // do not generate duplicate instantiations along 'uses' path, findSchemaTreeGenerator() would satisfy our
 235         // request by returning a child of the source 'grouping'.
 236         //
 237         // When that happens, our subsequent lookups need to adjust the namespace being looked up to the grouping's
 238         // namespace... except for the case when the step is actually an augmentation, in which case we must not make
 239         // that adjustment.
 240         //
 241         // Hence we deal with this lookup recursively, dropping namespace hints when we cross into groupings.
 242         return resolveSchemaNode(path.getNodeIdentifiers().iterator(), null);
 243     }
 244
 245     private @NonNull AbstractExplicitGenerator<?> resolveSchemaNode(final Iterator<QName> qnames,
 246             final @Nullable QNameModule localNamespace) {
 247         final QName qname = qnames.next();
 248
 249         // First try local augments, as those are guaranteed to match namespace exactly
 250         for (AbstractAugmentGenerator augment : augments) {
 251             final AbstractExplicitGenerator<?> gen = augment.findSchemaTreeGenerator(qname);
 252             if (gen != null) {
 253                 return resolveNext(gen, qnames, null);
 254             }
 255         }
 256
 257         // Second try local groupings, as those perform their own adjustment
 258         for (GroupingGenerator grouping : groupings) {
 259             final QNameModule ns = grouping.statement().argument().getModule();
 260             final AbstractExplicitGenerator<?> gen = grouping.findSchemaTreeGenerator(qname.bindTo(ns));
 261             if (gen != null) {
 262                 return resolveNext(gen, qnames, ns);
 263             }
 264         }
 265
 266         // Lastly try local statements adjusted with namespace, if applicable
 267         final QName lookup = localNamespace == null ? qname : qname.bindTo(localNamespace);
 268         final AbstractExplicitGenerator<?> gen = verifyNotNull(super.findSchemaTreeGenerator(lookup),
 269             "Failed to find %s as %s in %s", qname, lookup, this);
 270         return resolveNext(gen, qnames, localNamespace);
 271     }
 272
 273     private static @NonNull AbstractExplicitGenerator<?> resolveNext(final @NonNull AbstractExplicitGenerator<?> gen,
 274             final Iterator<QName> qnames, final QNameModule localNamespace) {
 275         if (qnames.hasNext()) {
 276             verify(gen instanceof AbstractCompositeGenerator, "Unexpected generator %s", gen);
 277             return ((AbstractCompositeGenerator<?>) gen).resolveSchemaNode(qnames, localNamespace);
 278         }
 279         return gen;
 280     }
 281
 282     /**
 283      * Update the specified builder to implement interfaces generated for the {@code grouping} statements this generator
 284      * is using.
 285      *
 286      * @param builder Target builder
 287      * @param builderFactory factory for creating {@link TypeBuilder}s
 288      * @return The number of groupings this type uses.
 289      */
 290     final int addUsesInterfaces(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
 291         for (GroupingGenerator grp : groupings) {
 292             builder.addImplementsType(grp.getGeneratedType(builderFactory));
 293         }
 294         return groupings.size();
 295     }
 296
 297     static final void addAugmentable(final GeneratedTypeBuilder builder) {
 298         builder.addImplementsType(BindingTypes.augmentable(builder));
 299     }
 300
 301     final void addGetterMethods(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
 302         for (Generator child : this) {
 303             // Only process explicit generators here
 304             if (child instanceof AbstractExplicitGenerator) {
 305                 ((AbstractExplicitGenerator<?>) child).addAsGetterMethod(builder, builderFactory);
 306             }
 307
 308             final GeneratedType enclosedType = child.enclosedType(builderFactory);
 309             if (enclosedType instanceof GeneratedTransferObject) {
 310                 builder.addEnclosingTransferObject((GeneratedTransferObject) enclosedType);
 311             } else if (enclosedType instanceof Enumeration) {
 312                 builder.addEnumeration((Enumeration) enclosedType);
 313             } else {
 314                 verify(enclosedType == null, "Unhandled enclosed type %s in %s", enclosedType, child);
 315             }
 316         }
 317     }
 318
 319     private List<Generator> createChildren(final EffectiveStatement<?, ?> statement) {
 320         final List<Generator> tmp = new ArrayList<>();
 321         final List<AbstractAugmentGenerator> tmpAug = new ArrayList<>();
 322
 323         for (EffectiveStatement<?, ?> stmt : statement.effectiveSubstatements()) {
 324             if (stmt instanceof ActionEffectiveStatement) {
 325                 if (!isAugmenting(stmt)) {
 326                     tmp.add(new ActionGenerator((ActionEffectiveStatement) stmt, this));
 327                 }
 328             } else if (stmt instanceof AnydataEffectiveStatement) {
 329                 if (!isAugmenting(stmt)) {
 330                     tmp.add(new OpaqueObjectGenerator<>((AnydataEffectiveStatement) stmt, this));
 331                 }
 332             } else if (stmt instanceof AnyxmlEffectiveStatement) {
 333                 if (!isAugmenting(stmt)) {
 334                     tmp.add(new OpaqueObjectGenerator<>((AnyxmlEffectiveStatement) stmt, this));
 335                 }
 336             } else if (stmt instanceof CaseEffectiveStatement) {
 337                 tmp.add(new CaseGenerator((CaseEffectiveStatement) stmt, this));
 338             } else if (stmt instanceof ChoiceEffectiveStatement) {
 339                 // FIXME: use isOriginalDeclaration() ?
 340                 if (!isAddedByUses(stmt)) {
 341                     tmp.add(new ChoiceGenerator((ChoiceEffectiveStatement) stmt, this));
 342                 }
 343             } else if (stmt instanceof ContainerEffectiveStatement) {
 344                 if (isOriginalDeclaration(stmt)) {
 345                     tmp.add(new ContainerGenerator((ContainerEffectiveStatement) stmt, this));
 346                 }
 347             } else if (stmt instanceof GroupingEffectiveStatement) {
 348                 tmp.add(new GroupingGenerator((GroupingEffectiveStatement) stmt, this));
 349             } else if (stmt instanceof IdentityEffectiveStatement) {
 350                 tmp.add(new IdentityGenerator((IdentityEffectiveStatement) stmt, this));
 351             } else if (stmt instanceof InputEffectiveStatement) {
 352                 // FIXME: do not generate legacy RPC layout
 353                 tmp.add(this instanceof RpcGenerator ? new RpcContainerGenerator((InputEffectiveStatement) stmt, this)
 354                     : new OperationContainerGenerator((InputEffectiveStatement) stmt, this));
 355             } else if (stmt instanceof LeafEffectiveStatement) {
 356                 if (!isAugmenting(stmt)) {
 357                     tmp.add(new LeafGenerator((LeafEffectiveStatement) stmt, this));
 358                 }
 359             } else if (stmt instanceof LeafListEffectiveStatement) {
 360                 if (!isAugmenting(stmt)) {
 361                     tmp.add(new LeafListGenerator((LeafListEffectiveStatement) stmt, this));
 362                 }
 363             } else if (stmt instanceof ListEffectiveStatement) {
 364                 if (isOriginalDeclaration(stmt)) {
 365                     final ListGenerator listGen = new ListGenerator((ListEffectiveStatement) stmt, this);
 366                     tmp.add(listGen);
 367
 368                     final KeyGenerator keyGen = listGen.keyGenerator();
 369                     if (keyGen != null) {
 370                         tmp.add(keyGen);
 371                     }
 372                 }
 373             } else if (stmt instanceof NotificationEffectiveStatement) {
 374                 if (!isAugmenting(stmt)) {
 375                     tmp.add(new NotificationGenerator((NotificationEffectiveStatement) stmt, this));
 376                 }
 377             } else if (stmt instanceof OutputEffectiveStatement) {
 378                 // FIXME: do not generate legacy RPC layout
 379                 tmp.add(this instanceof RpcGenerator ? new RpcContainerGenerator((OutputEffectiveStatement) stmt, this)
 380                     : new OperationContainerGenerator((OutputEffectiveStatement) stmt, this));
 381             } else if (stmt instanceof RpcEffectiveStatement) {
 382                 tmp.add(new RpcGenerator((RpcEffectiveStatement) stmt, this));
 383             } else if (stmt instanceof TypedefEffectiveStatement) {
 384                 tmp.add(new TypedefGenerator((TypedefEffectiveStatement) stmt, this));
 385             } else if (stmt instanceof AugmentEffectiveStatement) {
 386                 // FIXME: MDSAL-695: So here we are ignoring any augment which is not in a module, while the 'uses'
 387                 //                   processing takes care of the rest. There are two problems here:
 388                 //
 389                 //                   1) this could be an augment introduced through uses -- in this case we are picking
 390                 //                      confusing it with this being its declaration site, we should probably be
 391                 //                      ignoring it, but then
 392                 //
 393                 //                   2) we are losing track of AugmentEffectiveStatement for which we do not generate
 394                 //                      interfaces -- and recover it at runtime through explicit walk along the
 395                 //                      corresponding AugmentationSchemaNode.getOriginalDefinition() pointer
 396                 //
 397                 //                   So here is where we should decide how to handle this augment, and make sure we
 398                 //                   retain information about this being an alias. That will serve as the base for keys
 399                 //                   in the augment -> original map we provide to BindingRuntimeTypes.
 400                 if (this instanceof ModuleGenerator) {
 401                     tmpAug.add(new ModuleAugmentGenerator((AugmentEffectiveStatement) stmt, this));
 402                 }
 403             } else if (stmt instanceof UsesEffectiveStatement) {
 404                 final UsesEffectiveStatement uses = (UsesEffectiveStatement) stmt;
 405                 for (EffectiveStatement<?, ?> usesSub : uses.effectiveSubstatements()) {
 406                     if (usesSub instanceof AugmentEffectiveStatement) {
 407                         tmpAug.add(new UsesAugmentGenerator((AugmentEffectiveStatement) usesSub, this));
 408                     }
 409                 }
 410             } else {
 411                 LOG.trace("Ignoring statement {}", stmt);
 412                 continue;
 413             }
 414         }
 415
 416         // Sort augments and add them last. This ensures child iteration order always reflects potential
 417         // interdependencies, hence we do not need to worry about them.
 418         tmpAug.sort(AbstractAugmentGenerator.COMPARATOR);
 419         tmp.addAll(tmpAug);
 420
 421         // Compatibility FooService and FooListener interfaces, only generated for modules.
 422         if (this instanceof ModuleGenerator) {
 423             final ModuleGenerator moduleGen = (ModuleGenerator) this;
 424
 425             final List<NotificationGenerator> notifs = tmp.stream()
 426                 .filter(NotificationGenerator.class::isInstance)
 427                 .map(NotificationGenerator.class::cast)
 428                 .collect(Collectors.toUnmodifiableList());
 429             if (!notifs.isEmpty()) {
 430                 tmp.add(new NotificationServiceGenerator(moduleGen, notifs));
 431             }
 432
 433             final List<RpcGenerator> rpcs = tmp.stream()
 434                 .filter(RpcGenerator.class::isInstance)
 435                 .map(RpcGenerator.class::cast)
 436                 .collect(Collectors.toUnmodifiableList());
 437             if (!rpcs.isEmpty()) {
 438                 tmp.add(new RpcServiceGenerator(moduleGen, rpcs));
 439             }
 440         }
 441
 442         return List.copyOf(tmp);
 443     }
 444
 445     // Utility equivalent of (!isAddedByUses(stmt) && !isAugmenting(stmt)). Takes advantage of relationship between
 446     // CopyableNode and AddedByUsesAware
 447     private static boolean isOriginalDeclaration(final EffectiveStatement<?, ?> stmt) {
 448         if (stmt instanceof AddedByUsesAware) {
 449             if (((AddedByUsesAware) stmt).isAddedByUses()
 450                 || stmt instanceof CopyableNode && ((CopyableNode) stmt).isAugmenting()) {
 451                 return false;
 452             }
 453         }
 454         return true;
 455     }
 456
 457     private static boolean isAddedByUses(final EffectiveStatement<?, ?> stmt) {
 458         return stmt instanceof AddedByUsesAware && ((AddedByUsesAware) stmt).isAddedByUses();
 459     }
 460
 461     private static boolean isAugmenting(final EffectiveStatement<?, ?> stmt) {
 462         return stmt instanceof CopyableNode && ((CopyableNode) stmt).isAugmenting();
 463     }
 464 }