cowwoc commented on code in PR #389: URL: https://github.com/apache/maven-build-cache-extension/pull/389#discussion_r3608969184
########## src/main/java/org/apache/maven/buildcache/xml/PluginParameterLoader.java: ########## @@ -0,0 +1,271 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.maven.buildcache.xml; + +import javax.xml.parsers.DocumentBuilder; +import javax.xml.parsers.DocumentBuilderFactory; + +import java.io.InputStream; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; + +import org.apache.maven.buildcache.xml.PluginParameterDefinition.GoalParameterDefinition; +import org.apache.maven.buildcache.xml.PluginParameterDefinition.ParameterDefinition; +import org.apache.maven.buildcache.xml.PluginParameterDefinition.ParameterType; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.w3c.dom.Document; +import org.w3c.dom.Element; +import org.w3c.dom.NodeList; + +/** + * Loads plugin parameter definitions from classpath resources. + * Definitions are stored in src/main/resources/plugin-parameters/{artifactId}.xml + */ +public class PluginParameterLoader { + + private static final Logger LOGGER = LoggerFactory.getLogger(PluginParameterLoader.class); + private static final String PARAMETER_DIR = "plugin-parameters/"; + + private final Map<String, PluginParameterDefinition> definitions = new ConcurrentHashMap<>(); + + /** + * Load parameter definitions for a plugin by artifact ID only (no version matching) + */ + public PluginParameterDefinition load(String artifactId) { + return load(artifactId, null); + } + + /** + * Load parameter definitions for a plugin by artifact ID and version. + * If version is provided, finds the best matching definition (highest minVersion <= actual version). + * If version is null, returns any definition for the artifactId. + */ + public PluginParameterDefinition load(String artifactId, String pluginVersion) { + String cacheKey = artifactId + (pluginVersion != null ? ":" + pluginVersion : ""); + + if (definitions.containsKey(cacheKey)) { + return definitions.get(cacheKey); + } + + String resourcePath = PARAMETER_DIR + artifactId + ".xml"; + InputStream is = getClass().getClassLoader().getResourceAsStream(resourcePath); + + if (is == null) { + LOGGER.debug("No parameter definition found for plugin: {}", artifactId); + return null; + } + + try { + java.util.List<PluginParameterDefinition> allDefinitions = parseDefinitions(is, artifactId); + + PluginParameterDefinition bestMatch = findBestMatch(allDefinitions, pluginVersion); + + if (bestMatch != null) { + definitions.put(cacheKey, bestMatch); + LOGGER.info( + "Loaded parameter definition for {}:{} (minVersion: {}): {} goals, {} total parameters", + artifactId, + pluginVersion != null ? pluginVersion : "any", + bestMatch.getMinVersion() != null ? bestMatch.getMinVersion() : "none", + bestMatch.getGoals().size(), + bestMatch.getGoals().values().stream() + .mapToInt(g -> g.getParameters().size()) + .sum()); Review Comment: Addressed in 25e09ea: the parameter-definition load message now uses this log level: ```text DEBUG ``` ########## src/main/resources/plugin-parameters/maven-compiler-plugin.xml: ########## @@ -0,0 +1,327 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<plugin xmlns="http://maven.apache.org/PLUGIN-PARAMETERS/1.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/PLUGIN-PARAMETERS/1.0.0 plugin-parameters.xsd"> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-compiler-plugin</artifactId> + <minVersion>3.11.0</minVersion> + + <goals> + <goal> + <name>compile</name> + <parameters> + <!-- FUNCTIONAL: Affect compiled bytecode or compilation behavior --> + <parameter> + <name>source</name> + <type>functional</type> + <description>Source JDK version for compilation</description> + </parameter> + <parameter> + <name>target</name> + <type>functional</type> + <description>Target JDK version for compiled bytecode</description> + </parameter> + <parameter> + <name>release</name> + <type>functional</type> + <description>JDK release version (combines source and target)</description> + </parameter> + <parameter> + <name>encoding</name> + <type>functional</type> + <description>Source file encoding</description> + </parameter> + <parameter> + <name>debug</name> + <type>functional</type> + <description>Include debugging information in compiled bytecode</description> + </parameter> + <parameter> + <name>debuglevel</name> + <type>functional</type> + <description>Level of debugging information (lines, vars, source)</description> + </parameter> + <parameter> + <name>optimize</name> + <type>functional</type> + <description>Optimize compiled bytecode</description> + </parameter> + <parameter> + <name>compilerArgs</name> + <type>functional</type> + <description>Additional compiler arguments</description> + </parameter> + <parameter> + <name>compilerArgument</name> + <type>functional</type> + <description>Single additional compiler argument</description> + </parameter> + <parameter> + <name>annotationProcessorPaths</name> + <type>functional</type> + <description>Classpath for annotation processors</description> + </parameter> + <parameter> + <name>annotationProcessors</name> + <type>functional</type> + <description>Annotation processors to run</description> + </parameter> + <parameter> + <name>proc</name> + <type>functional</type> + <description>Annotation processing mode (none, only, proc)</description> + </parameter> + <parameter> + <name>executable</name> + <type>functional</type> + <description>Path to javac executable (different compiler may produce different output)</description> + </parameter> + <parameter> + <name>parameters</name> + <type>functional</type> + <description>Generate metadata for method parameters</description> + </parameter> + <parameter> + <name>enablePreview</name> + <type>functional</type> + <description>Enable preview features</description> + </parameter> + + <!-- BEHAVIORAL: Affect how compilation runs but not the output --> Review Comment: Addressed in 25e09ea: the XML comment now states that: ```text behavioral ``` parameters are the default and output-affecting exceptions are marked: ```text FUNCTIONAL ``` ########## src/site/markdown/how-to.md: ########## @@ -169,6 +169,175 @@ Add `executionControl/runAlways` section: </executionControl> ``` +### Default Reconciliation Behavior + +The build cache extension automatically tracks certain critical plugin properties by default, even without explicit +`executionControl` configuration. These defaults are derived from plugin parameter descriptors under +`plugin-parameters/`: + +* **maven-compiler-plugin** (`compile` and `testCompile` goals): Tracks functional parameters defined in + `plugin-parameters/maven-compiler-plugin.xml` +* **maven-install-plugin** (`install` and `install-file` goals): Tracks functional parameters defined in + `plugin-parameters/maven-install-plugin.xml` + +This default behavior prevents common cache invalidation issues, particularly in multi-module JPMS (Java Platform Module System) +projects where compiler version changes can cause compilation failures. + +**Overriding Defaults:** When you explicitly configure `executionControl` for a plugin, your explicit configuration completely +overrides the defaults for that plugin. For example, to track only the `release` property for maven-compiler-plugin instead +of the functional parameters from `plugin-parameters/maven-compiler-plugin.xml`: + +```xml +<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.2.0";> + <configuration> + ... + </configuration> + <executionControl> + <reconcile> + <plugins> + <plugin artifactId="maven-compiler-plugin" goal="compile"> + <reconciles> + <reconcile propertyName="release"/> + </reconciles> + </plugin> + </plugins> + </reconcile> + </executionControl> +</cache> +``` + +This configuration in your `.mvn/maven-build-cache-config.xml` file replaces the built-in defaults. You can also define +reconciliation configurations for plugins that don't have built-in defaults using the same syntax. + +### Parameter Validation and Categorization + +The build cache extension includes a parameter validation system that categorizes plugin parameters and validates +reconciliation configurations against known parameter definitions. + +#### Parameter Categories + +All plugin parameters are categorized into two types: + +* **Functional Parameters**: Affect the compiled output or build artifacts (e.g., `source`, `target`, `release`, `encoding`) +* **Behavioral Parameters**: Affect how the build runs but not the output (e.g., `verbose`, `fork`, `maxmem`, `skip`) + +Only **functional** parameters should be tracked in reconciliation configurations, as behavioral parameters don't affect +the build output and shouldn't invalidate the cache. + +#### Validation Features + +The extension automatically validates reconciliation configurations and logs warnings/errors for: + +* **Unknown parameters**: Parameters not defined in the plugin's parameter definition (ERROR level) Review Comment: Addressed in ea9634b: the documentation now uses this log level: ```text WARN ``` It matches the logging call in: ```java CacheConfigImpl.validateReconciliationConfig() ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
