Package org.codehaus.mojo.flatten

Class FlattenMojo

  • All Implemented Interfaces:
    org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo
    @Mojo(name="flatten",
      requiresDependencyCollection=RUNTIME,
      threadSafe=true)
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.
    If the build element contains plugins in the build/plugins section which are configured to load extensions, a reduced build element containing these plugins will be kept in the flattened pom.

    • Field Detail

      • INITIAL_POM_WRITER_SIZE

        private static final int INITIAL_POM_WRITER_SIZE
        See Also:
        Constant Field Values

      • NEW_LINE_PATTERN

        private static final java.util.regex.Pattern NEW_LINE_PATTERN

      • settings

        @Parameter(defaultValue="${settings}",
           readonly=true,
           required=true)
private org.apache.maven.settings.Settings settings
        The Settings used to get active profile properties.

      • session

        @Parameter(defaultValue="${session}",
           readonly=true,
           required=true)
private org.apache.maven.execution.MavenSession session
        The MavenSession used to get user properties.

      • project

        @Parameter(defaultValue="${project}",
           readonly=true,
           required=true)
private org.apache.maven.project.MavenProject project
        The Maven Project.

      • updatePomFile

        @Parameter(property="updatePomFile")
private java.lang.Boolean updatePomFile
        The flag to indicate if the generated flattened POM shall be set as POM file to the current project. By default this is only done for projects with packaging other than pom. You may want to also do this for pom packages projects by setting this parameter to true or you can use false in order to only generate the flattened POM but never set it as POM file. If flattenMode is set to bom the default value will be true.

      • embedBuildProfileDependencies

        @Parameter(defaultValue="false")
private java.lang.Boolean embedBuildProfileDependencies
        Profiles activated by OS or JDK are valid ways to have different dependencies per environment. However, profiles activated by property of file are less clear. When setting this parameter to true, the latter dependencies will be written as direct dependencies of the project. This is not how Maven2 and Maven3 handles dependencies. When keeping this property false, all profiles will stay in the flattened-pom.

      • mojoExecution

        @Parameter(defaultValue="${mojo}",
           readonly=true,
           required=true)
private org.apache.maven.plugin.MojoExecution mojoExecution
        The MojoExecution used to get access to the raw configuration of pomElements as empty tags are mapped to null.

      • pomElements

        @Parameter(required=false)
private FlattenDescriptor pomElements
        The Model that defines how to handle additional POM elements. Please use flattenMode in preference if possible. This parameter is only for ultimate flexibility.

      • omitExclusions

        @Parameter(defaultValue="false",
           required=false)
private boolean omitExclusions
        Dictates whether dependency exclusions stanzas should be included in the flattened POM. By default exclusions will be included in the flattened POM but if you wish to omit exclusions stanzas from being present then set this configuration property to true.
        Since:
        1.3.0

      • flattenMode

        @Parameter(property="flatten.mode",
           required=false)
private FlattenMode flattenMode
        The different possible values for flattenMode:
        Mode Description
        oss For Open-Source-Software projects that want to keep all optional POM elements except for repositories and pluginRepositories.
        ossrh Keeps all optional POM elements that are required for OSS Repository-Hosting.
        bom Like ossrh but additionally keeps dependencyManagement and properties. Especially it will keep the dependencyManagement as-is without resolving parent influences and import-scoped dependencies. This is useful if your POM represents a BOM (Bill Of Material) and you do not want to deploy it as is (to remove parent and resolve version variables, etc.).
        defaults The default mode that removes all optional POM elements except repositories.
        clean Removes all optional POM elements.
        fatjar Removes all optional POM elements and all dependencies.
        resolveCiFriendliesOnly Only resolves variables revision, sha1 and changelist. Keeps everything else. See Maven CI Friendly for further details.

      • flattenDependencyMode

        @Parameter(property="flatten.dependency.mode",
           required=false)
