Maven: The Complete Reference

5.3. Profile Activation

In the previous section we showed you how to create a profile that overrides default behavior for a specific target environment. In the previous build the default build was designed for development and the production profile exists to provide configuration for a production environment. What happens when you need to provide customizations based on variables like operating systems or JDK version? Maven provides a way to "activate" a profile for different environmental parameters, this is called profile activation.

Take the following example, assume that we have a Java library that has a specific feature only available in the Java 6 release: the Scripting Engine as defined in JSR-223. You’ve separated the portion of the library that deals with the scripting library into a separate Maven project, and you want people running Java 5 to be able to build the project without attempting to build the Java 6 specific library extension. You can do this by using a Maven profile that adds the script extension module to the build only when the build is running within a Java 6 JDK. First, let’s take a look at our project’s directory layout and how we want developers to build the system.

When someone runs mvn install with a Java 6 JDK, you want the build to include the simple-script project’s build, when they are running in Java 5, you would like to skip the simple-script project build. If you failed to skip the simple-script project build in Java 5, your build would fail because Java 5 does not have the ScriptEngine on the classpath. Let’s take a look at the library project’s pom.xml:

Dynamic Inclusion of Submodules Using Profile Activation. 

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.sonatype.mavenbook</groupId>
    <artifactId>simple</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>simple</name>
    <url>http://maven.apache.org</url>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
    <profiles>
        <profile>
            <id>jdk16</id>
            <activation> (1)
                    <jdk>1.6</jdk>
            </activation>
            <modules> (2)
                    <module>simple-script</module>
            </modules>
        </profile>
    </profiles>
</project>

If you run mvn install under Java 1.6, you will see Maven descending into the simple-script subdirectory to build the simple-script project. If you are running mvn install in Java 1.5, the build will not try to build the simple-script submodule. Exploring this activation configuration in more detail:

(1)

The activation element lists the conditions for profile activation. In this example, we’ve specified that this profile will be activated by Java versions that begin with "1.6". This would include "1.6.0_03", "1.6.0_02", or any other string that began with "1.6". Activation parameters are not limited to Java version, for a full list of activation parameters, see Section 5.3.1, “Activation Configuration”.

(2)

In this profile we are adding the module simple-script. Adding this module will cause Maven to look in the simple-script/ subdirectory for a pom.xml.

5.3.1. Activation Configuration

Activations can contain one of more selectors including JDK versions, Operating System parameters, files, and properties. A profile is activated when all activation criteria has been satisfied. For example, a profile could list an Operating System family of Windows, and a JDK version of 1.4, this profile will only be activated when the build is executed on a Windows machine running Java 1.4. If the profile is active then all elements override the corresponding project-level elements as if the profile were included with the -P command-line argument. The following example, lists a profile which is activated by a very specific combination of operating system parameters, properties, and a JDK version.

Profile Activation Parameters: JDK Version, OS Parameters, and Properties. 

<project>
    ...
    <profiles>
        <profile>
            <id>dev</id>
            <activation>
                <activeByDefault>false</activeByDefault> (1)
                    <jdk>1.5</jdk> (2)
                        <os>
                            <name>Windows XP</name> (3)
                                <family>Windows</family>
                                <arch>x86</arch>
                                <version>5.1.2600</version>
                        </os>
                        <property>
                            <name>customProperty</name> (4)
                                <value>BLUE</value>
                        </property>
                        <file>
                            <exists>file2.properties</exists> (5)
                                <missing>file1.properties</missing>
                        </file>
            </activation>
            ...
        </profile>
    </profiles>
</project>

This previous example defines a very narrow set of activation parameters. Let’s examine each activation criterion in detail:

(1)

The activeByDefault element controls whether this profile is considered active by default.

(2)

This profile will only be active for JDK versions that begin with "1.5". This includes "1.5.0_01", "1.5.1".

(3)

This profile targets a very specific version of Windows XP, version 5.1.2600 on a 32-bit platform. If your project uses the native plugin to build a C program, you might find yourself writing projects for specific platforms.

(4)

The property element tells Maven to activate this profile if the property customProperty is set to the value BLUE.

(5)

The file element allows us to activate a profile based on the presence (or absence) of files. The dev profile will be activated if a file named file2.properties exists in the base directory of the project. The dev profile will only be activated if there is no file named file1.properties file in the base directory of the project.

5.3.2. Activation by the Absence of a Property

You can activate a profile based on the value of a property like environment.type. You can activate a development profile if environment.type equals dev, or a production profile if environment.type equals prod. You can also activate a profile in the absence of a property. The following configuration activates a profile if the property environment.type is not present during Maven execution.

Activating Profiles in the Absence of a Property. 

<project>
    ...
    <profiles>
        <profile>
            <id>development</id>
            <activation>
                <property>
                    <name>!environment.type</name>
                </property>
            </activation>
        </profile>
    </profiles>
</project>

Note the exclamation point prefixing the property name. The exclamation point is often referred to as the "bang" character and signifies "not". This profile is activated when no ${environment.type} property is set.