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.Preconditions.checkState;
11 import static com.google.common.base.Verify.verify;
12 import static com.google.common.base.Verify.verifyNotNull;
13 import static java.util.Objects.requireNonNull;
15 import com.google.common.base.Stopwatch;
16 import com.google.common.base.VerifyException;
17 import com.google.common.collect.Maps;
18 import java.util.ArrayDeque;
19 import java.util.ArrayList;
20 import java.util.Deque;
21 import java.util.Iterator;
22 import java.util.List;
24 import java.util.function.Function;
25 import java.util.stream.Collectors;
26 import org.eclipse.jdt.annotation.NonNull;
27 import org.eclipse.jdt.annotation.Nullable;
28 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
29 import org.opendaylight.mdsal.binding.model.api.JavaTypeName;
30 import org.opendaylight.mdsal.binding.model.api.Type;
31 import org.opendaylight.yangtools.concepts.Mutable;
32 import org.opendaylight.yangtools.yang.binding.ChildOf;
33 import org.opendaylight.yangtools.yang.binding.ChoiceIn;
34 import org.opendaylight.yangtools.yang.common.QName;
35 import org.opendaylight.yangtools.yang.common.QNameModule;
36 import org.opendaylight.yangtools.yang.model.api.EffectiveModelContext;
37 import org.opendaylight.yangtools.yang.model.api.PathExpression;
38 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
39 import org.opendaylight.yangtools.yang.model.api.stmt.ModuleEffectiveStatement;
40 import org.opendaylight.yangtools.yang.model.ri.type.TypeBuilder;
41 import org.opendaylight.yangtools.yang.model.spi.ModuleDependencySort;
42 import org.opendaylight.yangtools.yang.model.util.SchemaInferenceStack;
43 import org.slf4j.Logger;
44 import org.slf4j.LoggerFactory;
47 * A multi-stage reactor for generating {@link GeneratedType} instances from an {@link EffectiveModelContext}.
50 * The reason for multi-stage processing is that the problem ahead of us involves:
52 * <li>mapping {@code typedef} and restricted {@code type} statements onto Java classes</li>
53 * <li>mapping a number of schema tree nodes into Java interfaces with properties</li>
54 * <li>taking advantage of Java composition to provide {@code grouping} mobility</li>
57 public final class GeneratorReactor extends GeneratorContext implements Mutable {
64 private static final Logger LOG = LoggerFactory.getLogger(GeneratorReactor.class);
66 private final Deque<Iterable<? extends Generator>> stack = new ArrayDeque<>();
67 private final @NonNull Map<QNameModule, ModuleGenerator> generators;
68 private final @NonNull List<ModuleGenerator> children;
69 private final @NonNull SchemaInferenceStack inferenceStack;
71 private State state = State.INITIALIZED;
73 public GeneratorReactor(final EffectiveModelContext context) {
74 inferenceStack = SchemaInferenceStack.of(context);
76 // Construct modules and their subtrees. Dependency sort is very much needed here, as it establishes order of
77 // module evaluation, and that (along with the sort in AbstractCompositeGenerator) ensures we visit
78 // AugmentGenerators without having forward references.
79 // FIXME: migrate to new ModuleDependencySort when it is available, which streamline things here
80 children = ModuleDependencySort.sort(context.getModules()).stream()
82 verify(module instanceof ModuleEffectiveStatement, "Unexpected module %s", module);
83 return new ModuleGenerator((ModuleEffectiveStatement) module);
85 .collect(Collectors.toUnmodifiableList());
86 generators = Maps.uniqueIndex(children, gen -> gen.statement().localQNameModule());
90 * Execute the reactor. Execution follows the following steps:
92 * <li>link the statement inheritance graph along {@code uses}/{@code grouping} statements</li>
93 * <li>link the {@code typedef} inheritance hierarchy by visiting all {@link TypedefGenerator}s and memoizing the
94 * {@code type} lookup</li>
95 * <li>link the {@code identity} inheritance hierarchy by visiting all {@link IdentityGenerator}s and memoizing
96 * the {@code base} lookup</li>
97 * <li>link the {@code type} statements and resolve type restriction hierarchy, determining the set of Java
98 classes required for Java equivalent of effective YANG type definitions</li>
99 * <li>bind {@code leafref} and {@code identityref} references to their Java class roots</li>
100 * <li>resolve {@link ChoiceIn}/{@link ChildOf} hierarchy</li>
101 * <li>assign Java package names and {@link JavaTypeName}s to all generated classes</li>
102 * <li>create {@link Type} instances</li>
105 * @param builderFactory factory for creating {@link TypeBuilder}s for resulting types
106 * @return Resolved generators
107 * @throws IllegalStateException if the reactor has failed execution
108 * @throws NullPointerException if {@code builderFactory} is {@code null}
110 public @NonNull Map<QNameModule, ModuleGenerator> execute(final TypeBuilderFactory builderFactory) {
113 state = State.EXECUTING;
118 throw new IllegalStateException("Cannot resume partial execution");
120 throw new IllegalStateException("Unhandled state" + state);
123 // Start measuring time...
124 final Stopwatch sw = Stopwatch.createStarted();
126 // Step 1a: Walk all composite generators and resolve 'uses' statements to the corresponding grouping generator,
127 // establishing implied inheritance. During this walk we maintain 'stack' to aid this process.
128 // This indirectly triggers resolution of UsesAugmentGenerators' targets by hooking a requirement
129 // on the resolved grouping's child nodes as needed.
130 linkUsesDependencies(children);
132 // Step 1b: Walk all module generators and start ModuleAugmentGenerators' target resolution by linking the first
133 // step of each 'augment' statement to its corresponding instantiated site.
134 // Then start all UsesAugmentGenerators' target resolution.
135 final var augments = new ArrayList<AugmentRequirement>();
136 for (ModuleGenerator module : children) {
137 for (Generator gen : module) {
138 if (gen instanceof ModuleAugmentGenerator) {
139 augments.add(((ModuleAugmentGenerator) gen).startLinkage(this));
143 for (ModuleGenerator module : children) {
144 module.startUsesAugmentLinkage(augments);
146 LOG.trace("Processing linkage of {} augment generators", augments.size());
148 // Step 1c: ... finally establish linkage along the reverse uses/augment axis. This is needed to route generated
149 // type manifestations (isAddedByUses/isAugmenting) to their type generation sites. Since generator
150 // tree iteration order does not match dependencies, we may need to perform multiple passes.
151 for (ModuleGenerator module : children) {
152 verify(module.linkOriginalGenerator(), "Module %s failed to link", module);
155 final var unlinkedModules = new ArrayList<>(children);
157 final boolean progress =
158 progressAndClean(unlinkedModules, ModuleGenerator::linkOriginalGeneratorRecursive)
159 // not '||' because we need the side-effects, which would get short-circuited
160 | progressAndClean(augments, AugmentRequirement::resolve);
162 if (augments.isEmpty() && unlinkedModules.isEmpty()) {
167 final var ex = new VerifyException("Failed to make progress on linking of original generators");
168 for (var augment : augments) {
169 ex.addSuppressed(new IllegalStateException(augment + " is incomplete"));
171 for (var module : unlinkedModules) {
172 ex.addSuppressed(new IllegalStateException(module + " remains unlinked"));
179 * Step 2: link typedef statements, so that typedef's 'type' axis is fully established
180 * Step 3: link all identity statements, so that identity's 'base' axis is fully established
181 * Step 4: link all type statements, so that leafs and leaf-lists have restrictions established
183 * Since our implementation class hierarchy captures all four statements involved in a common superclass, we can
184 * perform this in a single pass.
186 linkDependencies(children);
188 // Step five: resolve all 'type leafref' and 'type identityref' statements, so they point to their
189 // corresponding Java type representation.
190 bindTypeDefinition(children);
192 // Step six: walk all composite generators and link ChildOf/ChoiceIn relationships with parents. We have taken
193 // care of this step during tree construction, hence this now a no-op.
196 * Step seven: assign java packages and JavaTypeNames
198 * This is a really tricky part, as we have large number of factors to consider:
199 * - we are mapping grouping, typedef, identity and schema tree namespaces into Fully Qualified Class Names,
200 * i.e. four namespaces into one
201 * - our source of class naming are YANG identifiers, which allow characters not allowed by Java
202 * - we generate class names as well as nested package hierarchy
203 * - we want to generate names which look like Java as much as possible
204 * - we need to always have an (arbitrarily-ugly) fail-safe name
206 * To deal with all that, we split this problem into multiple manageable chunks.
208 * The first chunk is here: we walk all generators and ask them to do two things:
209 * - instantiate their CollisionMembers and link them to appropriate CollisionDomains
210 * - return their collision domain
212 * Then we process we ask collision domains until all domains are resolved, driving the second chunk of the
213 * algorithm in CollisionDomain. Note that we may need to walk the domains multiple times, as the process of
214 * solving a domain may cause another domain's solution to be invalidated.
216 final List<CollisionDomain> domains = new ArrayList<>();
217 collectCollisionDomains(domains, children);
218 boolean haveUnresolved;
220 haveUnresolved = false;
221 for (CollisionDomain domain : domains) {
222 if (domain.findSolution()) {
223 haveUnresolved = true;
226 } while (haveUnresolved);
228 // Step eight: generate actual Types
230 // We have now properly cross-linked all generators and have assigned their naming roots, so from this point
231 // it looks as though we are performing a simple recursive execution. In reality, though, the actual path taken
232 // through generators is dictated by us as well as generator linkage.
233 for (ModuleGenerator module : children) {
234 module.ensureType(builderFactory);
237 LOG.debug("Processed {} modules in {}", generators.size(), sw);
238 state = State.FINISHED;
242 private void collectCollisionDomains(final List<CollisionDomain> result,
243 final Iterable<? extends Generator> parent) {
244 for (Generator gen : parent) {
246 collectCollisionDomains(result, gen);
247 if (gen instanceof AbstractCompositeGenerator) {
248 result.add(((AbstractCompositeGenerator<?>) gen).domain());
254 <E extends EffectiveStatement<QName, ?>, G extends AbstractExplicitGenerator<E>> G resolveTreeScoped(
255 final Class<G> type, final QName argument) {
256 LOG.trace("Searching for tree-scoped argument {} at {}", argument, stack);
258 // Check if the requested QName matches current module, if it does search the stack
259 final Iterable<? extends Generator> last = stack.getLast();
260 verify(last instanceof ModuleGenerator, "Unexpected last stack item %s", last);
262 if (argument.getModule().equals(((ModuleGenerator) last).statement().localQNameModule())) {
263 for (Iterable<? extends Generator> ancestor : stack) {
264 for (Generator child : ancestor) {
265 if (type.isInstance(child)) {
266 final G cast = type.cast(child);
267 if (argument.equals(cast.statement().argument())) {
268 LOG.trace("Found matching {}", child);
275 final ModuleGenerator module = generators.get(argument.getModule());
276 if (module != null) {
277 for (Generator child : module) {
278 if (type.isInstance(child)) {
279 final G cast = type.cast(child);
280 if (argument.equals(cast.statement().argument())) {
281 LOG.trace("Found matching {}", child);
289 throw new IllegalStateException("Could not find " + type + " argument " + argument + " in " + stack);
293 ModuleGenerator resolveModule(final QNameModule namespace) {
294 final ModuleGenerator module = generators.get(requireNonNull(namespace));
295 checkState(module != null, "Failed to find module for %s", namespace);
300 AbstractTypeObjectGenerator<?> resolveLeafref(final PathExpression path) {
301 LOG.trace("Resolving path {}", path);
302 verify(inferenceStack.isEmpty(), "Unexpected data tree state %s", inferenceStack);
304 // Populate inferenceStack with a grouping + data tree equivalent of current stack's state.
305 final Iterator<Iterable<? extends Generator>> it = stack.descendingIterator();
306 // Skip first item, as it points to our children
307 verify(it.hasNext(), "Unexpected empty stack");
310 while (it.hasNext()) {
311 final Iterable<? extends Generator> item = it.next();
312 verify(item instanceof Generator, "Unexpected stack item %s", item);
313 ((Generator) item).pushToInference(inferenceStack);
316 return inferenceStack.inGrouping() ? lenientResolveLeafref(path) : strictResolvePath(path);
318 inferenceStack.clear();
322 private @NonNull AbstractTypeAwareGenerator<?> strictResolvePath(final @NonNull PathExpression path) {
324 inferenceStack.resolvePathExpression(path);
325 } catch (IllegalArgumentException e) {
326 throw new IllegalArgumentException("Failed to find leafref target " + path.getOriginalString(), e);
328 return mapToGenerator();
331 private @Nullable AbstractTypeAwareGenerator<?> lenientResolveLeafref(final @NonNull PathExpression path) {
333 inferenceStack.resolvePathExpression(path);
334 } catch (IllegalArgumentException e) {
335 LOG.debug("Ignoring unresolved path {}", path, e);
338 return mapToGenerator();
341 // Map a statement to the corresponding generator
342 private @NonNull AbstractTypeAwareGenerator<?> mapToGenerator() {
343 // Some preliminaries first: we need to be in the correct module to walk the path
344 final ModuleEffectiveStatement module = inferenceStack.currentModule();
345 final ModuleGenerator gen = verifyNotNull(generators.get(module.localQNameModule()),
346 "Cannot find generator for %s", module);
348 // Now kick of the search
349 final List<EffectiveStatement<?, ?>> stmtPath = inferenceStack.toInference().statementPath();
350 final AbstractExplicitGenerator<?> found = gen.findGenerator(stmtPath);
351 if (found instanceof AbstractTypeAwareGenerator) {
352 return (AbstractTypeAwareGenerator<?>) found;
354 throw new VerifyException("Statements " + stmtPath + " resulted in unexpected " + found);
357 // Note: unlike other methods, this method pushes matching child to the stack
358 private void linkUsesDependencies(final Iterable<? extends Generator> parent) {
359 for (Generator child : parent) {
360 if (child instanceof AbstractCompositeGenerator) {
361 LOG.trace("Visiting composite {}", child);
362 final AbstractCompositeGenerator<?> composite = (AbstractCompositeGenerator<?>) child;
363 stack.push(composite);
364 composite.linkUsesDependencies(this);
365 linkUsesDependencies(composite);
371 private static <T> boolean progressAndClean(final List<T> items, final Function<T, LinkageProgress> function) {
372 boolean progress = false;
374 final var it = items.iterator();
375 while (it.hasNext()) {
376 final var item = it.next();
377 final var tmp = function.apply(item);
378 if (tmp == LinkageProgress.NONE) {
379 LOG.debug("No progress made linking {}", item);
384 if (tmp == LinkageProgress.DONE) {
385 LOG.debug("Finished linking {}", item);
388 LOG.debug("Progress made linking {}", item);
395 private void linkDependencies(final Iterable<? extends Generator> parent) {
396 for (Generator child : parent) {
397 if (child instanceof AbstractDependentGenerator) {
398 ((AbstractDependentGenerator<?>) child).linkDependencies(this);
399 } else if (child instanceof AbstractCompositeGenerator) {
401 linkDependencies(child);
407 private void bindTypeDefinition(final Iterable<? extends Generator> parent) {
408 for (Generator child : parent) {
410 if (child instanceof AbstractTypeObjectGenerator) {
411 ((AbstractTypeObjectGenerator<?>) child).bindTypeDefinition(this);
412 } else if (child instanceof AbstractCompositeGenerator) {
413 bindTypeDefinition(child);