maven-model-transform/src/site/apt/index.apt

~~ 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/model/transform/BuildPomXMLFilter.html}javadoc}}),
   with its <<<BuildPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/model/transform/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/model/transform/ConsumerPomXMLFilter.html}javadoc}}),
   with its <<<ConsumerPomXMLFilterFactory>>> ({{{./xref/org/apache/maven/model/transform/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).

 []