Skip to content

Commit

Permalink
Config Doc - Only merge internal/common extensions in doc generation
Browse files Browse the repository at this point in the history 
When we attach the config metadata, we need to consider only the
properties of the current extension and not those from potential
internal/common extensions: these will be published for the
internal/common extensions themselves.
  • Loading branch information
@gsmet
gsmet committed Sep 13, 2024
1 parent 3e4c8d0 commit fe7d368
Show file tree
Hide file tree
Showing 5 changed files with 96 additions and 30 deletions.
35 changes: 33 additions & 2 deletions ...rc/main/java/io/quarkus/annotation/processor/documentation/config/merger/ModelMerger.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,29 @@ public static MergedModel mergeModel(List<Path> buildOutputDirectories) {
* target/ directories found in the parent directory scanned).
*/
public static MergedModel mergeModel(JavadocRepository javadocRepository, List<Path> buildOutputDirectories) {
return mergeModel(javadocRepository, buildOutputDirectories, false);
}

/**
* Merge all the resolved models obtained from a list of build output directories (e.g. in the case of Maven, the list of
* target/ directories found in the parent directory scanned).
*/
public static MergedModel mergeModel(List<Path> buildOutputDirectories, boolean mergeCommonOrInternalExtensions) {
return mergeModel(null, buildOutputDirectories, mergeCommonOrInternalExtensions);
}

/**
* Merge all the resolved models obtained from a list of build output directories (e.g. in the case of Maven, the list of
* target/ directories found in the parent directory scanned).
*/
public static MergedModel mergeModel(JavadocRepository javadocRepository, List<Path> buildOutputDirectories,
boolean mergeCommonOrInternalExtensions) {
// keyed on extension and then top level prefix
Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots = new HashMap<>();
// keyed on file name
Map<String, ConfigRoot> configRootsInSpecificFile = new TreeMap<>();
// keyed on extension
Map<Extension, List<ConfigSection>> generatedConfigSections = new TreeMap<>();
Map<Extension, List<ConfigSection>> generatedConfigSections = new HashMap<>();

for (Path buildOutputDirectory : buildOutputDirectories) {
Path resolvedModelPath = buildOutputDirectory.resolve(Outputs.QUARKUS_CONFIG_DOC_MODEL);
Expand Down Expand Up @@ -85,7 +102,8 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
continue;
}

Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(configRoot.getExtension(),
Map<ConfigRootKey, ConfigRoot> extensionConfigRoots = configRoots.computeIfAbsent(
normalizeExtension(configRoot.getExtension(), mergeCommonOrInternalExtensions),
e -> new TreeMap<>());

ConfigRootKey configRootKey = getConfigRootKey(javadocRepository, configRoot);
Expand All @@ -102,6 +120,7 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
}
}

// note that the configRoots are now sorted by extension name
configRoots = retainBestExtensionKey(configRoots);

