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 com.google.common.base.Verify.verifyNotNull;
12 import static java.util.Objects.requireNonNull;
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;
24 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder;
25 import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
26 import org.opendaylight.mdsal.binding.runtime.api.CompositeRuntimeType;
27 import org.opendaylight.mdsal.binding.runtime.api.RuntimeType;
28 import org.opendaylight.yangtools.yang.common.QName;
29 import org.opendaylight.yangtools.yang.model.api.AddedByUsesAware;
30 import org.opendaylight.yangtools.yang.model.api.CopyableNode;
31 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
32 import org.opendaylight.yangtools.yang.model.api.stmt.ActionEffectiveStatement;
33 import org.opendaylight.yangtools.yang.model.api.stmt.AnydataEffectiveStatement;
34 import org.opendaylight.yangtools.yang.model.api.stmt.AnyxmlEffectiveStatement;
35 import org.opendaylight.yangtools.yang.model.api.stmt.AugmentEffectiveStatement;
36 import org.opendaylight.yangtools.yang.model.api.stmt.CaseEffectiveStatement;
37 import org.opendaylight.yangtools.yang.model.api.stmt.ChoiceEffectiveStatement;
38 import org.opendaylight.yangtools.yang.model.api.stmt.ContainerEffectiveStatement;
39 import org.opendaylight.yangtools.yang.model.api.stmt.FeatureEffectiveStatement;
40 import org.opendaylight.yangtools.yang.model.api.stmt.GroupingEffectiveStatement;
41 import org.opendaylight.yangtools.yang.model.api.stmt.IdentityEffectiveStatement;
42 import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
43 import org.opendaylight.yangtools.yang.model.api.stmt.LeafEffectiveStatement;
44 import org.opendaylight.yangtools.yang.model.api.stmt.LeafListEffectiveStatement;
45 import org.opendaylight.yangtools.yang.model.api.stmt.ListEffectiveStatement;
46 import org.opendaylight.yangtools.yang.model.api.stmt.NotificationEffectiveStatement;
47 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
48 import org.opendaylight.yangtools.yang.model.api.stmt.RpcEffectiveStatement;
49 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaTreeEffectiveStatement;
50 import org.opendaylight.yangtools.yang.model.api.stmt.TypedefEffectiveStatement;
51 import org.opendaylight.yangtools.yang.model.api.stmt.UsesEffectiveStatement;
52 import org.opendaylight.yangtools.yang.model.ri.type.TypeBuilder;
53 import org.slf4j.Logger;
54 import org.slf4j.LoggerFactory;
57 * A composite generator. Composite generators may contain additional children, which end up being mapped into
58 * the naming hierarchy 'under' the composite generator. To support this use case, each composite has a Java package
62 * State tracking for resolution of children to their original declaration, i.e. back along the 'uses' and 'augment'
63 * axis. This is quite convoluted because we are traversing the generator tree recursively in the iteration order of
64 * children, but actual dependencies may require resolution in a different order, for example in the case of:
69 * container xyzzy; // C
74 * container bar { // D
86 * augment /foo/bar/xyzzy { // G
94 * In this case we have three manifestations of 'leaf baz' -- marked A, E and F in the child iteration order. In order
95 * to perform a resolution, we first have to determine that F is the original definition, then establish that E is using
96 * the definition made by F and finally establish that A is using the definition made by F.
99 * Dealing with augmentations is harder still, because we need to attach them to the original definition, hence for the
100 * /foo/bar container at A, we need to understand that its original definition is at D and we need to attach the augment
101 * at B to D. Futhermore we also need to establish that the augmentation at G attaches to container defined in C, so
102 * that the 'leaf xyzzy' existing as /foo/bar/xyzzy/xyzzy under C has its original definition at H.
105 * Finally realize that the augment at G can actually exist in a different module and is shown in this example only
106 * the simplified form. That also means we could encounter G well before 'container foo' as well as we can have multiple
107 * such augments sprinkled across multiple modules having the same dependency rules as between C and G -- but they still
108 * have to form a directed acyclic graph and we partially deal with those complexities by having modules sorted by their
112 * For further details see {@link #linkOriginalGenerator()} and {@link #linkOriginalGeneratorRecursive()}, which deal
113 * with linking original instances in the tree iteration order. The part dealing with augment attachment lives mostly
114 * in {@link AugmentRequirement}.
116 public abstract class AbstractCompositeGenerator<S extends EffectiveStatement<?, ?>, R extends CompositeRuntimeType>
117 extends AbstractExplicitGenerator<S, R> {
118 private static final Logger LOG = LoggerFactory.getLogger(AbstractCompositeGenerator.class);
120 // FIXME: we want to allocate this lazily to lower memory footprint
121 private final @NonNull CollisionDomain domain = new CollisionDomain(this);
122 private final @NonNull List<Generator> childGenerators;
125 * List of {@code augment} statements targeting this generator. This list is maintained only for the primary
126 * incarnation. This list is an evolving entity until after we have finished linkage of original statements. It is
127 * expected to be stable at the start of {@code step 2} in {@link GeneratorReactor#execute(TypeBuilderFactory)}.
129 private @NonNull List<AbstractAugmentGenerator> augments = List.of();
132 * List of {@code grouping} statements this statement references. This field is set once by
133 * {@link #linkUsesDependencies(GeneratorContext)}.
135 private List<GroupingGenerator> groupings;
138 * List of composite children which have not been recursively processed. This may become a mutable list when we
139 * have some children which have not completed linking. Once we have completed linking of all children, including
140 * {@link #unlinkedChildren}, this will be set to {@code null}.
142 private List<AbstractCompositeGenerator<?, ?>> unlinkedComposites = List.of();
144 * List of children which have not had their original linked. This list starts of as null. When we first attempt
145 * linkage, it becomes non-null.
147 private List<Generator> unlinkedChildren;
149 AbstractCompositeGenerator(final S statement) {
151 childGenerators = createChildren(statement);
154 AbstractCompositeGenerator(final S statement, final AbstractCompositeGenerator<?, ?> parent) {
155 super(statement, parent);
156 childGenerators = createChildren(statement);
160 public final Iterator<Generator> iterator() {
161 return childGenerators.iterator();
164 final @NonNull List<AbstractAugmentGenerator> augments() {
168 final @NonNull List<GroupingGenerator> groupings() {
169 return verifyNotNull(groupings, "Groupings not initialized in %s", this);
173 final R createExternalRuntimeType(final Type type) {
174 verify(type instanceof GeneratedType, "Unexpected type %s", type);
175 return createBuilder(statement()).populate(new AugmentResolver(), this).build((GeneratedType) type);
178 abstract @NonNull CompositeRuntimeTypeBuilder<S, R> createBuilder(S statement);
181 final R createInternalRuntimeType(final AugmentResolver resolver, final S statement, final Type type) {
182 verify(type instanceof GeneratedType, "Unexpected type %s", type);
183 return createBuilder(statement).populate(resolver, this).build((GeneratedType) type);
187 final boolean isEmpty() {
188 return childGenerators.isEmpty();
191 final @Nullable AbstractExplicitGenerator<?, ?> findGenerator(final List<EffectiveStatement<?, ?>> stmtPath) {
192 return findGenerator(MatchStrategy.identity(), stmtPath, 0);
195 final @Nullable AbstractExplicitGenerator<?, ?> findGenerator(final MatchStrategy childStrategy,
196 // TODO: Wouldn't this method be nicer with Deque<EffectiveStatement<?, ?>> ?
197 final List<EffectiveStatement<?, ?>> stmtPath, final int offset) {
198 final var stmt = stmtPath.get(offset);
200 // Try direct children first, which is simple
201 var ret = childStrategy.findGenerator(stmt, childGenerators);
203 final int next = offset + 1;
204 if (stmtPath.size() == next) {
205 // Final step, return child
208 if (ret instanceof AbstractCompositeGenerator<?, ?> composite) {
209 // We know how to descend down
210 return composite.findGenerator(childStrategy, stmtPath, next);
212 // Yeah, don't know how to continue here
216 // At this point we are about to fork for augments or groupings. In either case only schema tree statements can
217 // be found this way. The fun part is that if we find a match and need to continue, we will use the same
218 // strategy for children as well. We now know that this (and subsequent) statements need to have a QName
220 if (stmt instanceof SchemaTreeEffectiveStatement) {
221 // grouping -> uses instantiation changes the namespace to the local namespace of the uses site. We are
222 // going the opposite direction, hence we are changing namespace from local to the grouping's namespace.
223 for (GroupingGenerator gen : groupings) {
224 final MatchStrategy strat = MatchStrategy.grouping(gen);
225 ret = gen.findGenerator(strat, stmtPath, offset);
231 // All augments are dead simple: they need to match on argument (which we expect to be a QName)
232 final MatchStrategy strat = MatchStrategy.augment();
233 for (AbstractAugmentGenerator gen : augments) {
234 ret = gen.findGenerator(strat, stmtPath, offset);
243 final @NonNull CollisionDomain domain() {
247 final void linkUsesDependencies(final GeneratorContext context) {
248 // We are establishing two linkages here:
249 // - we are resolving 'uses' statements to their corresponding 'grouping' definitions
250 // - we propagate those groupings as anchors to any augment statements, which takes out some amount of guesswork
251 // from augment+uses resolution case, as groupings know about their immediate augments as soon as uses linkage
253 final var tmp = new ArrayList<GroupingGenerator>();
254 for (var stmt : statement().effectiveSubstatements()) {
255 if (stmt instanceof UsesEffectiveStatement uses) {
256 final var grouping = context.resolveTreeScoped(GroupingGenerator.class, uses.argument());
259 // Trigger resolution of uses/augment statements. This looks like guesswork, but there may be multiple
260 // 'augment' statements in a 'uses' statement and keeping a ListMultimap here seems wasteful.
261 for (Generator gen : this) {
262 if (gen instanceof UsesAugmentGenerator usesGen) {
263 usesGen.resolveGrouping(uses, grouping);
268 groupings = List.copyOf(tmp);
271 final void startUsesAugmentLinkage(final List<AugmentRequirement> requirements) {
272 for (var child : childGenerators) {
273 if (child instanceof UsesAugmentGenerator uses) {
274 requirements.add(uses.startLinkage());
276 if (child instanceof AbstractCompositeGenerator<?, ?> composite) {
277 composite.startUsesAugmentLinkage(requirements);
282 final void addAugment(final AbstractAugmentGenerator augment) {
283 if (augments.isEmpty()) {
284 augments = new ArrayList<>(2);
286 augments.add(requireNonNull(augment));
290 * Attempt to link the generator corresponding to the original definition for this generator's statements as well as
291 * to all child generators.
293 * @return Progress indication
295 final @NonNull LinkageProgress linkOriginalGeneratorRecursive() {
296 if (unlinkedComposites == null) {
297 // We have unset this list (see below), and there is nothing left to do
298 return LinkageProgress.DONE;
301 if (unlinkedChildren == null) {
302 unlinkedChildren = childGenerators.stream()
303 .filter(AbstractExplicitGenerator.class::isInstance)
304 .map(child -> (AbstractExplicitGenerator<?, ?>) child)
305 .collect(Collectors.toList());
308 var progress = LinkageProgress.NONE;
309 if (!unlinkedChildren.isEmpty()) {
310 // Attempt to make progress on child linkage
311 final var it = unlinkedChildren.iterator();
312 while (it.hasNext()) {
313 final var child = it.next();
314 if (child instanceof AbstractExplicitGenerator) {
315 if (((AbstractExplicitGenerator<?, ?>) child).linkOriginalGenerator()) {
316 progress = LinkageProgress.SOME;
319 // If this is a composite generator we need to process is further
320 if (child instanceof AbstractCompositeGenerator<?, ?> composite) {
321 if (unlinkedComposites.isEmpty()) {
322 unlinkedComposites = new ArrayList<>();
324 unlinkedComposites.add(composite);
330 if (unlinkedChildren.isEmpty()) {
331 // Nothing left to do, make sure any previously-allocated list can be scavenged
332 unlinkedChildren = List.of();
336 // Process children of any composite children we have.
337 final var it = unlinkedComposites.iterator();
338 while (it.hasNext()) {
339 final var tmp = it.next().linkOriginalGeneratorRecursive();
340 if (tmp != LinkageProgress.NONE) {
341 progress = LinkageProgress.SOME;
343 if (tmp == LinkageProgress.DONE) {
348 if (unlinkedChildren.isEmpty() && unlinkedComposites.isEmpty()) {
349 // All done, set the list to null to indicate there is nothing left to do in this generator or any of our
351 unlinkedComposites = null;
352 return LinkageProgress.DONE;
359 final AbstractCompositeGenerator<S, R> getOriginal() {
360 return (AbstractCompositeGenerator<S, R>) super.getOriginal();
364 final AbstractCompositeGenerator<S, R> tryOriginal() {
365 return (AbstractCompositeGenerator<S, R>) super.tryOriginal();
368 final <X extends EffectiveStatement<?, ?>, Y extends RuntimeType> @Nullable OriginalLink<X, Y> originalChild(
369 final QName childQName) {
370 // First try groupings/augments ...
371 var found = findInferredGenerator(childQName);
373 return (OriginalLink<X, Y>) OriginalLink.partial(found);
376 // ... no luck, we really need to start looking at our origin
377 final var prev = previous();
379 final QName prevQName = childQName.bindTo(prev.getQName().getModule());
380 found = prev.findSchemaTreeGenerator(prevQName);
382 return (OriginalLink<X, Y>) found.originalLink();
390 final AbstractExplicitGenerator<?, ?> findSchemaTreeGenerator(final QName qname) {
391 final var found = super.findSchemaTreeGenerator(qname);
392 return found != null ? found : findInferredGenerator(qname);
395 final @Nullable AbstractAugmentGenerator findAugmentForGenerator(final QName qname) {
396 for (var augment : augments) {
397 final var gen = augment.findSchemaTreeGenerator(qname);
405 final @Nullable GroupingGenerator findGroupingForGenerator(final QName qname) {
406 for (var grouping : groupings) {
407 final var gen = grouping.findSchemaTreeGenerator(qname.bindTo(grouping.statement().argument().getModule()));
415 private @Nullable AbstractExplicitGenerator<?, ?> findInferredGenerator(final QName qname) {
416 // First search our local groupings ...
417 for (var grouping : groupings) {
418 final var gen = grouping.findSchemaTreeGenerator(qname.bindTo(grouping.statement().argument().getModule()));
423 // ... next try local augments, which may have groupings themselves
424 for (var augment : augments) {
425 final var gen = augment.findSchemaTreeGenerator(qname);
434 * Update the specified builder to implement interfaces generated for the {@code grouping} statements this generator
437 * @param builder Target builder
438 * @param builderFactory factory for creating {@link TypeBuilder}s
439 * @return The number of groupings this type uses.
441 final int addUsesInterfaces(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
442 for (var grp : groupings) {
443 builder.addImplementsType(grp.getGeneratedType(builderFactory));
445 return groupings.size();
448 static final void addAugmentable(final GeneratedTypeBuilder builder) {
449 builder.addImplementsType(BindingTypes.augmentable(builder));
452 final void addGetterMethods(final GeneratedTypeBuilder builder, final TypeBuilderFactory builderFactory) {
453 for (var child : this) {
454 // Only process explicit generators here
455 if (child instanceof AbstractExplicitGenerator<?, ?> explicit) {
456 explicit.addAsGetterMethod(builder, builderFactory);
459 final var enclosedType = child.enclosedType(builderFactory);
460 if (enclosedType instanceof GeneratedTransferObject gto) {
461 builder.addEnclosingTransferObject(gto);
462 } else if (enclosedType instanceof Enumeration enumeration) {
463 builder.addEnumeration(enumeration);
465 verify(enclosedType == null, "Unhandled enclosed type %s in %s", enclosedType, child);
470 private @NonNull List<Generator> createChildren(final EffectiveStatement<?, ?> statement) {
471 final var tmp = new ArrayList<Generator>();
472 final var tmpAug = new ArrayList<AbstractAugmentGenerator>();
474 for (var stmt : statement.effectiveSubstatements()) {
475 if (stmt instanceof ActionEffectiveStatement action) {
476 if (!isAugmenting(action)) {
477 tmp.add(new ActionGenerator(action, this));
479 } else if (stmt instanceof AnydataEffectiveStatement anydata) {
480 if (!isAugmenting(anydata)) {
481 tmp.add(new OpaqueObjectGenerator.Anydata(anydata, this));
483 } else if (stmt instanceof AnyxmlEffectiveStatement anyxml) {
484 if (!isAugmenting(anyxml)) {
485 tmp.add(new OpaqueObjectGenerator.Anyxml(anyxml, this));
487 } else if (stmt instanceof CaseEffectiveStatement cast) {
488 tmp.add(new CaseGenerator(cast, this));
489 } else if (stmt instanceof ChoiceEffectiveStatement choice) {
490 // FIXME: use isOriginalDeclaration() ?
491 if (!isAddedByUses(choice)) {
492 tmp.add(new ChoiceGenerator(choice, this));
494 } else if (stmt instanceof ContainerEffectiveStatement container) {
495 if (isOriginalDeclaration(container)) {
496 tmp.add(new ContainerGenerator(container, this));
498 } else if (stmt instanceof FeatureEffectiveStatement feature && this instanceof ModuleGenerator parent) {
499 tmp.add(new FeatureGenerator(feature, parent));
500 } else if (stmt instanceof GroupingEffectiveStatement grouping) {
501 tmp.add(new GroupingGenerator(grouping, this));
502 } else if (stmt instanceof IdentityEffectiveStatement identity) {
503 tmp.add(new IdentityGenerator(identity, this));
504 } else if (stmt instanceof InputEffectiveStatement input) {
505 tmp.add(this instanceof RpcGenerator ? new RpcInputGenerator(input, this)
506 : new InputGenerator(input, this));
507 } else if (stmt instanceof LeafEffectiveStatement leaf) {
508 if (!isAugmenting(leaf)) {
509 tmp.add(new LeafGenerator(leaf, this));
511 } else if (stmt instanceof LeafListEffectiveStatement leafList) {
512 if (!isAugmenting(leafList)) {
513 tmp.add(new LeafListGenerator(leafList, this));
515 } else if (stmt instanceof ListEffectiveStatement list) {
516 if (isOriginalDeclaration(list)) {
517 final var listGen = new ListGenerator(list, this);
520 final var keyGen = listGen.keyGenerator();
521 if (keyGen != null) {
525 } else if (stmt instanceof NotificationEffectiveStatement notification) {
526 if (!isAugmenting(notification)) {
527 tmp.add(new NotificationGenerator(notification, this));
529 } else if (stmt instanceof OutputEffectiveStatement output) {
530 tmp.add(this instanceof RpcGenerator ? new RpcOutputGenerator(output, this)
531 : new OutputGenerator(output, this));
532 } else if (stmt instanceof RpcEffectiveStatement rpc) {
533 if (this instanceof ModuleGenerator module) {
534 tmp.add(new RpcGenerator(rpc, module));
536 } else if (stmt instanceof TypedefEffectiveStatement typedef) {
537 tmp.add(new TypedefGenerator(typedef, this));
538 } else if (stmt instanceof AugmentEffectiveStatement augment) {
539 // FIXME: MDSAL-695: So here we are ignoring any augment which is not in a module, while the 'uses'
540 // processing takes care of the rest. There are two problems here:
542 // 1) this could be an augment introduced through uses -- in this case we are picking
543 // confusing it with this being its declaration site, we should probably be
544 // ignoring it, but then
546 // 2) we are losing track of AugmentEffectiveStatement for which we do not generate
547 // interfaces -- and recover it at runtime through explicit walk along the
548 // corresponding AugmentationSchemaNode.getOriginalDefinition() pointer
550 // So here is where we should decide how to handle this augment, and make sure we
551 // retain information about this being an alias. That will serve as the base for keys
552 // in the augment -> original map we provide to BindingRuntimeTypes.
553 if (this instanceof ModuleGenerator module) {
554 tmpAug.add(new ModuleAugmentGenerator(augment, module));
556 } else if (stmt instanceof UsesEffectiveStatement uses) {
557 for (var usesSub : uses.effectiveSubstatements()) {
558 if (usesSub instanceof AugmentEffectiveStatement usesAug) {
559 tmpAug.add(new UsesAugmentGenerator(usesAug, uses, this));
563 LOG.trace("Ignoring statement {}", stmt);
567 // Sort augments and add them last. This ensures child iteration order always reflects potential
568 // interdependencies, hence we do not need to worry about them. This is extremely important, as there are a
569 // number of places where we would have to either move the logic to parent statement and explicitly filter/sort
570 // substatements to establish this order.
571 tmpAug.sort(AbstractAugmentGenerator.COMPARATOR);
574 // Compatibility FooService and FooListener interfaces, only generated for modules.
575 if (this instanceof ModuleGenerator moduleGen) {
576 final List<NotificationGenerator> notifs = tmp.stream()
577 .filter(NotificationGenerator.class::isInstance)
578 .map(NotificationGenerator.class::cast)
579 .collect(Collectors.toUnmodifiableList());
580 if (!notifs.isEmpty()) {
581 tmp.add(new NotificationServiceGenerator(moduleGen, notifs));
584 final List<RpcGenerator> rpcs = tmp.stream()
585 .filter(RpcGenerator.class::isInstance)
586 .map(RpcGenerator.class::cast)
587 .collect(Collectors.toUnmodifiableList());
588 if (!rpcs.isEmpty()) {
589 tmp.add(new RpcServiceGenerator(moduleGen, rpcs));
593 return List.copyOf(tmp);
596 // Utility equivalent of (!isAddedByUses(stmt) && !isAugmenting(stmt)). Takes advantage of relationship between
597 // CopyableNode and AddedByUsesAware
598 private static boolean isOriginalDeclaration(final EffectiveStatement<?, ?> stmt) {
599 if (stmt instanceof AddedByUsesAware aware) {
600 if (aware.isAddedByUses()
601 || stmt instanceof CopyableNode copyable && copyable.isAugmenting()) {
608 private static boolean isAddedByUses(final EffectiveStatement<?, ?> stmt) {
609 return stmt instanceof AddedByUsesAware aware && aware.isAddedByUses();
612 private static boolean isAugmenting(final EffectiveStatement<?, ?> stmt) {
613 return stmt instanceof CopyableNode copyable && copyable.isAugmenting();