From 4f2aae0c4886a8b760365b81c4f0fa84182e7d6a Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Sun, 11 Aug 2024 16:12:44 +0200 Subject: [PATCH 1/3] Add a element in the model. Properties are: - directory (inherited from FileSet) - includes (inherited from PatternSet) - excludes (inherited from PatternSet) - scope - lang - module - targetVersion - targetPath (taken from ) - filtering (taken from ) - enabled This commit also renames `source` parameter value in `reader-stax.vm` for avoiding name collision with the new `Source` model element. https://github.com/apache/maven/pull/1936 --- api/maven-api-model/src/main/mdo/maven.mdo | 192 +++++++++++++++++++++ src/mdo/reader-stax.vm | 44 ++--- 2 files changed, 214 insertions(+), 22 deletions(-) diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo index 2829ffdc225b..4a9c05f77e30 100644 --- a/api/maven-api-model/src/main/mdo/maven.mdo +++ b/api/maven-api-model/src/main/mdo/maven.mdo @@ -775,6 +775,7 @@ String + resources 3.0.0+ @@ -789,6 +790,7 @@ + testResources 4.0.0+ @@ -857,6 +859,22 @@ + sources + 4.1.0+ + + All the sources to compile and resources files to copy for a project or it's unit tests. + The sources can be Java source files, generated source files, scripts or resources for examples. + Each source is specified by a mandatory {@code directory} element, which is relative to the POM. + The kind of sources (codes to compile or resources to copy) and their usage (for the main code + or for the tests) is specified by the {@code scope} element together with each source directory. + + + Source + * + + + + sourceDirectory 3.0.0+ true @@ -869,6 +887,7 @@ String + scriptSourceDirectory 4.0.0+ true @@ -882,6 +901,7 @@ String + testSourceDirectory 4.0.0+ true @@ -1945,6 +1965,178 @@ + Source + + etc.) and their + usage (main code, tests, etc.) is specified by the {@code scope} element. + +

Default source directories

+ If no source directories are specified, the defaults are {@code src/${scope}/${lang}} where + {@code ${scope}} is the value of the {@link #scope} element (typically {@code main} or {@code test}) and + {@code ${lang}} is the value of the {@link #lang} element (typically {@code java} or {@code resources}). + ]]> + + 4.1.0+ + FileSet + + + scope + 4.1.0+ + + The main scope is used for specifying a directory containing the source of the project. + The generated build system will compile the sources from this directory when the project is built. + The path given in the {@code directory} field is relative to the project descriptor. + The default directory for the default language (Java) is {@code "src/main/java"}.

+ +

The test scope is used for specifying a directory containing the unit test source of the project. + The generated build system will compile these directories when the project is being tested. + The path given in the {@code directory} field is relative to the project descriptor. + The default directory for the default language (Java) is {@code "src/test/java"}.

+ +

If no scope is specified, the default is {@code main}.

+ ]]> + + String + main + + + lang + 4.1.0+ + + JSON or XML). + +

The java language is used for specifying a directory containing the Java sources of the project. + The generated build system will compile the sources from this directory using the Java compiler when the + project is built. The path given in the {@code directory} field is relative to the project descriptor. + The default directory for the main Java sources is {@code "src/main/java"}.

+ +

The resources language is used for specifying a directory containing the class-path + or module-path resources such as properties files or scripts associated with a project. + This directory is meant to be different from the main source directory, + in that its contents will be copied to the output directory in most cases + (since scripts are interpreted rather than compiled). + The default directory for the main resources is {@code "src/main/resources"}.

+ +

If no language is specified, the default is {@code java}.

+ ]]> + + String + main + + + module + 4.1.0+ + + If a module name is specified for resources or script files, + then this value modifies the directory where the files will be copied. + For example, if a Java module name is "foo.biz", then the {@code foo/bar.properties} + resource file will be copied as {@code foo.biz/foo/bar.properties}.

+ +

This element can be combined with the {@code targetVersion} element for specifying sources, + scripts or resources that are specific to both a particular module and a target version.

