org.codehaus.mojo.flatten

Class FlattenMojo

java.lang.Object

org.apache.maven.plugin.AbstractMojo

org.codehaus.mojo.flatten.AbstractFlattenMojo

org.codehaus.mojo.flatten.FlattenMojo

All Implemented Interfaces:

org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo

@Mojo(name="flatten",
      requiresProject=true,
      requiresDirectInvocation=false,
      executionStrategy="once-per-session",
      requiresDependencyCollection=RUNTIME)
public class FlattenMojo
extends AbstractFlattenMojo

This MOJO realizes the goal flatten that generates the flattened POM and potentially updates the POM file so that the current MavenProject's file points to the flattened POM instead of the original pom.xml file.
The flattened POM is a reduced version of the original POM with the focus to contain only the important information for consuming it. Therefore information that is only required for maintenance by developers and to build the project artifact(s) are stripped.
Starting from here we specify how the flattened POM is created from the original POM and its project:

Element	Transformation	Note
modelVersion	Fixed to "4.0.0"	New maven versions will once be able to evolve the model version without incompatibility to older versions if flattened POMs get deployed.
groupId artifactId version packaging	resolved	copied to the flattened POM but with inheritance from parent as well as with all variables and defaults resolved. These elements are technically required for consumption.
licenses	resolved	copied to the flattened POM but with inheritance from parent as well as with all variables and defaults resolved. The licenses would not be required in flattened POM. However, they make sense for publication and deployment and are important for consumers of your artifact.
dependencies	resolved specially	flattened POM contains the actual dependencies of the project. Test dependencies are removed. Variables and dependencyManagement is resolved to get fixed dependency attributes (especially version). If embedBuildProfileDependencies is set to true, then also build-time driven Profiles will be evaluated and may add dependencies. For further details see Profiles below.
profiles	resolved specially	only the Activation and the dependencies of a Profile are copied to the flattened POM. If you set the parameter embedBuildProfileDependencies to true then only profiles activated by JDK or OS will be added to the flattened POM while the other profiles are triggered by the current build setup and if activated their impact on dependencies is embedded into the resulting flattened POM.
name description url inceptionYear organization scm developers contributors mailingLists pluginRepositories issueManagement ciManagement distributionManagement	configurable	Will be stripped from the flattened POM by default. You can configure all of the listed elements inside pomElements that should be kept in the flattened POM (e.g. <pomElements><name/><description/><developers/><contributors/></pomElements>). For common use-cases there are predefined modes available via the parameter flattenMode that should be used in preference.
prerequisites	configurable	Like above but by default NOT removed if packaging is "maven-plugin".
repositories	configurable	Like two above but by default NOT removed. If you want have it removed, you need to use the parameter pomElements and configure the child element repositories with value flatten.
parent build dependencyManagement properties modules reporting	configurable	These elements should typically be completely stripped from the flattened POM. However for ultimate flexibility (e.g. if you only want to resolve variables in a POM with packaging pom) you can also configure to keep these elements. We strictly recommend to use this feature with extreme care and only if packaging is pom (for "Bill of Materials"). In the latter case you configure the parameter flattenMode to the value bom.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields inherited from interface org.apache.maven.plugin.Mojo

ROLE

Constructor Summary

Constructors

Constructor and Description
FlattenMojo() The constructor.

Method Summary

Methods

Modifier and Type	Method and Description
protected org.apache.maven.model.Model	createCleanPom(org.apache.maven.model.Model effectivePom) This method creates the clean POM as a Model where to copy elements from that shall be flattened.
protected static org.apache.maven.model.Model	createEffectivePom(org.apache.maven.model.building.ModelBuildingRequest buildingRequest, boolean embedBuildProfileDependencies) Creates the effective POM for the given pomFile trying its best to match the core maven behaviour.
protected List<org.apache.maven.model.Dependency>	createFlattenedDependencies(org.apache.maven.model.Model effectiveModel) Creates the List of dependencies for the flattened POM.
protected void	createFlattenedDependencies(org.apache.maven.model.Model effectiveModel, List<org.apache.maven.model.Dependency> flattenedDependencies) Collects the resolved dependencies from the given effectiveModel.
protected org.apache.maven.model.Dependency	createFlattenedDependency(org.apache.maven.model.Dependency projectDependency)
protected org.apache.maven.model.Model	createFlattenedPom(File pomFile) This method creates the flattened POM what is the main task of this plugin.
protected static List<org.apache.maven.model.Repository>	createFlattenedRepositories(List<org.apache.maven.model.Repository> repositories) Creates a flattened List of Repository elements where those from super-POM are omitted.
void	execute()
protected String	extractHeaderComment(File xmlFile) This method extracts the XML header comment if available.
protected static boolean	isBuildTimeDriven(org.apache.maven.model.Activation activation)
boolean	isEmbedBuildProfileDependencies()
boolean	isUpdatePomFile()
protected void	writePom(org.apache.maven.model.Model pom, File pomFile, String headerComment) Writes the given POM Model to the given File.
protected void	writeStringToFile(String data, File file, String encoding) Writes the given data to the given file using the specified encoding.

Methods inherited from class org.codehaus.mojo.flatten.AbstractFlattenMojo

