Apache
/
maven
mirror of https://github.com/apache/maven.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[MNG-6656] add reference documentation on build/consumer transformers

This commit is contained in:
Hervé Boutemy 2021-04-04 09:27:59 +02:00
parent 46129561fb
commit 87cd4960a4
2 changed files with 111 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
maven-xml/src/site/apt/index.apt Normal file
View File

@ -0,0 +1,73 @@
~~ 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.
-----
Introduction
-----
Hervé Boutemy
-----
2021-04-04
-----
Maven Model XML Transformer
Maven Model XML Transformer provides build/consumer <<<pom.xml>>> transformers.
In order to keep formatting, comments and every detail when transforming a build <<<pom.xml>>> to a consumer <<<pom.xml>>>, transformation happens directly on the stream of SAX events.
There are 3 states of a <<<pom.xml>>> content:
[[1]] the <<build>> <<<pom.xml>>>, as it is stored on disk during development and in source control, which can be simplified to ease source code maintenance,
[[2]] the <<raw>> content (usually not saved to a file), which is enriched from initial build content, to match Maven Model validation rules,
[[3]] the <<consumer>> <<<pom.xml>>>, as it is saved to local repository or remote repository, to be used as dependencies descriptor when consumed by a project.
[]
Transformation is implemented as two filters:
* <<build to raw>> in <<<BuildPomXMLFilter>>> ({{{./apidocs/org/apache/maven/xml/sax/filter/BuildPomXMLFilter.html}javadoc}}),
with its <<<BuildPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/xml/sax/filter/BuildPomXMLFilterFactory.html}source}}) assembling transformation steps,
* in a multi-module build, <<<parent>>>'s <<<version>>> is automatically added,
* in a multi-module build, dependencies <<<version>>> is automatically added for reactor modules,
* CI-friendly <<<$\{sha1}>>>, <<<$\{revision}>>> and <<<$\{changelist}>>> are properties are replaced with their value,
[]
* <<raw to consumer>> in <<<ConsumerPomXMLFilter>>> ({{{./apidocs/org/apache/maven/xml/sax/filter/ConsumerPomXMLFilter.html}javadoc}}),
with its <<<ConsumerPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/xml/sax/filter/ConsumerPomXMLFilterFactory.html}source}}) assembling transformation steps.
* <<<modules>>> is stripped because it only has a meaning at build time on disk, but not once mapped to repository format,
* <<<parent>>>'s <<<relativePath>>> is stripped because it only has a meaning at build time on disk, but not once mapped to repository format.
[]
[]
For Maven 4, every state of Maven Model remains with the same <<<maven-4.0.0.xsd>>> schema, but it the future Maven 5+:
* build model should evolve to add new features configuration in new <v5> model fields, or remove some old unused fields,
* consumer model should at least continue to produce a <<<maven-4.0.0.xsd>>>-compliant <<<pom.xml>>> for compatibility with the vast and diverse dependency consumers ecosystem,
but may also produce in parallel new consumption formats (yet to be defined).
[]

38
maven-xml/src/site/site.xml Normal file
View File

@ -0,0 +1,38 @@
<?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.
-->
<project xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 http://maven.apache.org/xsd/decoration-1.8.0.xsd">
<edit>${project.scm.url}</edit>
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="JavaDocs" href="apidocs/index.html"/>
<item name="Source Xref" href="xref/index.html"/>
<!--item name="FAQ" href="faq.html"/-->
</menu>
<menu ref="parent"/>
<menu ref="reports"/>
</body>
</project>