+ ]]> + + String + + + targetVersion + 4.1.0+ + + JAR file will be created. + If this element is omitted, then the default target version is the compiler default value, + which is usually the version of the Java environment running Maven. + +

If a target version is specified for resources or script files, + then this value modifies the directory where the files will be copied. + For example, if {@code targetVersion} is 17, then the {@code foo/bar.properties} + resource file will be copied as {@code META-INF/versions/17/foo/bar.properties}.

+ +

This element can be combined with the {@code module} element for specifying sources, + scripts or resources that are specific to both a particular module and a target version.

+ ]]> + + String + + + targetPath + 4.1.0+ + + When a target path is explicitly specified, the values of the {@code module} and {@code targetVersion} + elements are not used for inferring the path (they are still used as compiler options however). + It means that for scripts and resources, the files below the path specified by {@code directory} + are copied to the path specified by {@code targetPath} with the exact same directory structure. + It is user's responsibility to put module and version components in the {@code targetPath} if needed.

+ +

Note that for Java source files, a directory with the module name may still be generated despite + above statement about {@code module} being ignored, because that directory is generated by the Java + compiler rather than Maven.

+ ]]> + + String + + + filtering + 4.1.0+ + + This filtering should not be confused with the filtering of paths done by the + {@code includes} and {@code excludes} patterns.

+ +

The default value is {@code false}.

+ ]]> + + boolean + false + + + enabled + 4.1.0+ + + The default value is {@code true}.

