A build’s “portability” is a measure of how easy it is to take a particular project and build it in different environments. A build that works without any custom configuration or customization of properties files is more portable than a build that requires a great deal of work to build from scratch. The most portable projects tend to be widely used open source projects such as Apache Commons or Apache Velocity, which ship with Maven builds that require little or no customization. Put simply, the most portable project builds tend to just work out of the box, and the least portable builds require you to jump through hoops and configure platform specific paths to locate build tools. Before we show you how to achieve build portability, let’s survey the different kinds of portability we are talking about.

Clearly, you’ll want to avoid creating the worst-case scenario: the nonportable build. You may have had the misfortune to work or study at an organization that has critical applications with nonportable builds. In such organizations, you cannot deploy an application without the help of a specific individual on a specific machine. In such an organization, it is also very difficult to introduce new project dependencies or changes without coordinating the change with the single person who maintains such a nonportable build. Nonportable builds tend to grow in highly political environments when one individual or group needs to exert control over how and when a project is built and deployed. “How do we build the system? Oh, we’ve got to call Jack and ask him to build it for us; no one else deploys to production.” This is a dangerous situation that is more common that you would think. If you work for this organization, Maven and Maven profiles provide a way out of this mess.

On the opposite end of the portability spectrum are widely portable builds. Widely portable builds are generally the most difficult build systems to attain. These builds restrict your dependencies to those projects and tools that may be freely distributed and are publicly available. Many commercial software packages might be excluded from the most portable builds because they cannot be downloaded before you have accepted a certain license. Wide portability also restricts dependencies to those pieces of software that may be distributed as Maven artifacts. For example, if you depend on Oracle JDBC drivers, your users will have to download and install them manually; this is not widely portable, as you will have to distribute a set of environment setup instructions for people interested in building your application. On the other hand, you could use a JDBC driver that is available from the public Maven repositories such as MySQL or HSQLDB.

As stated previously, open source projects benefit from having the most widely portable builds possible. Widely portable builds reduce the inefficiencies associated with contributing to a project. In an open source project (such as Maven), there are two distinct groups: end users and developers. When an end user uses a project like Maven and decides to contribute a patch to the project, he has to make the transition from using the output of a build to running a build. He first has to become a developer, and if it is difficult to learn how to build a project, this end user has a disincentive to take the time to contribute to a project. In a widely portable project, an end user doesn’t have to follow a set of arcane build instructions to start becoming a developer; she can download the source, modify the source, build, and submit a contribution without asking someone to help her set up a build environment. When the cost of contributing source back to an open source project is lower, you’ll see an increase in source code contributions, especially casual contributions, which can make the difference between a project’s success and a project’s failure. One side effect of Maven’s adoption across a wide group of open source projects is that it has made it easier for developers to contribute code to various open source projects.

Although the previous example showed you how to override the default configuration properties of a single Maven plugin, you still don’t know exactly what a Maven profile is allowed to override. The short answer to that question is that a Maven profile can override almost everything you would have in a pom.xml. The Maven POM contains an element under project called profiles containing a project’s alternate configurations, and under this element are profile elements that define each profile. Each profile must have an id, and other than that, it can contain almost any of the elements one would expect to see under project. The XML document in Example 11-2 shows all of the elements, a profile is allowed to override.

<project>
  <profiles>
    <profile>
      <build>
        <defaultGoal>...</defaultGoal>
        <finalName>...</finalName>
        <resources>...</resources>
        <testResources>...</testResources>
        <plugins>...</plugins>
      </build>
      <reporting>...</reporting>
      <modules>...</modules>
      <dependencies>...</dependencies>
      <dependencyManagement>...</dependencyManagement>
      <distributionManagement>...</distributionManagement>
      <repositories>...</repositories>
      <pluginRepositories>...</pluginRepositories>
      <properties>...</properties>
    </profile>
  </profiles>
</project>

A profile can override an element shown with ellipses. A profile can override the final name of a project’s artifact in a profile, the dependencies, and the behavior of a project’s build via plugin configuration. A profile can also override the configuration of distribution settings depending on the profile. For example, if you needed to publish an artifact to a staging server in a staging profile, you would create a staging profile that overrides the distributionManagement element in a profile.

