Apache Commons logo

commons-parent

This page provides information about the commons-parent pom.xml
It has been updated for version 46 of the pom (but some discrepancies may remain). Please consult version 46 source in case of doubt.
Release Notes for version 46

Commons components use Maven as their primary build system and commons-parent is the parent pom for the components' Maven build.

Using a parent pom reduces the build configuration required for each individual component and standardizes the builds across Commons components.

Build

The following is a list of the main build features provided by commons-parent:

  • Reproducible Build - It is important that builds are consistently reproducible and in order to achieve this with Maven the same Plugin versions need to be used each time. commons-parent specifies the Plugin versions to be used in the <pluginManagement> section.
    • (N.B. the <reporting> section ignores anything specified in the <pluginManagement> section and component pom.xml's should specify the version of any additional report plugins they specify).
  • LICENSE and NOTICE files - automatically added to the jar files produced by the build to conform with the ASF License Policy.
  • MANIFEST.MF files - The following information is automatically included in the componentjar's manifest file:
    • Implementation-Title - set to the component's name
    • Implementation-Vendor - set to The Apache Software Foundation
    • Implementation-Vendor-Id - set to org.apache
    • Implementation-Version - set to the component version
    • Specification-Title - set to the component's name
    • Specification-Vendor - set to The Apache Software Foundation
    • Specification-Version - set to the component version
    • X-Compile-Source-JDK - set to the source option used by the compiler
    • X-Compile-Target-JDK - set to the target option used by the compiler
  • OSGi Enabled - OSGi metadata is automatically included in the component jar's manifest file enabling commons components to be used in an OSGi container. The following manifest entries are generated by default:
    • Bundle-Name - set to the component's name
    • Bundle-Vendor - set to The Apache Software Foundation
    • Bundle-Version - set to the component version
    • Bundle-ManifestVersion - set to 2
    • Bundle-License - set to http://www.apache.org/licenses/LICENSE-2.0.txt
    • Bundle-Description - set to the component's description
    • Bundle-SymbolicName - set to the component's package name (e.g. org.apache.commons.beanutils)
    • Bundle-DocURL - set to the component's website URL
    • Export-Package - set to the component's package names (can be overriden)
    • Import-Package - set to the package names of the component's dependencies
  • Java Version - source and target options can be configured through properties, and profiles are provided to test on different Java versions. Where necessary, plugin versions are down-graded to the latest version that runs on earlier JVMs. If later Java versions require updated plugins, this is done in a conditional profile (jdk7-plugin-fix-version).
  • Testing Coverage - both Jacoco and Cobertura are supported. These can be independently enabled.
  • Source Compatibility - both japicmp and clirr are supported. These can be independently enabled.

Release

The following is a list of the main release features provided by commons-parent through the release profile.

  • Binary and Source distributions
  • Signatures and Checksums
  • Javadoc and source jars

Additionally the RAT (release audit) report is automatically produced when generating a component's site. The RAT report checks the source files for appropriate License Headers.

Commons Release Plugin.

By default in the parent, the commons-release-plugin is disabled as to not stop folks' release practices. That said, for people interested in configuring the newly released (April 2018) release plugin, one needs to configure the following properties, for single module builds:

<properties>
    <commons.release.isDistModule>true</commons.release.isDistModule>
    <commons.distSvnStagingUrl>scm:svn:https://dist.apache.org/repos/dist/dev/commons/foo</commons.distSvnStagingUrl>
</properties>
where foo represents our component. Furthermore, during a release build, we ask that the svn folder be empty. We then generate our release build by runnning:
mvn -Duser.name=${my_apache_id} -Prelease -Ptest-deploy clean package site deploy
to test our deployment. Note, all of the staged items end up in target/commons-release-plugin/scm. And, to perform a full release, we run:
mvn -Duser.name=${my_apache_id} -Prelease clean package site deploy
Using the release plugin should build and stage the non-assembly built artifacts to Nexus, and stage the assemblies to the svn location along with the site and the RELEASE-NOTES.txt from the root of the project.

Site Generation

The following is a list of the main site features provided by commons-parent:

  • Standard Style and Navigation - commons-parent has a site.xml which is inherited by each component's site and provides standard Menu/Navigation and styling.
    • Menu/Navigation - The menu and breadcrumb options specified in the commons-parent's site.xml are included in the component's site.
    • Style - The commons-parent's site.xml specifies the commons-skin so that component's sites use a standard style and commons logo.
  • Common Information
    • Mailing Lists - Mailing list information is specified in commons-parent and Maven automatically generates a standard Mailing List page for each compoenent.
    • Organization Name - The Apache Software Foundation (inherited from the Apache Parent pom).
  • Standard Reports - The following reports are configured
    • RAT (release audit) Report - reports on the presence/absence of appropriate License Headers in source files.
    • Japicmp Report - reports are only generated when a jar file has been produced by the build, so mvn clean site will produce an empty japicmp report, whereas mvn clean package site will produce a full report. Furthermore, in building pom only modules, japicmp has a tendency to print out a stacktrace under the pretense of a warning because it does not understand how to properly skip such a module.
    • Surefire Report
    • Javadocs
    • Source Cross Reference
    • The pom excludes Maven defaults such as the license report which is against the ASF branding rules. The following are currently included by default (components can add extra ones if they wish, but cannot remove them).
      • index
      • summary
      • modules
      • project-team
      • scm
      • issue-tracking
      • mailing-list
      • dependency-info
      • dependency-management
      • dependencies
      • dependency-convergence
      • cim
      • distribution-management
  • Custom Issue Tracking Page - The commons-build-plugin provides a mechanism to generate a custom issue tracking page for commons components. See here for details of how to configure the component's pom and generate the page.
  • Download Page - The commons-build-plugin provides a mechanism to generate a download page for the latest release of a component. See here for details of how to configure the component's pom and generate the page.

Java Version

Configuring the Java Source/Target options

commons-parent configures the source and target options in the maven-compiler-plugin to use the ${maven.compiler.source} and ${maven.compiler.target} properties respectively.

So, for example, to configure a component to have source/target set to 1.4 add the following lines to the component's pom.xml:

          <properties>
              <maven.compiler.source>1.4</maven.compiler.source>
              <maven.compiler.target>1.4</maven.compiler.target>
          </properties>
        
NOTE: the Maven compiler plugin defaults to using the properties ${maven.compiler.source} and ${maven.compiler.target}; however the Commons Parent POM originally incorrectly used ".compile." rather than ".compiler." This was fixed in version 31 of the Commons Parent pom. See https://issues.apache.org/jira/browse/COMMONSSITE-69

MANIFEST.MF

In order to help check what source/target options were used when building a release, the property values used to configure the source/target options in the maven-compiler-plugin (i.e. ${maven.compiler.source} and ${maven.compiler.target}) are also written out to the component jar's MANIFEST.MF file with the following header names:

            X-Compile-Source-JDK:
            X-Compile-Target-JDK:
        

Testing with different Java versions

Using the target option ensures that the .class file format is compatible with the required Java version - but it does not prevent/catch the use of methods/classes which were introduced in later Java versions (this is because the build will use the current Java libraries by default). One way to ensure that components don't accidentally use classes/methods from a later version of Java is to compile and test using the actual target Java version.

However, it may be that one or more Maven plugins require a later version of Java than the component. For this reason commons-parent provides profiles for compiling/testing under different Java versions (correct as of version 36):

  • java-1.3 for compiling and testing using Java 1.3 (uses property JAVA_1_3_HOME)
  • java-1.4 for compiling and testing using Java 1.4 (uses property JAVA_1_4_HOME)
  • java-1.5 for compiling and testing using Java 1.5 (uses property JAVA_1_5_HOME)
  • java-1.6 for compiling and testing using Java 1.6 (uses property JAVA_1_6_HOME)
  • java-1.7 for compiling and testing using Java 1.7 (uses property JAVA_1_7_HOME)
  • java-1.8 for compiling and testing using Java 1.8 (uses property JAVA_1_8_HOME)
  • java-1.9 for compiling and testing using Java 1.9 (uses property JAVA_1_9_HOME)

In order for these profiles to work, you need to configure the relevant JAVA_1_N_HOME properties in your settings.xml file. [There is no need to configure properties for profiles you don't need.] Each property should be set to the directory where the relevant version of the JDK is installed. Note: the Maven compiler plugin has documentation on how this works.

Note: the maven-bundle-plugin outputs all property values which start with a capital letter as headers to the jar's MANIFEST.MF file. The commons-parent pom uses the <_removeheaders> instruction to suppress the specific JAVA_* properties used by the pom.

To ensure that the properties are only present if they are actually needed, you can define the property in the relevant profile in your settings.xml, for example:

        <settings>
            <profiles>
                <!-- Sample profiles showing different ways of defining the properties -->
                <profile>
                    <id>java-1.5</id>
                    <properties>
                        <!-- sample Windows definition -->
                        <JAVA_1_5_HOME>C:\jdk1.5.0_22</JAVA_1_5_HOME>
                    </properties>
                </profile>
                <profile>
                    <id>java-1.6</id>
                    <properties>
                        <!-- Sample Unix definition -->
                        <JAVA_1_6_HOME>/home/jenkins/tools/java/latest1.6</JAVA_1_6_HOME>
                    </properties>
                </profile>
                <profile>
                    <id>java-1.7</id>
                    <properties>
                        <!-- sample definition using an OS environment variable -->
                        <JAVA_1_7_HOME>${env.JAVA_1_7_HOME}</JAVA_1_7_HOME>
                    </properties>
                </profile>
                <!-- No need to define every possible java profile, only the ones you want to use (and have JDKs for) -->
            </profiles>
        </settings>
        

An alternative is to define the home directories as OS environment variables. For example:

          JAVA_1_8_HOME=$(/usr/libexec/java_home -v 1.8) # MacOS only
          JAVA_1_8_HOME=/path/to/java8/home # Other Unix OSes
          export JAVA_1_8_HOME
          

Once you have configured settings.xml or defined the OS variables you can, for example, compile and test with Java 1.6 using the following command:

            mvn clean test -Pjava-1.6
        

You can also provide the appropriate property definition on the command-line. (However for frequent use it is easier to update the settings file or ensure the OS defines the appropriate variables) This overrides any property setting in the settings.xml file, which in turn overrides the OS environment variable. For example:

            mvn clean test -Pjava-1.6 -DJAVA_1_6_HOME=/home/jenkins/tools/java/latest1.6
        

OSGi Information

OSGi Metadata

In order to use a Commons component (or any libaray) in an OSGi container (for example Apache Felix) then OSGi metadata needs to be included in the MANIFEST.MF file of the component's jar.

Generating the OSGi Metadata

commons-parent is configured to automatically add the OSGi metadata to the component jar's MANIFEST.MF using the maven-bundle-plugin when the package phase is executed:

mvn package

Most components only need to configure the <commons.componentid> property in their pom.xml in the following way:

          <properties>
              <commons.componentid>beanutils</commons.componentid>
          </properties>
        

Custom OSGi configuration

There are a number of other OSGi properties in the commons-parent pom.xml which are used to configure the maven-bundle-plugin. These have sensible defaults, but can be overriden in a component's pom.xml if required. These are:

  • The <commons.osgi.symbolicName> property configures the <Bundle-SymbolicName> instruction
  • The <commons.osgi.export> property configures the <Export-Package> instruction
  • The <commons.osgi.private> property configures the <Private-Package> instruction
  • The <commons.osgi.import> property configures the <Import-Package> instruction
  • The <commons.osgi.dynamicImport> property configures the <DynamicImport-Package> instruction
  • The <commons.osgi.excludeDependencies> should be set to false if the bundle plugin should be able to scan dependency versions and the optional attribute.

Properties

The parent pom defines many properties. These provide the defaults for various aspects of the pom configuration. In most cases, the defaults are the best choice, but in some cases it may be necessary to override the value of a property - for example if a new version of a plugin has been released, and the parent POM has not yet been updated.

Overriding properties

Properties defined in the parent POM can be overriden on the command line, for example:

mvn apache-rat:rat -Dcommons.rat.version=0.11
This works best for temporary overrides. For more permanent overrides, just add the new property definition to the component POM. Please ensure the override is commented, so it can be removed when no longer necessary.

Version properties

Most of the plugin versions defined in the parent POM are defined using properties. For example, commons.rat.version defines the version of Apache RAT. Please see the POM for the list. [The properties are currently located at the end of the POM.]

Configuration properties

There are some properties which control the behavior of the plugins, for example:

  • commons.changes.onlyCurrentVersion - (default false) change this to true to limit the Jira changes list to the current version (any -SNAPSHOT suffix is ignored) only
  • commons.deployment.protocol - (default scp) some people may prefer "scpexe"
  • minSeverity - (default info) the Clirr minimum severity
  • commons.changes.onlyCurrentVersion - (default false) change this to true to force JIRA changes report to use current version only
  • commons.changes.maxEntries - (default 100) override this to increase the number of JIRAs that can be downloaded (provided the JIRA is configured to all it)
  • commons.changes.runOnlyAtExecutionRoot - (default false) override this to cause the changes report to be run at execution root only

Profiles

Java profiles

commons-parent contains some java profiles to compile/test using different versions of Java. See here for details of using the Java profiles.

jacoco profile

Enable this profile to run the Jacoco tool. This requires at least Java 1.5. The profile is not enabled by default. If the file src/site/resources/profile.jacoco exists then the profile is enabled. This allows components to always enable the profile

cobertura profile

Enable this profile to run the Cobertura tool. The profile is not enabled by default. If the file src/site/resources/profile.cobertura exists then the profile is enabled. This allows components to always enable the profile

japicmp profile (since CP41)

Enable this profile to run the japicmp cmp goal during the verify phase. If any change breaks source compatibilty, this will fail the build. This profile will also generate a source compatibilty report during the site lifecycle. This plugin requires building with at least Java 1.7. (source and target can be lower versions) The profile is not enabled by default. If the file src/site/resources/profile.japicmp exists then the profile is enabled. This allows components to always enable the profile

clirr profile (since CP41)

Enable this profile to generate the clirr report during the site lifecycle. The profile is not enabled by default. If the file src/site/resources/profile.clirr exists then the profile is enabled. This allows components to always enable the profile

site-basic profile (since CP37)

This profile disables as many of the optional reports as it can. It is intended for quickly checking the component documentation. The following properties are defined:

        <skipTests>true</skipTests>
        <maven.javadoc.skip>true</maven.javadoc.skip>
        <cobertura.skip>true</cobertura.skip>
        <findbugs.skip>true</findbugs.skip>
        <checkstyle.skip>true</checkstyle.skip>
        <clirr.skip>true</clirr.skip>
        <changes.jira.skip>true</changes.jira.skip>
        <rat.skip>true</rat.skip> <!-- from version 0.12 -->
        <jacoco.skip>true</jacoco.skip>
        <skipSurefireReport>true</skipSurefireReport>

Individual reports can be re-enabled as follows: mvn site -Psite-basic -Dclirr.skip=false

animal-sniffer profile (since CP37)

This profile is enabled by default. It runs the Animal Sniffer plugin on the main code during the "process-classes" phase. The main code base is checked against the API signature for the compiler target version. Restrictions: does not currently check test code; may not find all invalid API usage. The code still needs to be built and tested with the target compiler version before a release. However it should provide an early warning to developers using a more recent version of Java.

The plugin can be temporarily disabled by using the command-line option -Danimal.sniffer.skip. It can be completely disabled for a component (not recommended) by creating an empty file: src/site/resources/profile.noanimal

The profile creates the property animal-sniffer.signature (e.g. java16) from the property maven.compiler.target (e.g. 1.6). For temporary testing purposes, the property animal-sniffer.signature can be overridden on the command-line. The configuration for the plugin defines the signature version using the property commons.animal-sniffer.signature.version. This is defined with the value of 1.0 as almost all signatures are released with that version. If necessary, the property can be overridden on the command line or in the component POM. [For example, the java16 signature comes in 2 versions]. The Codehaus website has documentation on the available signatures

A simple way to run the check is as follows mvn process-classes

release profile

commons-parent contains a release profile for producing releases.

Running the following command will, in addition to creating the jar as normal, will also:

  • produce the source and binary distributions
  • produce the javadoc and sources jars
mvn -Prelease package

You can also combine the -Prelease option with deploy target and the -Ptest-deploy profile to simulate staging to the repository.

release-notes profile

This uses the src/changes.xml file to generate the file RELEASE-NOTES.txt. Requires file src/changes/release-notes.vm. A sample template is available from: https://github.com/apache/commons-parent/blob/master/src/changes/release-notes.vm

mvn changes:announcement-generate -Prelease-notes [-Dchanges.version=nnn]

Defining changes.version allows one to create the RN without first removing the SNAPSHOT suffix from the POM.

javasvn profile

Optional profile to use javasvn instead of the SVN CLI for the buildNumber plugin

Other profiles, not intended for direct use

The pom also includes some helper profiles that are automatically enabled as needed

  • jdk7-plugin-fix-version - updates plugin versions for use under JDK7 (currently Findbugs and Animal Sniffer)
  • svn-buildnumber - adds the build number to the manifests; suppress with -Dbuildnumber.skip
  • parse-target-version - parses maven.compiler.target into javaTarget.[majorVersion|minorVersion|etc] using the build-helper:parse-version goal