for (Entry<Extension, Map<ConfigRootKey, ConfigRoot>> extensionConfigRootsEntry : configRoots.entrySet()) {
Expand All @@ -116,6 +135,18 @@ public static MergedModel mergeModel(JavadocRepository javadocRepository, List<P
return new MergedModel(configRoots, configRootsInSpecificFile, generatedConfigSections);
}

private static Extension normalizeExtension(Extension extension, boolean mergeCommonOrInternalExtensions) {
if (!mergeCommonOrInternalExtensions) {
return extension;
}

if (extension.commonOrInternal()) {
return extension.normalizeCommonOrInternal();
}

return extension;
}

private static Map<Extension, Map<ConfigRootKey, ConfigRoot>> retainBestExtensionKey(
Map<Extension, Map<ConfigRootKey, ConfigRoot>> configRoots) {
return configRoots.entrySet().stream().collect(Collectors.toMap(e -> {
Expand Down
39 changes: 37 additions & 2 deletions ...r/src/main/java/io/quarkus/annotation/processor/documentation/config/model/Extension.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,24 @@
import com.fasterxml.jackson.annotation.JsonIgnore;

public record Extension(String groupId, String artifactId, String name,
NameSource nameSource, boolean detected) implements Comparable<Extension> {
NameSource nameSource, boolean commonOrInternal, boolean detected) implements Comparable<Extension> {

private static final String ARTIFACT_COMMON_SUFFIX = "-common";
private static final String ARTIFACT_INTERNAL_SUFFIX = "-internal";

public static Extension of(String groupId, String artifactId, String name,
NameSource nameSource) {
boolean commonOrInternal = artifactId.endsWith(ARTIFACT_COMMON_SUFFIX) || artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX);
if (commonOrInternal) {
nameSource = nameSource == NameSource.EXTENSION_METADATA ? NameSource.EXTENSION_METADATA_COMMON_INTERNAL
: (nameSource == NameSource.POM_XML ? NameSource.POM_XML_COMMON_INTERNAL : nameSource);
}

return new Extension(groupId, artifactId, name, nameSource, commonOrInternal, true);
}

public static Extension createNotDetected() {
return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false);
return new Extension("not.detected", "not.detected", "Not detected", NameSource.NONE, false, false);
}

@Override
Expand Down Expand Up @@ -50,6 +64,27 @@ public boolean splitOnConfigRootDescription() {
return "io.quarkus".equals(groupId) && "quarkus-core".equals(artifactId);
}

@JsonIgnore
public Extension normalizeCommonOrInternal() {
if (!commonOrInternal()) {
return this;
}

String normalizedArtifactId = artifactId;
if (artifactId.endsWith(ARTIFACT_COMMON_SUFFIX)) {
normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_COMMON_SUFFIX.length());
}
if (artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX)) {
normalizedArtifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_INTERNAL_SUFFIX.length());
}

if (normalizedArtifactId.equals(artifactId)) {
return this;
}

return new Extension(groupId, normalizedArtifactId, name, nameSource, commonOrInternal, detected);
}

@Override
public int compareTo(Extension other) {
if (name != null && other.name != null) {
Expand Down
47 changes: 24 additions & 23 deletions core/processor/src/main/java/io/quarkus/annotation/processor/util/ExtensionUtil.java
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
package io.quarkus.annotation.processor.util;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Map;
import java.util.Optional;

import javax.annotation.processing.ProcessingEnvironment;
import javax.tools.Diagnostic.Kind;
import javax.tools.StandardLocation;
import javax.xml.XMLConstants;
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
Expand All @@ -19,14 +23,12 @@

public final class ExtensionUtil {

private static final String RUNTIME_MARKER_FILE = "META-INF/quarkus.properties";

private static final String ARTIFACT_DEPLOYMENT_SUFFIX = "-deployment";
private static final String ARTIFACT_COMMON_SUFFIX = "-common";
private static final String ARTIFACT_INTERNAL_SUFFIX = "-internal";
private static final String NAME_QUARKUS_PREFIX = "Quarkus - ";
private static final String NAME_RUNTIME_SUFFIX = " - Runtime";
private static final String NAME_DEPLOYMENT_SUFFIX = " - Deployment";
private static final String NAME_COMMON_SUFFIX = " - Common";
private static final String NAME_INTERNAL_SUFFIX = " - Internal";

private final ProcessingEnvironment processingEnv;
private final FilerUtil filerUtil;
Expand Down Expand Up @@ -111,27 +113,19 @@ private Extension getExtensionFromPom(Path pom, Document doc) {
return Extension.createNotDetected();
}

boolean commonOrInternal = false;
boolean runtime = isRuntime();

if (artifactId.endsWith(ARTIFACT_DEPLOYMENT_SUFFIX)) {
if (!runtime && artifactId.endsWith(ARTIFACT_DEPLOYMENT_SUFFIX)) {
artifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_DEPLOYMENT_SUFFIX.length());
}
if (artifactId.endsWith(ARTIFACT_COMMON_SUFFIX)) {
artifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_COMMON_SUFFIX.length());
commonOrInternal = true;
}
if (artifactId.endsWith(ARTIFACT_INTERNAL_SUFFIX)) {
artifactId = artifactId.substring(0, artifactId.length() - ARTIFACT_INTERNAL_SUFFIX.length());
commonOrInternal = true;
}

NameSource nameSource;
Optional<String> nameFromExtensionMetadata = getExtensionNameFromExtensionMetadata();
if (nameFromExtensionMetadata.isPresent()) {
name = nameFromExtensionMetadata.get();
nameSource = commonOrInternal ? NameSource.EXTENSION_METADATA_COMMON_INTERNAL : NameSource.EXTENSION_METADATA;
nameSource = NameSource.EXTENSION_METADATA;
} else if (name != null) {
nameSource = commonOrInternal ? NameSource.POM_XML_COMMON_INTERNAL : NameSource.POM_XML;
nameSource = NameSource.POM_XML;
} else {
nameSource = NameSource.NONE;
}
Expand All @@ -140,18 +134,15 @@ private Extension getExtensionFromPom(Path pom, Document doc) {
if (name.startsWith(NAME_QUARKUS_PREFIX)) {
name = name.substring(NAME_QUARKUS_PREFIX.length()).trim();
}
if (name.endsWith(NAME_DEPLOYMENT_SUFFIX)) {
if (!runtime && name.endsWith(NAME_DEPLOYMENT_SUFFIX)) {
name = name.substring(0, name.length() - NAME_DEPLOYMENT_SUFFIX.length());
} else if (name.endsWith(NAME_RUNTIME_SUFFIX)) {
}
if (runtime && name.endsWith(NAME_RUNTIME_SUFFIX)) {
name = name.substring(0, name.length() - NAME_RUNTIME_SUFFIX.length());
} else if (name.endsWith(NAME_COMMON_SUFFIX)) {
name = name.substring(0, name.length() - NAME_COMMON_SUFFIX.length());
} else if (name.endsWith(NAME_INTERNAL_SUFFIX)) {
name = name.substring(0, name.length() - NAME_INTERNAL_SUFFIX.length());
}
}

return new Extension(groupId, artifactId, name, nameSource, true);
return Extension.of(groupId, artifactId, name, nameSource);
}

private Optional<String> getExtensionNameFromExtensionMetadata() {
Expand All @@ -168,4 +159,14 @@ private Optional<String> getExtensionNameFromExtensionMetadata() {

return Optional.of(extensionName.trim());
}

private boolean isRuntime() {
try {
Path runtimeMarkerFile = Paths
.get(processingEnv.getFiler().getResource(StandardLocation.CLASS_OUTPUT, "", RUNTIME_MARKER_FILE).toUri());
return Files.exists(runtimeMarkerFile);
} catch (IOException e) {
return false;
}
}
}
2 changes: 1 addition & 1 deletion ...fig-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/GenerateConfigDocMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ public void execute() throws MojoExecutionException, MojoFailureException {
List<Path> targetDirectories = findTargetDirectories(resolvedScanDirectory);

JavadocRepository javadocRepository = JavadocMerger.mergeJavadocElements(targetDirectories);
MergedModel mergedModel = ModelMerger.mergeModel(javadocRepository, targetDirectories);
MergedModel mergedModel = ModelMerger.mergeModel(javadocRepository, targetDirectories, true);

Format normalizedFormat = Format.normalizeFormat(format);

Expand Down
3 changes: 1 addition & 2 deletions ...rc/main/java/io/quarkus/maven/extension/deployment/metadata/AttachConfigMetadataMojo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,8 +222,7 @@ private List<Path> getMetaInfDirectories() {
private Extension getExtension() {
return new Extension(project.getGroupId(),
project.getArtifactId().substring(0, project.getArtifactId().length() - DEPLOYMENT_ARTIFACT_SUFFIX.length()),
null,
NameSource.NONE, true);
null, NameSource.NONE, false, true);
}

private String getJavadoc(JavadocRepository javadocRepository, String sourceType, String sourceElementName) {
Expand Down

0 comments on commit fe7d368

Please sign in to comment.