2 * Copyright (c) 2021 PANTHEON.tech, s.r.o. and others. All rights reserved.
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
8 package org.opendaylight.mdsal.binding.generator.impl.reactor;
10 import static com.google.common.base.Verify.verify;
11 import static java.util.Objects.requireNonNull;
13 import java.util.ArrayList;
14 import java.util.Iterator;
15 import java.util.List;
16 import java.util.stream.Collectors;
17 import org.eclipse.jdt.annotation.NonNull;
18 import org.eclipse.jdt.annotation.Nullable;
19 import org.opendaylight.mdsal.binding.model.api.Enumeration;
20 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject;
21 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
22 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder;
23 import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
24 import org.opendaylight.yangtools.yang.common.QName;
25 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
26 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
27 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
28 import org.opendaylight.yangtools.yang.model.api.stmt.ActionEffectiveStatement;
29 import org.opendaylight.yangtools.yang.model.api.stmt.AnydataEffectiveStatement;
30 import org.opendaylight.yangtools.yang.model.api.stmt.AnyxmlEffectiveStatement;
31 import org.opendaylight.yangtools.yang.model.api.stmt.AugmentEffectiveStatement;
32 import org.opendaylight.yangtools.yang.model.api.stmt.CaseEffectiveStatement;
33 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
34 import org.opendaylight.yangtools.yang.model.api.stmt.ContainerEffectiveStatement;
35 import org.opendaylight.yangtools.yang.model.api.stmt.GroupingEffectiveStatement;
36 import org.opendaylight.yangtools.yang.model.api.stmt.IdentityEffectiveStatement;
37 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
38 import org.opendaylight.yangtools.yang.model.api.stmt.LeafEffectiveStatement;
39 import org.opendaylight.yangtools.yang.model.api.stmt.LeafListEffectiveStatement;
40 import org.opendaylight.yangtools.yang.model.api.stmt.ListEffectiveStatement;
41 import org.opendaylight.yangtools.yang.model.api.stmt.NotificationEffectiveStatement;
42 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
43 import org.opendaylight.yangtools.yang.model.api.stmt.RpcEffectiveStatement;
44 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeEffectiveStatement;
45 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
46 import org.opendaylight.yangtools.yang.model.api.stmt.UsesEffectiveStatement;
47 import org.opendaylight.yangtools.yang.model.ri.type.TypeBuilder;
48 import org.slf4j.Logger;
49 import org.slf4j.LoggerFactory;
52 * A composite generator. Composite generators may contain additional children, which end up being mapped into
53 * the naming hierarchy 'under' the composite generator. To support this use case, each composite has a Java package
57 * State tracking for resolution of children to their original declaration, i.e. back along the 'uses' and 'augment'
58 * axis. This is quite convoluted because we are traversing the generator tree recursively in the iteration order of
59 * children, but actual dependencies may require resolution in a different order, for example in the case of:
64 * container xyzzy; // C
69 * container bar { // D
81 * augment /foo/bar/xyzzy { // G
89 * In this case we have three manifestations of 'leaf baz' -- marked A, E and F in the child iteration order. In order
90 * to perform a resolution, we first have to determine that F is the original definition, then establish that E is using
91 * the definition made by F and finally establish that A is using the definition made by F.
94 * Dealing with augmentations is harder still, because we need to attach them to the original definition, hence for the
95 * /foo/bar container at A, we need to understand that its original definition is at D and we need to attach the augment
96 * at B to D. Futhermore we also need to establish that the augmentation at G attaches to container defined in C, so
97 * that the 'leaf xyzzy' existing as /foo/bar/xyzzy/xyzzy under C has its original definition at H.
100 * Finally realize that the augment at G can actually exist in a different module and is shown in this example only
101 * the simplified form. That also means we could encounter G well before 'container foo' as well as we can have multiple
102 * such augments sprinkled across multiple modules having the same dependency rules as between C and G -- but they still
103 * have to form a directed acyclic graph and we partially deal with those complexities by having modules sorted by their
107 * For further details see {@link #linkOriginalGenerator()} and {@link #linkOriginalGeneratorRecursive()}, which deal
108 * with linking original instances in the tree iteration order. The part dealing with augment attachment lives mostly
109 * in {@link AugmentRequirement}.
111 abstract class AbstractCompositeGenerator<T extends EffectiveStatement<?, ?>> extends AbstractExplicitGenerator<T> {
112 private static final Logger LOG = LoggerFactory.getLogger(AbstractCompositeGenerator.class);
114 // FIXME: we want to allocate this lazily to lower memory footprint
115 private final @NonNull CollisionDomain domain = new CollisionDomain(this);
116 private final List<Generator> children;
119 * List of {@code augment} statements targeting this generator. This list is maintained only for the primary
120 * incarnation. This list is an evolving entity until after we have finished linkage of original statements. It is
121 * expected to be stable at the start of {@code step 2} in {@link GeneratorReactor#execute(TypeBuilderFactory)}.
123 private List<AbstractAugmentGenerator> augments = List.of();
126 * List of {@code grouping} statements this statement references. This field is set once by
127 * {@link #linkUsesDependencies(GeneratorContext)}.
129 private List<GroupingGenerator> groupings;
132 * List of composite children which have not been recursively processed. This may become a mutable list when we
133 * have some children which have not completed linking. Once we have completed linking of all children, including
134 * {@link #unlinkedChildren}, this will be set to {@code null}.
136 private List<AbstractCompositeGenerator<?>> unlinkedComposites = List.of();
138 * List of children which have not had their original linked. This list starts of as null. When we first attempt
139 * linkage, it becomes non-null.
141 private List<Generator> unlinkedChildren;
143 AbstractCompositeGenerator(final T statement) {
145 children = createChildren(statement);
148 AbstractCompositeGenerator(final T statement, final AbstractCompositeGenerator<?> parent) {
149 super(statement, parent);
150 children = createChildren(statement);
154 public final Iterator<Generator> iterator() {
155 return children.iterator();
159 final boolean isEmpty() {
160 return children.isEmpty();
163 final @Nullable AbstractExplicitGenerator<?> findGenerator(final List<EffectiveStatement<?, ?>> stmtPath) {
164 return findGenerator(MatchStrategy.identity(), stmtPath, 0);
167 final @Nullable AbstractExplicitGenerator<?> findGenerator(final MatchStrategy childStrategy,
168 // TODO: Wouldn't this method be nicer with Deque<EffectiveStatement<?, ?>> ?
169 final List<EffectiveStatement<?, ?>> stmtPath, final int offset) {
170 final EffectiveStatement<?, ?> stmt = stmtPath.get(offset);
172 // Try direct children first, which is simple
173 AbstractExplicitGenerator<?> ret = childStrategy.findGenerator(stmt, children);
175 final int next = offset + 1;
176 if (stmtPath.size() == next) {
177 // Final step, return child
180 if (ret instanceof AbstractCompositeGenerator) {
181 // We know how to descend down
182 return ((AbstractCompositeGenerator<?>) ret).findGenerator(childStrategy, stmtPath, next);
184 // Yeah, don't know how to continue here
188 // At this point we are about to fork for augments or groupings. In either case only schema tree statements can
189 // be found this way. The fun part is that if we find a match and need to continue, we will use the same
190 // strategy for children as well. We now know that this (and subsequent) statements need to have a QName
192 if (stmt instanceof SchemaTreeEffectiveStatement) {
193 // grouping -> uses instantiation changes the namespace to the local namespace of the uses site. We are
194 // going the opposite direction, hence we are changing namespace from local to the grouping's namespace.
195 for (GroupingGenerator gen : groupings) {
196 final MatchStrategy strat = MatchStrategy.grouping(gen);
197 ret = gen.findGenerator(strat, stmtPath, offset);
203 // All augments are dead simple: they need to match on argument (which we expect to be a QName)
204 final MatchStrategy strat = MatchStrategy.augment();
205 for (AbstractAugmentGenerator gen : augments) {
206 ret = gen.findGenerator(strat, stmtPath, offset);
215 final @NonNull CollisionDomain domain() {
219 final void linkUsesDependencies(final GeneratorContext context) {
220 // We are establishing two linkages here:
221 // - we are resolving 'uses' statements to their corresponding 'grouping' definitions
222 // - we propagate those groupings as anchors to any augment statements, which takes out some amount of guesswork
223 // from augment+uses resolution case, as groupings know about their immediate augments as soon as uses linkage
225 final List<GroupingGenerator> tmp = new ArrayList<>();
226 for (EffectiveStatement<?, ?> stmt : statement().effectiveSubstatements()) {
227 if (stmt instanceof UsesEffectiveStatement) {
228 final UsesEffectiveStatement uses = (UsesEffectiveStatement) stmt;
229 final GroupingGenerator grouping = context.resolveTreeScoped(GroupingGenerator.class, uses.argument());
232 // Trigger resolution of uses/augment statements. This looks like guesswork, but there may be multiple
233 // 'augment' statements in a 'uses' statement and keeping a ListMultimap here seems wasteful.
234 for (Generator gen : this) {
235 if (gen instanceof UsesAugmentGenerator) {
236 ((UsesAugmentGenerator) gen).resolveGrouping(uses, grouping);
241 groupings = List.copyOf(tmp);
244 final void startUsesAugmentLinkage(final List<AugmentRequirement> requirements) {
245 for (Generator child : children) {
246 if (child instanceof UsesAugmentGenerator) {
247 requirements.add(((UsesAugmentGenerator) child).startLinkage());
249 if (child instanceof AbstractCompositeGenerator) {
250 ((AbstractCompositeGenerator<?>) child).startUsesAugmentLinkage(requirements);
255 final void addAugment(final AbstractAugmentGenerator augment) {
256 if (augments.isEmpty()) {
257 augments = new ArrayList<>(2);
259 augments.add(requireNonNull(augment));
263 * Attempt to link the generator corresponding to the original definition for this generator's statements as well as
264 * to all child generators.
266 * @return Progress indication
268 final @NonNull LinkageProgress linkOriginalGeneratorRecursive() {
269 if (unlinkedComposites == null) {
270 // We have unset this list (see below), and there is nothing left to do
271 return LinkageProgress.DONE;
274 if (unlinkedChildren == null) {
275 unlinkedChildren = children.stream()
276 .filter(AbstractExplicitGenerator.class::isInstance)
277 .map(child -> (AbstractExplicitGenerator<?>) child)
278 .collect(Collectors.toList());
281 var progress = LinkageProgress.NONE;
282 if (!unlinkedChildren.isEmpty()) {
283 // Attempt to make progress on child linkage
284 final var it = unlinkedChildren.iterator();
285 while (it.hasNext()) {
286 final var child = it.next();
287 if (child instanceof AbstractExplicitGenerator) {
288 if (((AbstractExplicitGenerator<?>) child).linkOriginalGenerator()) {
289 progress = LinkageProgress.SOME;
292 // If this is a composite generator we need to process is further
293 if (child instanceof AbstractCompositeGenerator) {
294 if (unlinkedComposites.isEmpty()) {
295 unlinkedComposites = new ArrayList<>();
297 unlinkedComposites.add((AbstractCompositeGenerator<?>) child);
303 if (unlinkedChildren.isEmpty()) {
304 // Nothing left to do, make sure any previously-allocated list can be scavenged
305 unlinkedChildren = List.of();
309 // Process children of any composite children we have.
310 final var it = unlinkedComposites.iterator();
311 while (it.hasNext()) {
312 final var tmp = it.next().linkOriginalGeneratorRecursive();
313 if (tmp != LinkageProgress.NONE) {
314 progress = LinkageProgress.SOME;
316 if (tmp == LinkageProgress.DONE) {
321 if (unlinkedChildren.isEmpty() && unlinkedComposites.isEmpty()) {
322 // All done, set the list to null to indicate there is nothing left to do in this generator or any of our
324 unlinkedComposites = null;
325 return LinkageProgress.DONE;
332 final AbstractCompositeGenerator<?> getOriginal() {
333 return (AbstractCompositeGenerator<?>) super.getOriginal();
337 final AbstractCompositeGenerator<?> tryOriginal() {
338 return (AbstractCompositeGenerator<?>) super.tryOriginal();
341 final @Nullable OriginalLink originalChild(final QName childQName) {
342 // First try groupings/augments ...
343 var found = findInferredGenerator(childQName);
345 return OriginalLink.partial(found);
348 // ... no luck, we really need to start looking at our origin
349 final var prev = previous();
351 final QName prevQName = childQName.bindTo(prev.getQName().getModule());
352 found = prev.findSchemaTreeGenerator(prevQName);
354 return found.originalLink();
362 final AbstractExplicitGenerator<?> findSchemaTreeGenerator(final QName qname) {
363 final AbstractExplicitGenerator<?> found = super.findSchemaTreeGenerator(qname);
364 return found != null ? found : findInferredGenerator(qname);
367 final @Nullable AbstractAugmentGenerator findAugmentForGenerator(final QName qname) {
368 for (var augment : augments) {
369 final var gen = augment.findSchemaTreeGenerator(qname);
377 final @Nullable GroupingGenerator findGroupingForGenerator(final QName qname) {
378 for (GroupingGenerator grouping : groupings) {
379 final var gen = grouping.findSchemaTreeGenerator(qname.bindTo(grouping.statement().argument().getModule()));
387 private @Nullable AbstractExplicitGenerator<?> findInferredGenerator(final QName qname) {
388 // First search our local groupings ...
389 for (var grouping : groupings) {
390 final var gen = grouping.findSchemaTreeGenerator(qname.bindTo(grouping.statement().argument().getModule()));
395 // ... next try local augments, which may have groupings themselves
396 for (var augment : augments) {
397 final var gen = augment.findSchemaTreeGenerator(qname);
406 * Update the specified builder to implement interfaces generated for the {@code grouping} statements this generator
409 * @param builder Target builder
410 * @param builderFactory factory for creating {@link TypeBuilder}s
411 * @return The number of groupings this type uses.
413 final int addUsesInterfaces(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
414 for (GroupingGenerator grp : groupings) {
415 builder.addImplementsType(grp.getGeneratedType(builderFactory));
417 return groupings.size();
420 static final void addAugmentable(final GeneratedTypeBuilder builder) {
421 builder.addImplementsType(BindingTypes.augmentable(builder));
424 final void addGetterMethods(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
425 for (Generator child : this) {
426 // Only process explicit generators here
427 if (child instanceof AbstractExplicitGenerator) {
428 ((AbstractExplicitGenerator<?>) child).addAsGetterMethod(builder, builderFactory);
431 final GeneratedType enclosedType = child.enclosedType(builderFactory);
432 if (enclosedType instanceof GeneratedTransferObject) {
433 builder.addEnclosingTransferObject((GeneratedTransferObject) enclosedType);
434 } else if (enclosedType instanceof Enumeration) {
435 builder.addEnumeration((Enumeration) enclosedType);
437 verify(enclosedType == null, "Unhandled enclosed type %s in %s", enclosedType, child);
442 private List<Generator> createChildren(final EffectiveStatement<?, ?> statement) {
443 final List<Generator> tmp = new ArrayList<>();
444 final List<AbstractAugmentGenerator> tmpAug = new ArrayList<>();
446 for (EffectiveStatement<?, ?> stmt : statement.effectiveSubstatements()) {
447 if (stmt instanceof ActionEffectiveStatement) {
448 if (!isAugmenting(stmt)) {
449 tmp.add(new ActionGenerator((ActionEffectiveStatement) stmt, this));
451 } else if (stmt instanceof AnydataEffectiveStatement) {
452 if (!isAugmenting(stmt)) {
453 tmp.add(new OpaqueObjectGenerator<>((AnydataEffectiveStatement) stmt, this));
455 } else if (stmt instanceof AnyxmlEffectiveStatement) {
456 if (!isAugmenting(stmt)) {
457 tmp.add(new OpaqueObjectGenerator<>((AnyxmlEffectiveStatement) stmt, this));
459 } else if (stmt instanceof CaseEffectiveStatement) {
460 tmp.add(new CaseGenerator((CaseEffectiveStatement) stmt, this));
461 } else if (stmt instanceof ChoiceEffectiveStatement) {
462 // FIXME: use isOriginalDeclaration() ?
463 if (!isAddedByUses(stmt)) {
464 tmp.add(new ChoiceGenerator((ChoiceEffectiveStatement) stmt, this));
466 } else if (stmt instanceof ContainerEffectiveStatement) {
467 if (isOriginalDeclaration(stmt)) {
468 tmp.add(new ContainerGenerator((ContainerEffectiveStatement) stmt, this));
470 } else if (stmt instanceof GroupingEffectiveStatement) {
471 tmp.add(new GroupingGenerator((GroupingEffectiveStatement) stmt, this));
472 } else if (stmt instanceof IdentityEffectiveStatement) {
473 tmp.add(new IdentityGenerator((IdentityEffectiveStatement) stmt, this));
474 } else if (stmt instanceof InputEffectiveStatement) {
475 // FIXME: do not generate legacy RPC layout
476 tmp.add(this instanceof RpcGenerator ? new RpcContainerGenerator((InputEffectiveStatement) stmt, this)
477 : new OperationContainerGenerator((InputEffectiveStatement) stmt, this));
478 } else if (stmt instanceof LeafEffectiveStatement) {
479 if (!isAugmenting(stmt)) {
480 tmp.add(new LeafGenerator((LeafEffectiveStatement) stmt, this));
482 } else if (stmt instanceof LeafListEffectiveStatement) {
483 if (!isAugmenting(stmt)) {
484 tmp.add(new LeafListGenerator((LeafListEffectiveStatement) stmt, this));
486 } else if (stmt instanceof ListEffectiveStatement) {
487 if (isOriginalDeclaration(stmt)) {
488 final ListGenerator listGen = new ListGenerator((ListEffectiveStatement) stmt, this);
491 final KeyGenerator keyGen = listGen.keyGenerator();
492 if (keyGen != null) {
496 } else if (stmt instanceof NotificationEffectiveStatement) {
497 if (!isAugmenting(stmt)) {
498 tmp.add(new NotificationGenerator((NotificationEffectiveStatement) stmt, this));
500 } else if (stmt instanceof OutputEffectiveStatement) {
501 // FIXME: do not generate legacy RPC layout
502 tmp.add(this instanceof RpcGenerator ? new RpcContainerGenerator((OutputEffectiveStatement) stmt, this)
503 : new OperationContainerGenerator((OutputEffectiveStatement) stmt, this));
504 } else if (stmt instanceof RpcEffectiveStatement) {
505 tmp.add(new RpcGenerator((RpcEffectiveStatement) stmt, this));
506 } else if (stmt instanceof TypedefEffectiveStatement) {
507 tmp.add(new TypedefGenerator((TypedefEffectiveStatement) stmt, this));
508 } else if (stmt instanceof AugmentEffectiveStatement) {
509 // FIXME: MDSAL-695: So here we are ignoring any augment which is not in a module, while the 'uses'
510 // processing takes care of the rest. There are two problems here:
512 // 1) this could be an augment introduced through uses -- in this case we are picking
513 // confusing it with this being its declaration site, we should probably be
514 // ignoring it, but then
516 // 2) we are losing track of AugmentEffectiveStatement for which we do not generate
517 // interfaces -- and recover it at runtime through explicit walk along the
518 // corresponding AugmentationSchemaNode.getOriginalDefinition() pointer
520 // So here is where we should decide how to handle this augment, and make sure we
521 // retain information about this being an alias. That will serve as the base for keys
522 // in the augment -> original map we provide to BindingRuntimeTypes.
523 if (this instanceof ModuleGenerator) {
524 tmpAug.add(new ModuleAugmentGenerator((AugmentEffectiveStatement) stmt, this));
526 } else if (stmt instanceof UsesEffectiveStatement) {
527 final UsesEffectiveStatement uses = (UsesEffectiveStatement) stmt;
528 for (EffectiveStatement<?, ?> usesSub : uses.effectiveSubstatements()) {
529 if (usesSub instanceof AugmentEffectiveStatement) {
530 tmpAug.add(new UsesAugmentGenerator((AugmentEffectiveStatement) usesSub, uses, this));
534 LOG.trace("Ignoring statement {}", stmt);
539 // Sort augments and add them last. This ensures child iteration order always reflects potential
540 // interdependencies, hence we do not need to worry about them. This is extremely important, as there are a
541 // number of places where we would have to either move the logic to parent statement and explicitly filter/sort
542 // substatements to establish this order.
543 tmpAug.sort(AbstractAugmentGenerator.COMPARATOR);
546 // Compatibility FooService and FooListener interfaces, only generated for modules.
547 if (this instanceof ModuleGenerator) {
548 final ModuleGenerator moduleGen = (ModuleGenerator) this;
550 final List<NotificationGenerator> notifs = tmp.stream()
551 .filter(NotificationGenerator.class::isInstance)
552 .map(NotificationGenerator.class::cast)
553 .collect(Collectors.toUnmodifiableList());
554 if (!notifs.isEmpty()) {
555 tmp.add(new NotificationServiceGenerator(moduleGen, notifs));
558 final List<RpcGenerator> rpcs = tmp.stream()
559 .filter(RpcGenerator.class::isInstance)
560 .map(RpcGenerator.class::cast)
561 .collect(Collectors.toUnmodifiableList());
562 if (!rpcs.isEmpty()) {
563 tmp.add(new RpcServiceGenerator(moduleGen, rpcs));
567 return List.copyOf(tmp);
570 // Utility equivalent of (!isAddedByUses(stmt) && !isAugmenting(stmt)). Takes advantage of relationship between
571 // CopyableNode and AddedByUsesAware
572 private static boolean isOriginalDeclaration(final EffectiveStatement<?, ?> stmt) {
573 if (stmt instanceof AddedByUsesAware) {
574 if (((AddedByUsesAware) stmt).isAddedByUses()
575 || stmt instanceof CopyableNode && ((CopyableNode) stmt).isAugmenting()) {
582 private static boolean isAddedByUses(final EffectiveStatement<?, ?> stmt) {
583 return stmt instanceof AddedByUsesAware && ((AddedByUsesAware) stmt).isAddedByUses();
586 private static boolean isAugmenting(final EffectiveStatement<?, ?> stmt) {
587 return stmt instanceof CopyableNode && ((CopyableNode) stmt).isAugmenting();