private FlattenDependencyMode flattenDependencyMode
        The different possible values for flattenDependencyMode:
        Mode Description
        direct

        Flatten only the direct dependency versions, excluding inherited dependencies from a parent module.

        This was the default mode with Flatten Plugin in versions 1.4.0 up to 1.6.0.

        inherited

        Flatten the dependency versions, including inherited dependencies from a parent module

        This is the default mode and compatible with Flatten Plugin prior to 1.2.0, this mode was called direct between versions 1.2.0 and 1.3.0.
        all

        Flatten both direct and transitive dependencies. This will examine the full dependency tree, and pull up all transitive dependencies as a direct dependency, and setting their versions appropriately.

        This is recommended if you are releasing a library that uses dependency management to manage dependency versions.

      • keepCommentsInPom

        @Parameter(property="flatten.dependency.keepComments",
           required=false,
           defaultValue="false")
private boolean keepCommentsInPom
        The core maven model readers/writers are discarding the comments of the pom.xml. By setting keepCommentsInPom to true the current comments are moved to the flattened pom.xml. Default value is false (= not re-adding comments).
        Since:
        1.3.0

      • skipFlatten

        @Parameter(property="flatten.flatten.skip",
           defaultValue="false")
private boolean skipFlatten
        If true the flatten goal will be skipped.
        Since:
        1.6.0

      • defaultOperation

        @Parameter(property="flatten.dependency.defaultOperation",
           required=false,
           defaultValue="flatten")
private ElementHandling defaultOperation
        The default operation to use when no element handling is given. Defaults to flatten.
        Since:
        1.6.0

      • extendedModelInterpolator

        @Inject
private ExtendedModelInterpolator extendedModelInterpolator
        The ModelInterpolator used to resolve variables.

      • modelCiFriendlyInterpolator

        @Inject
private CiInterpolator modelCiFriendlyInterpolator
        The ModelInterpolator used to resolve variables.

      • artifactHandlerManager

        @Inject
private org.apache.maven.artifact.handler.manager.ArtifactHandlerManager artifactHandlerManager

      • repositorySystem

        @Inject