getFlattenedPomFile, getFlattenedPomFilename, getOutputDirectory

Methods inherited from class org.apache.maven.plugin.AbstractMojo

getLog, getPluginContext, setLog, setPluginContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FlattenMojo

public FlattenMojo()

The constructor.

Method Detail

execute

public void execute()
             throws org.apache.maven.plugin.MojoExecutionException,
                    org.apache.maven.plugin.MojoFailureException

Throws:

org.apache.maven.plugin.MojoExecutionException

org.apache.maven.plugin.MojoFailureException

extractHeaderComment

protected String extractHeaderComment(File xmlFile)
                               throws org.apache.maven.plugin.MojoExecutionException

This method extracts the XML header comment if available.

Parameters:

xmlFile - is the XML File to parse.

Returns:

the XML comment between the XML header declaration and the root tag or null if NOT available.

Throws:

org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

writePom

protected void writePom(org.apache.maven.model.Model pom,
            File pomFile,
            String headerComment)
                 throws org.apache.maven.plugin.MojoExecutionException

Writes the given POM Model to the given File.

Parameters:

pom - the Model of the POM to write.

pomFile - the File where to write the given POM will be written to. Parent directories are created automatically.

headerComment - is the content of a potential XML comment at the top of the XML (after XML declaration and before root tag). May be null if not present and to be omitted in target POM.

Throws:

org.apache.maven.plugin.MojoExecutionException - if the operation failed (e.g. due to an IOException).

writeStringToFile

protected void writeStringToFile(String data,
                     File file,
                     String encoding)
                          throws org.apache.maven.plugin.MojoExecutionException

Writes the given data to the given file using the specified encoding.

Parameters:

data - is the String to write.

file - is the File to write to.

encoding - is the encoding to use for writing the file.

Throws:

org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

createFlattenedPom

protected org.apache.maven.model.Model createFlattenedPom(File pomFile)
                                                   throws org.apache.maven.plugin.MojoExecutionException,
                                                          org.apache.maven.plugin.MojoFailureException

This method creates the flattened POM what is the main task of this plugin.

Parameters:

pomFile - is the name of the original POM file to read and transform.

Returns:

the Model of the flattened POM.

Throws:

org.apache.maven.plugin.MojoExecutionException - if anything goes wrong (e.g. POM can not be processed).

org.apache.maven.plugin.MojoFailureException - if anything goes wrong (logical error).

createCleanPom

protected org.apache.maven.model.Model createCleanPom(org.apache.maven.model.Model effectivePom)

This method creates the clean POM as a Model where to copy elements from that shall be flattened. Will be mainly empty but contains some the minimum elements that have to be kept in flattened POM.

Parameters:

effectivePom - is the effective POM.

Returns:

the clean POM.

createFlattenedRepositories

protected static List<org.apache.maven.model.Repository> createFlattenedRepositories(List<org.apache.maven.model.Repository> repositories)

Creates a flattened List of Repository elements where those from super-POM are omitted.

Parameters:

repositories - is the List of Repository elements. May be null.

Returns:

the flattened List of Repository elements or null if null was given.

createEffectivePom

protected static org.apache.maven.model.Model createEffectivePom(org.apache.maven.model.building.ModelBuildingRequest buildingRequest,
                                              boolean embedBuildProfileDependencies)
                                                          throws org.apache.maven.plugin.MojoExecutionException

Creates the effective POM for the given pomFile trying its best to match the core maven behaviour.

Returns:

the parsed and calculated effective POM.

Throws:

org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

isEmbedBuildProfileDependencies

public boolean isEmbedBuildProfileDependencies()

Returns:

true if build-dependent profiles (triggered by OS or JDK) should be evaluated and their effect (variables and dependencies) are resolved and embedded into the flattened POM while the profile itself is stripped. Otherwise if false the profiles will remain untouched.

isBuildTimeDriven

protected static boolean isBuildTimeDriven(org.apache.maven.model.Activation activation)

Parameters:

activation - is the Activation of a Profile.

Returns:

true if the given Activation is build-time driven, false otherwise (if it is triggered by OS or JDK).

createFlattenedDependencies

protected List<org.apache.maven.model.Dependency> createFlattenedDependencies(org.apache.maven.model.Model effectiveModel)

Creates the List of dependencies for the flattened POM. These are all resolved dependencies except for those added from profiles.

Parameters:

effectiveModel - is the effective POM Model to process.

Returns:

the List of dependencies.

createFlattenedDependencies

protected void createFlattenedDependencies(org.apache.maven.model.Model effectiveModel,
                               List<org.apache.maven.model.Dependency> flattenedDependencies)

Collects the resolved dependencies from the given effectiveModel.

Parameters:

effectiveModel - is the effective POM Model to process.

flattenedDependencies - is the List where to add the collected dependencies.

createFlattenedDependency

protected org.apache.maven.model.Dependency createFlattenedDependency(org.apache.maven.model.Dependency projectDependency)

Parameters:

projectDependency - is the project Dependency.

Returns:

the flattened Dependency or null if the given Dependency is NOT relevant for flattened POM.

isUpdatePomFile

public boolean isUpdatePomFile()

Returns:

true if the generated flattened POM shall be set as POM artifact of the MavenProject, false otherwise.