Activations can contain one or 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 be activated only 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. Example 11-4 lists a profile that is activated by a very specific combination of operating system parameters, properties, and a JDK version.

<project>
  ...
  <profiles>
    <profile>
      <id>dev</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.5</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.2600</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>2.0.5</value>
        </property>
        <file>
          <exists>file2.properties</exists>
          <missing>file1.properties</missing>
        </file>
      </activation>
      ...
    </profile>
  </profiles>
</project>

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

You can activate a profile based on the value of a property such as 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 configuration shown in Example 11-5 activates a profile if the property environment.type is not present during Maven execution.

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

Just like settings profiles, you can also define a set of global profiles in ${M2_HOME}/conf/settings.xml. Profiles defined in this configuration file are available across all users using a specific installation of Maven. The ability to define a global settings profile is useful if you are creating a customized distribution of Maven for a specific organization and you want to ensure that every user of Maven has access to a set of build profiles that ensure in-house portability. If you need to add custom plugin repositories or define a custom set of plugins that are used only by your organization, you could distribute a copy of Maven to your users that has these settings “baked in.” The configuration of global settings profiles is the same as the configuration of user-specific settings profiles.

One of the core motivations for Maven project profiles was to provide for environment-specific configuration settings. In a development environment, you might want to produce bytecode with debug information and configure your system to use a development database instance. In a production environment, you might want to produce a signed JAR and configure the system to use a production database. In this chapter, we defined a number of environments with identifiers such as dev and prod. A simpler way to do this would be to define profiles that are activated by environment properties and to use these common environment properties across all of your projects. For example, if every project had a development profile activated by a property named environment.type having a value of dev, and if those same projects had a production profile activated by a property named environment.type having a value of prod, you could create a default profile in your settings.xml that always set environment.type to dev on your development machine. That way, each project defines a dev profile activated by the same environment variable. Let’s see how this is done; the settings.xml shown in Example 11-9 defines a profile in ~/.m2/settings.xml that sets the environment.type property to dev.

<settings>
  <profiles>
    <profile>
      <activation> 
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <environment.type>dev</environment.type>
      </properties>
    </profile>
  </profiles>
</settings>

This means that every time you run Maven on your machine, this profile will be activated and the property environment.type will have the value dev. You can then use this property to activate profiles defined in a project’s pom.xml. Let’s take a look in Example 11-10 at how a project’s pom.xml would define a profile activated by environment.type having the value dev.

<project>
  ...
  <profiles>
    <profile>
      <id>development</id>
      <activation>
        <property>
          <name>environment.type</name>
          <value>dev</value>
        </property>
      </activation>
      <properties>
        <database.driverClassName>com.mysql.jdbc.Driver</database.driverClassName>
        <database.url>jdbc:mysql://localhost:3306/app_dev</database.url>
        <database.user>development_user</database.user>
        <database.password>development_password</database.password>
      </properties>
    </profile>
    <profile>
      <id>production</id>
      <activation>
        <property>
          <name>environment.type</name>
          <value>prod</value>
        </property>
      </activation>
      <properties>
        <database.driverClassName>com.mysql.jdbc.Driver</database.driverClassName>
        <database.url>jdbc:mysql://master01:3306,slave01:3306/app_prod</database.url>
        <database.user>prod_user</database.user>
      </properties>
    </profile>
  </profiles>
</project>

This project defines some properties such as database.url and database.user, which might be used to configure another Maven plugin configured in the pom.xml. There are plugins available that can manipulate the database and run SQL, and plugins such as the Maven Hibernate3 plugin can generate annotated model objects for use in persistence frameworks. A few of these plugins can be configured in a pom.xml using these properties. These properties can also be used to filter resources. In this example, because we’ve defined a profile in ~/.m2/settings.xml that sets environment.type to dev, the development profile will always be activated when we run Maven on our development machine. Alternatively, if we wanted to override this default, we could set a property on the command line. If we need to activate the production profile, we can always run Maven with:

~/examples/profiles $ mvn install -Denvironment.type=prod

