- Overview
- Release Notes
- Installation
- Disabling the Extension
- Deprecated and Unknown Properties
- Extension Marker File
- Summary Logging
- Javadoc
- Feature Guide
Overview
POM Manipulation Extension (PME) is a Maven tool to align the versions in your POMs according to some external reference, sort of like a BOM but much more extensive and without the added baggage of a BOM declaration.
It is suppplied as a core library, a Maven extension (in the sense of installing to lib/ext
, not pom.xml
<extensions/>
) and a command line tool.
PME excels in a cleanroom environment where large numbers of pre-existing projects must be rebuilt. To minimize the number of builds necessary, PME supports aligning dependency versions using an external BOM-like reference. However, it can also use a similar POM external reference to align plugin versions, and inject standardized plugin executions into project builds. Because in this scenario you’re often rebuilding projects from existing release tags, PME also supports appending a rebuild version suffix, such as rebuild-1
, where the actual rebuild number is automatically incremented beyond the highest rebuild number detected in the Maven repository.
Release Notes
For a list of changes please see here
Installation
Installation as CLI tool.
Obtain the jar from here and then it may be invoked as
java -jar pom-manipulation-cli-<version>.jar
It supports the following arguments
-D <arg> Java Properties
-f,--file <arg> POM file
-h,--help Print help
-l,--log <arg> Log file to output logging to
-P,--activeProfiles <arg> Comma separated list of active profiles.
-s,--settings <arg> Optional settings.xml file
-q,--quiet Enable quiet
-d,--debug Enable debug
-t,--trace Enable trace
-p,--printDeps Print all project dependencies
--printManipulatorOrder Print the current manipulator order
Note:
- All property arguments are the equivalent to those used when it is used as a Maven extension.
- The latter two commands do not run the entire tool.
- Log file output will be disabled if running inside a container image.
Installation as an Extension
Installing PME is as simple as grabbing the binary and copying it to your ${MAVEN_HOME}/lib/ext
directory. Once PME is installed, Maven should output something like the following when run:
[INFO] Maven-Manipulation-Extension
Uninstalling the extension is equally simple: just delete it from ${MAVEN_HOME}/lib/ext
.
Disabling the Extension
You can disable PME using the manipulation.disable
property:
$ mvn -Dmanipulation.disable=true clean install
If you want to make it more permanent, you could add it to your settings.xml
:
<settings>
<profiles>
<profile>
<id>disable-pme</id>
<properties>
<manipulation.disable>true</manipulation.disable>
</properties>
</profile>
</profiles>
<activeProfiles>
<activeProfile>disable-pme</activeProfile>
</activeProfiles>
</settings>
Deprecated and Unknown Properties
NOTE : Available from version 4.0 |
If an unknown property is passed in the tool (whether in CLI or extension mode) will output a warning with the unknown property.
By default if a deprecated property is used the tool will detect it and throw an exception. If the user wishes to allow usage of deprecated properties set enabledDeprecatedProperties
to true.
Extension Marker File
When the extension runs it writes out a control marker file in the execution root target
directory. This is named pom-manip-ext-marker.txt
. If this marker file exists PME will not run a second time instead logging:
Skipping manipulation as previous execution found.
Removing the target directory will allow PME to be run again.
Summary Logging
PME will output a summary of its changes at the end of the run. As well as reporting version, property, dependency and
plugin alignment, it is also possible to report what hasn’t been aligned by setting the property
reportNonAligned=true
. This summary may also be output to a file by setting the property reportTxtOutputFile
to the
name of the file, e.g., alignmentReport.txt
. The file’s path will always be relative to the execution root target
directory (next to the marker file above).
Finally, it will also output the comparator summary as a JSON file. The file’s path will always be relative to the
execution root target
directory (next to the marker file above). By default, the file will be named
alignmentReport.json
. However, the name of this file may be changed by setting the reportJSONOutputFile
property to
an alternate name for the file.
{
"executionRoot" : {
"groupId" : "org.foo",
"artifactId" : "foo-parent",
"version" : "7.0.0.Final-rebuild-1",
"originalGAV" : "org.foo:foo-parent:7.0.0.Final"
},
"modules" : [ {
"gav" : {
"groupId" : "org.foo",
"artifactId" : "foo-parent",
"version" : "7.0.0.Final-rebuild-1",
"originalGAV" : "org.foo:foo-parent:7.0.0.Final"
},
"properties" : {
...
}
}
This JSON file may be read as POJO by using the JSONUtils class which utilises the json package.
Javadoc
This is available here.
Feature Guide
Operation
- Maven POM files are read from disk into memory before all manipulators, including the Groovy manipulators. The one
exception is the
PREPARSE
Groovy manipulator, which runs before the POM files are loaded into memory. Therefore,PREPARSE
is the only stage where it is safe to modify POM files on disk without risking losing modifications. For more information about Groovy script invocation stages, see the Groovy Script Injection section of this guide. - In-memory POM models are written back to disk after all manipulators have executed. It is possible to modify the POM
at any time before this by accessing its in-memory model via
Project.getModel()
. - The Groovy manipulators can safely modify non-model files on disk at any time.
Below are links to more specific information about configuring sets of features in PME: