From 6800df576ad05a975ef10a7dfd423ee2b1fa1b31 Mon Sep 17 00:00:00 2001 From: Alexey Loubyansky Date: Fri, 17 Mar 2023 13:14:52 +0100 Subject: [PATCH] A bit of javadoc for codegen and path tree API Co-authored-by: Peter Palaga --- .../io/quarkus/deployment/CodeGenContext.java | 61 +++++++++++++++++ .../quarkus/deployment/CodeGenProvider.java | 6 +- .../deployment/codegen/CodeGenData.java | 16 +++++ .../bootstrap/model/ApplicationModel.java | 67 ++++++++++++++++++- .../java/io/quarkus/paths/PathTreeVisit.java | 7 +- .../main/java/io/quarkus/paths/PathVisit.java | 35 ++++++++++ .../java/io/quarkus/paths/PathVisitor.java | 12 ++++ 7 files changed, 196 insertions(+), 8 deletions(-) diff --git a/core/deployment/src/main/java/io/quarkus/deployment/CodeGenContext.java b/core/deployment/src/main/java/io/quarkus/deployment/CodeGenContext.java index f18250f76f55f9..c1543c31ec1905 100644 --- a/core/deployment/src/main/java/io/quarkus/deployment/CodeGenContext.java +++ b/core/deployment/src/main/java/io/quarkus/deployment/CodeGenContext.java @@ -6,6 +6,9 @@ import io.quarkus.bootstrap.model.ApplicationModel; +/** + * Code generation context + */ public class CodeGenContext { private final ApplicationModel model; private final Path outDir; @@ -15,6 +18,17 @@ public class CodeGenContext { private final Config config; private final boolean test; + /** + * Creates a code generation context + * + * @param model application model + * @param outDir target directory for the generated output + * @param workDir working directory, typically the main build directory of the project + * @param inputDir directory containing input content for a code generator + * @param redirectIO whether the code generating process should redirect its IO + * @param config application build time configuration + * @param test indicates whether the code generation is being triggered for tests + */ public CodeGenContext(ApplicationModel model, Path outDir, Path workDir, Path inputDir, boolean redirectIO, Config config, boolean test) { this.model = model; @@ -26,30 +40,77 @@ public CodeGenContext(ApplicationModel model, Path outDir, Path workDir, Path in this.test = test; } + /** + * Application model + * + * @return application model + */ public ApplicationModel applicationModel() { return model; } + /** + * Target directory for the generated output. + * The directory would typically be resolved as {@code /generated-sources/}, + * where {@code would match the value of {@link CodeGenProvider#providerId()}. + * For example, for a code gen provider {@code foo}, the output directory in a typical Maven project would be + * {@code target/generated-sources/foo}. + * + * @return target directory for the generated output + */ public Path outDir() { return outDir; } + /** + * Working directory, typically the main build directory of the project. + * For a typical Maven project it would be the {@code target} directory. + * + * @return working directory, typically the main build directory of the project + */ public Path workDir() { return workDir; } + /** + * Directory containing input content for a code generator. + * For the main application build of a typical Maven project the input sources directory + * would be {@code /src/main/}, while for the tests it would be + * {@code /src/test/}, where {@code foo, src/main/foo for application and src/test/foo for test resources + * Name of the directory containing input files for a given {@link CodeGenProvider} implementation + * relative to a sources root directory. For example, if an input directory is configured as foo, + * for a production build of an application the sources will be looked up at src/main/foo path + * and at src/test/foo for tests. * * @return the input directory */ diff --git a/core/deployment/src/main/java/io/quarkus/deployment/codegen/CodeGenData.java b/core/deployment/src/main/java/io/quarkus/deployment/codegen/CodeGenData.java index 32f19b984e52d8..ac2e04f98088a8 100644 --- a/core/deployment/src/main/java/io/quarkus/deployment/codegen/CodeGenData.java +++ b/core/deployment/src/main/java/io/quarkus/deployment/codegen/CodeGenData.java @@ -4,6 +4,9 @@ import io.quarkus.deployment.CodeGenProvider; +/** + * Links a {@link CodeGenProvider} instance, an input and output directories for the provider. + */ public class CodeGenData { public final CodeGenProvider provider; public final Path outPath; @@ -11,10 +14,23 @@ public class CodeGenData { public final Path buildDir; public boolean redirectIO; + /** + * @param provider code gen provider + * @param outPath where the generated output should be stored + * @param sourceDir where the input sources are + * @param buildDir base project output directory + */ public CodeGenData(CodeGenProvider provider, Path outPath, Path sourceDir, Path buildDir) { this(provider, outPath, sourceDir, buildDir, true); } + /** + * @param provider code gen provider + * @param outPath where the generated output should be stored + * @param sourceDir where the input sources are + * @param buildDir base project output directory + * @param redirectIO whether to redirect IO, in case a provider is logging something + */ public CodeGenData(CodeGenProvider provider, Path outPath, Path sourceDir, Path buildDir, boolean redirectIO) { this.provider = provider; this.outPath = outPath; diff --git a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/model/ApplicationModel.java b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/model/ApplicationModel.java index 1f94f001c27649..2cb24beea18d09 100644 --- a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/model/ApplicationModel.java +++ b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/bootstrap/model/ApplicationModel.java @@ -1,7 +1,6 @@ package io.quarkus.bootstrap.model; import java.util.Collection; -import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.Set; @@ -13,31 +12,85 @@ import io.quarkus.maven.dependency.Dependency; import io.quarkus.maven.dependency.ResolvedDependency; +/** + * Application dependency model. Allows to explore application dependencies, + * Quarkus platforms found in the project configuration and Quarkus platform configuration properties. + */ public interface ApplicationModel { + /** + * Main application artifact + * + * @return main application artifact + */ ResolvedDependency getAppArtifact(); + /** + * All the dependencies of an application including runtime and build time dependencies. + * + * @return application runtime and build time dependencies + */ Collection getDependencies(); + /** + * Runtime dependencies of an application + * + * @return runtime dependencies of an application + */ default Collection getRuntimeDependencies() { return getDependencies().stream().filter(Dependency::isRuntimeCp).collect(Collectors.toList()); } + /** + * Quarkus platforms (BOMs) found in the configuration of an application + * + * @return Quarkus platforms (BOMs) found in the configuration of an application + */ PlatformImports getPlatforms(); + /** + * Quarkus platform configuration properties + * + * @return Quarkus platform configuration properties + */ default Map getPlatformProperties() { final PlatformImports platformImports = getPlatforms(); - return platformImports == null ? Collections.emptyMap() : platformImports.getPlatformProperties(); + return platformImports == null ? Map.of() : platformImports.getPlatformProperties(); } + /** + * Extension capability requirements collected from the extensions found on the classpath of an application + * + * @return Extension capability requirements collected from the extensions found on the classpath of an application + */ Collection getExtensionCapabilities(); + /** + * Class loading parent-first artifacts + * + * @return class loading parent-first artifacts + */ Set getParentFirst(); + /** + * Class loading runner parent-first artifacts + * + * @return class loading runner parent-first artifacts + */ Set getRunnerParentFirst(); + /** + * Class loading lower priority artifacts + * + * @return class loading lower priority artifacts + */ Set getLowerPriorityArtifacts(); + /** + * Local project dependencies that are live-reloadable in dev mode. + * + * @return local project dependencies that are live-reloadable in dev mode. + */ Set getReloadableWorkspaceDependencies(); /** @@ -47,10 +100,20 @@ default Map getPlatformProperties() { */ Map> getRemovedResources(); + /** + * Main workspace module of an application. Could be null, in case the project is not available during the build. + * + * @return main workspace module of an application, could be null, in case the project is not available during the build + */ default WorkspaceModule getApplicationModule() { return getAppArtifact().getWorkspaceModule(); } + /** + * All the workspace modules found as dependencies of an application + * + * @return all the workspace modules found as dependencies of an application + */ default Collection getWorkspaceModules() { final Map result = new HashMap<>(); collectModules(getAppArtifact().getWorkspaceModule(), result); diff --git a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java index 388f28ea0aefb6..27d466f1e5d4fb 100644 --- a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java +++ b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathTreeVisit.java @@ -4,7 +4,6 @@ import java.io.UncheckedIOException; import java.nio.file.Files; import java.nio.file.Path; -import java.util.Collections; import java.util.HashMap; import java.util.Iterator; import java.util.Map; @@ -35,7 +34,7 @@ static void walk(Path root, Path rootDir, PathFilter pathFilter, Map T process(Path root, Path rootDir, Path path, PathFilter pathFilter, Function func) { - final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Collections.emptyMap()); + final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Map.of()); if (visit.setCurrent(path)) { return func.apply(visit); } @@ -43,7 +42,7 @@ static T process(Path root, Path rootDir, Path path, PathFilter pathFilter, } static void consume(Path root, Path rootDir, Path path, PathFilter pathFilter, Consumer func) { - final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Collections.emptyMap()); + final PathTreeVisit visit = new PathTreeVisit(root, rootDir, pathFilter, Map.of()); if (visit.setCurrent(path)) { func.accept(visit); } else { @@ -64,7 +63,7 @@ private PathTreeVisit(Path root, Path rootDir, PathFilter pathFilter, Map(multiReleaseMapping); } diff --git a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisit.java b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisit.java index 261b7ef6c6716d..34081fc285a1c9 100644 --- a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisit.java +++ b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisit.java @@ -4,12 +4,34 @@ import java.net.URL; import java.nio.file.Path; +/** + * Provides context for a given path visit + */ public interface PathVisit { + /** + * The root of the path tree the current path belongs to. + * For a {@link PathTree} created for an archive, this will be the path to the archive file. + * For a {@link PathTree} created for a directory, this will be the path to the directory. + * + * @return root of the path tree the current path belongs to + */ Path getRoot(); + /** + * The path being visited. The {@link java.nio.file.FileSystem} the path belongs to + * will depend on the implementation of the {@link PathTree} being visited. For example, + * for an archive it will be a ZIP {@link java.nio.file.FileSystem} implementation. + * + * @return path being visited + */ Path getPath(); + /** + * {@link java.net.URL} that can be used to read the content of the path. + * + * @return URL that can be used to read the content of the path + */ default URL getUrl() { try { return getPath().toUri().toURL(); @@ -18,7 +40,20 @@ default URL getUrl() { } } + /** + * Path relative to the root of the tree as a string with a provided path element separator. + * For a {@link PathTree} created for an archive, the returned path will be relative to the root + * of the corresponding {@link java.nio.file.FileSystem} implementation. + * For a {@link PathTree} created for a directory, the returned path will be relative to the directory + * used as the root of the path tree. + * + * @param separator path element separator + * @return path relative to the root of the tree as a string with a provided path element separator + */ String getRelativePath(String separator); + /** + * Terminates walking over a {@link PathTree} after this visit. + */ void stopWalking(); } diff --git a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisitor.java b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisitor.java index 2ffbb2cf22148f..d06bb599b97d73 100644 --- a/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisitor.java +++ b/independent-projects/bootstrap/app-model/src/main/java/io/quarkus/paths/PathVisitor.java @@ -1,6 +1,18 @@ package io.quarkus.paths; +/** + * {@link PathTree} path visitor + */ public interface PathVisitor { + /** + * Called to visit a path when walking a path tree or when a caller + * requested to visit a specific path in a tree. In the latter case + * if the requested path does not exist, the {@code visit} argument + * will be null and it'll be up to the caller how to handle that, + * i.e. whether to throw a path not found exception or return silently. + * + * @param visit visit object or null, in case the requested path does not exist + */ void visitPath(PathVisit visit); }