Apache Commons logo

commons-parent

This page provides information about the commons-parent pom.xml

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 accross 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 whats specified in the <pluginManagement> section and component pom.xml's should specify the version of additional reports 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 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.

Release

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

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

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.
    • Surefire Report
    • Javadocs
    • Source Cross Reference
  • 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.compile.source} and ${maven.compile.target} properties respectively. [NOTE: the Maven compiler plugin defaults to ${maven.compiler.source} and ${maven.compiler.target}; however for some (historical?) reason the Commons Parent POM has always used ".compile." rather than ".compiler." See https://issues.apache.org/jira/browse/COMMONSSITE-69].

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.compile.source>1.4</maven.compile.source>
              <maven.compile.target>1.4</maven.compile.target>
          </properties> 
        

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.compile.source} and ${maven.compile.target}) are also written out to the component jar's MANIFEST.MF file with the following values:

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

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 (because the build will use the current Java libraries by default). The only way to ensure that components don't accidentally use classes/methods from a later version of Java is to compile and test using actual Java versions.

For this reason commons-parent provides profiles for compiling/testing under different Java versions:

  • java-1.3 for compiling and testing using Java 1.3
  • java-1.4 for compiling and testing using Java 1.4
  • java-1.5 for compiling and testing using Java 1.5
  • java-1.6 for compiling and testing using Java 1.6

In order for these profiles to work, you need to configure the JAVA_1_3_HOME, JAVA_1_4_HOME, JAVA_1_5_HOME and JAVA_1_6_HOME properties in your settings.xml file (or as environment variables or even command-line properties). See here for details. Each property should be set to the directory where the relevant version of the JDK is installed.

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>
                <profile>
                    <id>java-1.3</id>
                    <properties>
                        <JAVA_1_3_HOME>C:\j\jdk1.3.1_18</JAVA_1_3_HOME>
                    </properties>
                </profile>
                <profile>
                    <id>java-1.4</id>
                    <properties>
                        <JAVA_1_4_HOME>C:\j\jdk1.4.2_19</JAVA_1_4_HOME>
                    </properties>
                </profile>
                <profile>
                    <id>java-1.5</id>
                    <properties>
                        <JAVA_1_5_HOME>C:\j\jdk1.5.0_22</JAVA_1_5_HOME>
                    </properties>
                </profile>
                <profile>
                    <id>java-1.6</id>
                    <properties>
                        <JAVA_1_6_HOME>C:\j\jdk1.6.0_17</JAVA_1_6_HOME>
                    </properties>
                </profile>
            </profiles>
        </settings>
        

(Since the values are the locations of the Java installations on your local machine, they are unlikely to change frequently and using the settings.xml file will be the most convenient).

Once you have configured those properties you can, for example, compile and test with Java 1.4 using the following command:

            mvn -Pjava-1.4 clean test
        

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

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.

rc profile

commons-parent contains an rc profile for producing release candidates.

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 -Prc package

Running the following command will, as well as doing producing everything specified above for the package command, also sign the artifacts and create checksums (in local m2 repo):

mvn -Prc install

release profile

commons-parent contains an release profile for producing releases. This is the same as the rc profile except the repository and snapshotRepository locations are different.

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

trunks-proper profile

commons-parent contains a trunks-proper profile with the components set up as <modules>. This is a convenience profile so that Maven commands can be run for all components.

N.B. This profile works with http://svn.apache.org/repos/asf/commons/trunks-proper/ which, you need to check out first (it pulls in the trunks of the components using an svn:externals property - see here for more details).

For example, if the template for the download page was changed, you could re-generate the download pages for all components using the following command:

mvn -Ptrunks-proper commons:download-page

...or to test all components:

mvn -Ptrunks-proper clean test

trunks-sandbox profile

commons-sandbox-parent contains a trunks-sandbox profile with the sandbox components set up as <modules>. This is a convenience profile so that Maven commands can be run for all sandbox components.

N.B. This profile works with http://svn.apache.org/repos/asf/commons/trunks-sandbox/ which, you need to check out first (it pulls in the trunks of the sandbox components using an svn:externals property - see here for more details).

For example, if the template for the sandbox issue tracking page was changed, you could re-generate the issue tracking pages for all sandbox components using the following command:

mvn -Ptrunks-sandbox commons:sandbox-jira-page

...or to test all sandbox components:

mvn -Ptrunks-sandbox clean test