+ ]]> + + boolean + true + + + + + Resource This element describes all of the classpath resources associated with a project or unit tests. diff --git a/src/mdo/reader-stax.vm b/src/mdo/reader-stax.vm index 9850149d6918..96386d62f616 100644 --- a/src/mdo/reader-stax.vm +++ b/src/mdo/reader-stax.vm @@ -435,19 +435,19 @@ public class ${className} { * @return ${root.name} */ #if ( $locationTracking ) - public ${root.name} read(Reader reader, boolean strict, InputSource source) throws XMLStreamException { + public ${root.name} read(Reader reader, boolean strict, InputSource inputSrc) throws XMLStreamException { #else public ${root.name} read(Reader reader, boolean strict) throws XMLStreamException { #end #if ( $locationTracking ) - StreamSource streamSource = new StreamSource(reader, source != null ? source.getLocation() : null); + StreamSource streamSource = new StreamSource(reader, inputSrc != null ? inputSrc.getLocation() : null); #else StreamSource streamSource = new StreamSource(reader); #end XMLInputFactory factory = getXMLInputFactory(); XMLStreamReader parser = factory.createXMLStreamReader(streamSource); #if ( $locationTracking ) - return read(parser, strict, source); + return read(parser, strict, inputSrc); #else return read(parser, strict); #end @@ -471,19 +471,19 @@ public class ${className} { * @return ${root.name} */ #if ( $locationTracking ) - public ${root.name} read(InputStream in, boolean strict, InputSource source) throws XMLStreamException { + public ${root.name} read(InputStream in, boolean strict, InputSource inputSrc) throws XMLStreamException { #else public ${root.name} read(InputStream in, boolean strict) throws XMLStreamException { #end #if ( $locationTracking ) - StreamSource streamSource = new StreamSource(in, source != null ? source.getLocation() : null); + StreamSource streamSource = new StreamSource(in, inputSrc != null ? inputSrc.getLocation() : null); #else StreamSource streamSource = new StreamSource(in); #end XMLInputFactory factory = getXMLInputFactory(); XMLStreamReader parser = factory.createXMLStreamReader(streamSource); #if ( $locationTracking ) - return read(parser, strict, source); + return read(parser, strict, inputSrc); #else return read(parser, strict); #end @@ -499,7 +499,7 @@ public class ${className} { * @return ${root.name} */ #if ( $locationTracking ) - public ${root.name} read(XMLStreamReader parser, boolean strict, InputSource source) throws XMLStreamException { + public ${root.name} read(XMLStreamReader parser, boolean strict, InputSource inputSrc) throws XMLStreamException { #else public ${root.name} read(XMLStreamReader parser, boolean strict) throws XMLStreamException { #end @@ -518,7 +518,7 @@ public class ${className} { throw new XMLStreamException("Duplicated tag: '${rootTag}'", parser.getLocation(), null); } #if ( $locationTracking ) - $rootLcapName = parse${rootUcapName}(parser, strict, source); + $rootLcapName = parse${rootUcapName}(parser, strict, inputSrc); #elseif ( $needXmlContext ) $rootLcapName = parse${rootUcapName}(parser, strict, context); #else @@ -541,7 +541,7 @@ public class ${className} { #set ( $ancestors = $Helper.ancestors( $class ) ) #set ( $allFields = $Helper.xmlFields( $class ) ) #if ( $locationTracking ) - private ${classUcapName} parse${classUcapName}(XMLStreamReader parser, boolean strict, InputSource source) throws XMLStreamException { + private ${classUcapName} parse${classUcapName}(XMLStreamReader parser, boolean strict, InputSource inputSrc) throws XMLStreamException { #elseif ( $needXmlContext ) private ${classUcapName} parse${classUcapName}(XMLStreamReader parser, boolean strict, Deque context) throws XMLStreamException { #else @@ -551,7 +551,7 @@ public class ${className} { ${classUcapName}.Builder ${classLcapName} = ${classUcapName}.newBuilder(true); #if ( $locationTracking ) if (addLocationInformation) { - ${classLcapName}.location("", new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), source)); + ${classLcapName}.location("", new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), inputSrc)); } #end for (int i = parser.getAttributeCount() - 1; i >= 0; i--) { @@ -574,7 +574,7 @@ public class ${className} { } else if ("$fieldTagName".equals(name)) { #if ( $locationTracking ) if (addLocationInformation) { - ${classLcapName}.location(name, new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), source)); + ${classLcapName}.location(name, new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), inputSrc)); } #end #if ( $field.type == "String" ) @@ -632,7 +632,7 @@ public class ${className} { break; #elseif ( $field.type == "DOM" ) #if ( $locationTracking ) - ${classLcapName}.${field.name}(buildXmlNode(parser, source)); + ${classLcapName}.${field.name}(buildXmlNode(parser, inputSrc)); #else ${classLcapName}.${field.name}(buildXmlNode(parser)); #end @@ -646,7 +646,7 @@ public class ${className} { if ("${Helper.singular($fieldTagName)}".equals(parser.getLocalName())) { #if ( $locationTracking ) if (addLocationInformation) { - locations.put(Integer.valueOf(locations.size()), new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), source)); + locations.put(Integer.valueOf(locations.size()), new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), inputSrc)); } #end ${field.name}.add(interpolatedTrimmed(nextText(parser, strict), "${fieldTagName}")); @@ -666,7 +666,7 @@ public class ${className} { String value = nextText(parser, strict).trim(); #if ( $locationTracking ) if (addLocationInformation) { - locations.put(key, new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), source)); + locations.put(key, new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), inputSrc)); } #end ${field.name}.put(key, value); @@ -675,7 +675,7 @@ public class ${className} { break; #elseif ( $field.to && $field.multiplicity == "1" ) #if ( $locationTracking ) - ${classLcapName}.${field.name}(parse${field.toClass.name}(parser, strict, source)); + ${classLcapName}.${field.name}(parse${field.toClass.name}(parser, strict, inputSrc)); #elseif ( $needXmlContext ) ${classLcapName}.${field.name}(parse${field.toClass.name}(parser, strict, context)); #else @@ -684,7 +684,7 @@ public class ${className} { break; #elseif ( $field.to && $field.multiplicity == "*" && $Helper.isFlatItems( $field ) ) #if ( $locationTracking ) - ${field.name}.add(parse${field.toClass.name}(parser, strict, source)); + ${field.name}.add(parse${field.toClass.name}(parser, strict, inputSrc)); #elseif ( $needXmlContext ) ${field.name}.add(parse${field.toClass.name}(parser, strict, context)); #else @@ -696,7 +696,7 @@ public class ${className} { while (parser.nextTag() == XMLStreamReader.START_ELEMENT) { if ("${Helper.singular($fieldTagName)}".equals(parser.getLocalName())) { #if ( $locationTracking ) - ${field.name}.add(parse${field.toClass.name}(parser, strict, source)); + ${field.name}.add(parse${field.toClass.name}(parser, strict, inputSrc)); #elseif ( $needXmlContext ) ${field.name}.add(parse${field.toClass.name}(parser, strict, context)); #else @@ -723,7 +723,7 @@ public class ${className} { } #if ( $locationTracking ) if (addLocationInformation) { - ${classLcapName}.location(childName, new InputLocation(line, column, source, locations)); + ${classLcapName}.location(childName, new InputLocation(line, column, inputSrc, locations)); } #end } @@ -923,10 +923,10 @@ public class ${className} { } #if ( $locationTracking ) - private XmlNode buildXmlNode(XMLStreamReader parser, InputSource source) throws XMLStreamException { + private XmlNode buildXmlNode(XMLStreamReader parser, InputSource inputSrc) throws XMLStreamException { return XmlNodeStaxBuilder.build(parser, addLocationInformation - ? p -> new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), source) + ? p -> new InputLocation(parser.getLocation().getLineNumber(), parser.getLocation().getColumnNumber(), inputSrc) : null); } #else @@ -993,12 +993,12 @@ public class ${className} { public static interface ContentTransformer { /** * Interpolate the value read from the xpp3 document - * @param source The source value + * @param inputSrc The input source value * @param fieldName A description of the field being interpolated. The implementation may use this to * log stuff. * @return The interpolated value. */ - String transform(String source, String fieldName); + String transform(String inputSrc, String fieldName); } } From fce3d382923d2d12a1b4ee6ff69f94f674a67544 Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Wed, 27 Nov 2024 11:56:16 +0100 Subject: [PATCH 2/3] Resolve an ambiguity in the description of `target` behavior. Rename `filtering` as `stringFiltering` for avoiding confusion with file filtering. --- api/maven-api-model/src/main/mdo/maven.mdo | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo index 4a9c05f77e30..64b586896342 100644 --- a/api/maven-api-model/src/main/mdo/maven.mdo +++ b/api/maven-api-model/src/main/mdo/maven.mdo @@ -2062,11 +2062,12 @@ The version of the platform where the code will be executed. In a Java environment, this is the value of the {@code --release} compiler option. If a Java project contains multiple main sources with different target versions, - then a multi-version JAR file will be created. + then a multi-version JAR file will be created + with the lowest version taken as the base version. If this element is omitted, then the default target version is the compiler default value, which is usually the version of the Java environment running Maven. -

If a target version is specified for resources or script files, +

If a target version, different from the base version, is specified for resources or script files, then this value modifies the directory where the files will be copied. For example, if {@code targetVersion} is 17, then the {@code foo/bar.properties} resource file will be copied as {@code META-INF/versions/17/foo/bar.properties}.

@@ -2100,7 +2101,7 @@ String - filtering + stringFiltering 4.1.0+ This filtering should not be confused with the filtering of paths done by the - {@code includes} and {@code excludes} patterns.

-

The default value is {@code false}.

]]> From e429aa3d9557a18f37cf61ffc62b7481fc114a06 Mon Sep 17 00:00:00 2001 From: Martin Desruisseaux Date: Sun, 26 Jan 2025 12:12:04 +0100 Subject: [PATCH 3/3] Corrections in the comment about mapping from old elements to . --- api/maven-api-model/src/main/mdo/maven.mdo | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/maven-api-model/src/main/mdo/maven.mdo b/api/maven-api-model/src/main/mdo/maven.mdo index 64b586896342..d3cfaa2795f8 100644 --- a/api/maven-api-model/src/main/mdo/maven.mdo +++ b/api/maven-api-model/src/main/mdo/maven.mdo @@ -775,7 +775,7 @@ String - + resources 3.0.0+ @@ -790,7 +790,7 @@ - + testResources 4.0.0+ @@ -887,7 +887,7 @@ String - + scriptSourceDirectory 4.0.0+ true @@ -2134,7 +2134,7 @@ - + Resource This element describes all of the classpath resources associated with a project or unit tests.