Setting a property on the command line will override the default property set in ~/.m2/settings.xml. We could have just defined a profile with an id of “dev” and invoked it directly with the -P command-line argument, but using this environment.type property allows us to code other project pom.xml files to this standard. Every project in the codebase can have a profile that is activated by the same environment.type property set in every user’s ~/.m2/settings.xml. In this way, developers can share common configuration for development without defining this configuration in nonportable settings.xml files.

This best practice builds on the previous section. In Example 11-10, the production profile does not contain the database.password property. We’ve done this on purpose to illustrate the concept of putting secrets in your user-specific settings.xml. If you were developing an application at a large organization that values security, it is likely that the majority of the development group will not know the password to the production database. In an organization that draws a bold line between the development group and the operations group, this will be the norm. Developers may have access to a development and a staging environment, but they might not have (or want to have) access to the production database. There are a number of reasons why this makes sense, particularly if an organization is dealing with extremely sensitive financial, intelligence, or medical information. In this scenario, the production environment build may be carried out only by a lead developer or by a member of the production operations group. When they run this build using the prod environment.type, they will need to define this variable in their settings.xml, as shown in Example 11-11.

<settings>
  <profiles>
    <profile>
      <activeByDefault>true</activeByDefault>
      <properties>
        <environment.type>prod</environment.type>
        <database.password>m1ss10nimp0ss1bl3</database.password>
      </properties>
    </profile>
  </profiles>
</settings>

This user has defined a default profile that sets the environment.type to prod and also set the production password. When the project is executed, the production profile is activated by the environment.type property and the database.password property is populated. This way, you can put all of the production-specific configuration into a project’s pom.xml and leave out only the single secret necessary to access the production database.

Let’s assume that you have a library or a project that produces platform-specific customizations. Even though Java is platform-neutral, there are times when you might need to write some code that invokes platform-specific native code. Another possibility is that you’ve written some C code that is compiled by the Maven Native plugin and you want to produce a qualified artifact depending on the build platform. You can set a classifier with the Maven Assembly plugin or with the Maven Jar plugin. The pom.xml shown in Example 11-12 produces a qualified artifact using profiles that are activated by operating system parameters. For more information about the Maven Assembly plugin, see Chapter 12.

<project>
  ...
  <profiles>
    <profile>
      <id>windows</id>
      <activation>
        <os>
          <family>windows</family>
        </os>
      </activation>
      <build>
        <plugins>
          <plugin
            <artifactId>maven-jar-plugin</artifactId>
            <configuration>
              <classifier>win</classifier>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
    <profile>
      <id>linux</id>
      <activation>
        <os>
          <family>unix</family>
        </os>
      </activation>
      <build>
        <plugins>
          <plugin>
            <artifactId>maven-jar-plugin</artifactId>
            <configuration>
              <classifier>linux</classifier>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </profile>
  </profiles>
</project>

If the operating system is in the Windows family, this pom.xml qualifies the JAR artifact with “-win”. If the operating system is in the Unix family, the artifact is qualified with “-linux”. This pom.xml successfully adds the qualifiers to the artifacts, but it is more verbose than it needs to be due to the redundant configuration of the Maven Jar plugin in both profiles. This example could be rewritten to use variable substitution to minimize redundancy, as shown in Example 11-13.

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-jar-plugin</artifactId>
        <configuration>
          <classifier>${envClassifier}</classifier>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
  <profiles>
    <profile>
      <id>windows</id>
      <activation>
        <os>
          <family>windows</family>
        </os>
      </activation>
      <properties>
        <envClassifier>win</envClassifier>
      </properties>
    </profile>
    <profile>
      <id>linux</id>
      <activation>
        <os>
          <family>unix</family>
        </os>
      </activation>
      <properties>
        <envClassifier>linux</envClassifier>
      </properties>
    </profile>
  </profiles>
</project>

In this pom.xml, each profile doesn’t need to include a build element to configure the Jar plugin. Instead, each profile is activated by the operating system family and sets the envClassifier property to either win or linux. This envClassifier is then referenced in the default pom.xml build element to add a classifier to the project’s JAR artifact. The JAR artifact will be named ${finalName}-${envClassifier}.jar and included as a dependency using the dependency syntax shown in Example 11-14.

    <dependency>
      <groupId>com.mycompany</groupId>
      <artifactId>my-project</artifactId>
      <version>1.0</version>
      <classifier>linux</classifier>
    </dependency>