private org.eclipse.aether.RepositorySystem repositorySystem

    • 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 java.lang.String extractHeaderComment​(java.io.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,
                        java.io.File pomFile,
                        java.lang.String headerComment,
                        KeepCommentsInPom anOriginalCommentsPath)
                 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​(java.lang.String data,
                                 java.io.File file,
                                 java.lang.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​(java.io.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).

      • createEffectivePom

        org.apache.maven.model.Model createEffectivePom​(org.apache.maven.model.building.ModelBuildingRequest buildingRequest)
                                         throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException

      • createCleanPom

        private org.apache.maven.model.Model createCleanPom​(org.apache.maven.model.Model effectivePom)
                                             throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException

      • createInterpolatedPom

        private org.apache.maven.model.Model createInterpolatedPom​(org.apache.maven.model.building.ModelBuildingRequest buildingRequest,
                                                           org.apache.maven.model.Model originalPom,
                                                           java.io.File projectDirectory)

      • createExtendedInterpolatedPom

        private org.apache.maven.model.Model createExtendedInterpolatedPom​(org.apache.maven.model.building.ModelBuildingRequest buildingRequest,
                                                                   org.apache.maven.model.Model originalPom,
                                                                   org.apache.maven.model.Model effectivePom,
                                                                   java.io.File projectDirectory)

      • createOriginalPom

        private org.apache.maven.model.Model createOriginalPom​(java.io.File pomFile)
                                                throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException

      • createCleanPomImpl

        protected org.apache.maven.model.Model createCleanPomImpl​(org.apache.maven.model.Model effectivePom)
                                                   throws org.apache.maven.plugin.MojoExecutionException
        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.
        Throws:
        org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

      • getSourceModel

        private org.apache.maven.model.Model getSourceModel​(FlattenDescriptor descriptor,
                                                    PomProperty<?> property,
                                                    FlattenMojo.ModelsFactory modelsFactory)
                                             throws org.apache.maven.plugin.MojoExecutionException
        Throws:
        org.apache.maven.plugin.MojoExecutionException

      • createFlattenedRepositories

        protected static java.util.List<org.apache.maven.model.Repository> createFlattenedRepositories​(java.util.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.

      • getModelEncoding

        private static java.lang.String getModelEncoding​(org.apache.maven.model.Model pom)

      • isCentralRepositoryFromSuperPom

        private static boolean isCentralRepositoryFromSuperPom​(org.apache.maven.model.Repository repo)
        This method determines if the given Repository section is identical to what is defined from the super POM.
        Parameters:
        repo - is the Repository section to check.
        Returns:
        true if maven central default configuration, false otherwise.

      • createModelBuildingRequest

        private org.apache.maven.model.building.ModelBuildingRequest createModelBuildingRequest​(java.io.File pomFile)

      • getReactorModelsFromSession

        private java.util.List<org.apache.maven.project.MavenProject> getReactorModelsFromSession()

      • createEffectivePomImpl

        protected org.apache.maven.model.Model createEffectivePomImpl​(org.apache.maven.model.building.ModelBuildingRequest buildingRequest)
                                                       throws org.apache.maven.plugin.MojoExecutionException
        Creates the effective POM for the given pomFile trying its best to match the core maven behaviour.
        Parameters:
        buildingRequest - ModelBuildingRequest
        Returns:
        the parsed and calculated effective POM.
        Throws:
        org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

      • isEmpty

        private boolean isEmpty​(java.util.Collection<?> collection)
        Null-safe check for Collection.isEmpty().
        Parameters:
        collection - is the Collection to test. May be null.
        Returns:
        true if null or empty, false otherwise.

      • 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 java.util.List<org.apache.maven.model.Dependency> createFlattenedDependencies​(org.apache.maven.model.Model effectiveModel)
                                                                                 throws org.apache.maven.plugin.MojoExecutionException
        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.
        Throws:
        org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

      • createFlattenedDependenciesDirect

        private void createFlattenedDependenciesDirect​(java.util.List<org.apache.maven.model.Dependency> projectDependencies,
                                               java.util.List<org.apache.maven.model.Dependency> flattenedDependencies)
        Collects the resolved dependencies from the given effectiveModel.
        Parameters:
        projectDependencies - is the effective POM Model's current dependencies
        flattenedDependencies - is the List where to add the collected dependencies.

      • createFlattenedDependenciesAll

        private void createFlattenedDependenciesAll​(java.util.List<org.apache.maven.model.Dependency> projectDependencies,
                                            java.util.List<org.apache.maven.model.Dependency> managedDependencies,
                                            java.util.List<org.apache.maven.model.Dependency> flattenedDependencies)
                                     throws org.eclipse.aether.resolution.ArtifactDescriptorException,
                                            org.eclipse.aether.collection.DependencyCollectionException
        Collects the resolved direct and transitive dependencies from the given effectiveModel. The collected dependencies are stored in order, so that the leaf dependencies are prioritized in front of direct dependencies. In addition, every non-leaf dependencies will exclude its own direct dependency, since all transitive dependencies will be collected.

        Transitive dependencies are all going to be collected and become a direct dependency. Maven should already resolve versions properly because now the transitive dependencies are closer to the artifact. However, when this artifact is being consumed, Maven Enforcer Convergence rule will fail because there may be multiple versions for the same transitive dependency.

        Typically, exclusion can be done by using the wildcard. However, a known Maven issue prevents convergence enforcer from working properly w/ wildcard exclusions. Thus, this will exclude each dependencies explicitly rather than using the wildcard.

        Parameters:
        projectDependencies - is the effective POM Model's current dependencies
        flattenedDependencies - is the List where to add the collected dependencies.
        Throws:
        org.eclipse.aether.collection.DependencyCollectionException
        org.eclipse.aether.resolution.ArtifactDescriptorException

      • createFlattenedDependencies

        protected void createFlattenedDependencies​(org.apache.maven.model.Model effectiveModel,
                                           java.util.List<org.apache.maven.model.Dependency> flattenedDependencies)
                                    throws org.apache.maven.plugin.MojoExecutionException
        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.
        Throws:
        org.apache.maven.plugin.MojoExecutionException - if anything goes wrong.

      • 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.