Throughout this book, you will notice references to properties that can be used in a POM file. Sibling dependencies in a multiproject build can be referenced using the ${project.groupId} and ${project.version} properties, and any part of the POM can be referenced by prefixing the variable name with “project.” Environment variables and Java System properties can be referenced, as well as values from your ~/.m2/settings.xml file. What you haven’t yet seen is an enumeration of the possible property values and some discussion about how they can be used to help you create portable builds. This chapter provides such an enumeration.

If you’ve been using property references in your POM, you should also know that Maven has a feature called resource filtering that allows you to replace property references in any resource files stored under src/main/resources. By default, this feature is disabled to prevent accidental replacement of property references. This feature can be used to target builds toward a specific platform and to externalize important build variables to properties files, POMs, or profiles. This chapter introduces the resource filtering feature and provides a brief discussion of how it can be used to create portable enterprise builds.

You can use Maven properties in a pom.xml file or in any resource that is being processed by the Maven Resource plugin’s filtering features. A property is always surrounded by ${ and }. For example, to reference the project.version property, one would write:

${project.version}

Some implicit properties are available in any Maven project, namely:

In addition to these implicit properties, a Maven POM, Maven settings, or a Maven profile can define a set of arbitrary, user-defined properties. The following sections provide more detail on the various properties available in a Maven project.

<project>
  ...
  <properties>
    <arbitrary.property.a>This is some text</arbitrary.property.a>
    <hibernate.version>3.3.0.ga</hibernate.version>
  </properties>
  ...
  <dependencies>
    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate</artifactId>
      <version>${hibernate.version}</version>
    </dependency>  
  </dependencies>
  ...
</project>

<project>
  ...
  <profiles>
    <profile>
      <id>some-profile</id>
      <properties>
        <arbitrary.property>This is some text</arbitrary.property>
      </properties>
    </profile>
  </profiles>
  ...
</project>

You can use Maven to perform variable replacement on project resources. When resource filtering is activated, Maven will scan resources for references to Maven property references surrounded by ${ and }. When it finds these references, it will replace them with the appropriate value in much the same way that the properties defined in the previous section can be referenced from a POM. This feature is especially helpful when you need to parameterize a build with different configuration values depending on the target deployment platform.

Often a .properties file or an XML document in src/main/resources will contain a reference to an external resource, such as a database or a network location that needs to be configured differently depending on the target deployment environment. For example, a system that reads data from a database has an XML document that contains the JDBC URL along with credentials for the database. If you need to use a different database in development and a different database in production, you can use a technology such as Java Naming and Directory Interface (JNDI) to externalize the configuration from the application in an application server, or you can create a build that knows how to replace variables with different values depending on the target platform.

Using Maven resource filtering, you can reference Maven properties and then use Maven profiles to define different configuration values for different target deployment environments. To illustrate this feature, assume you have a project that uses the Spring Framework to configure a BasicDataSource from the Apache Commons Database Connection Pool (DBCP) project (http://commons.apache.org/dbcp). Your project may contain a file in src/main/resources named applicationContact.xml that contains the XML listed in Example 13-3.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
       http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

    <bean id="someDao" class="com.example.SomeDao">
        <property name="dataSource" ref="dataSource"/>
    </bean>

    <bean id="dataSource" destroy-method="close" 
             class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="${jdbc.driverClassName}"/>
        <property name="url" value="${jdbc.url}"/>
        <property name="username" value="${jdbc.username}"/>
        <property name="password" value="${jdbc.password}"/>
    </bean>
</beans>

Your program would read this file at runtime, and your build would replace the references to properties such as jdbc.url and jdbc.username with the values you defined in your pom.xml. Resource filtering is disabled by default to prevent any unintentional resource filtering. To turn on resource filter, you need to use the resources child element of the build element in a POM. Example 13-4 shows a POM that defines the variables referenced in Example 13-3 and activates resource filtering for every resource under src/main/resources.

<project>
  ...
  <properties>
    <jdbc.driverClassName>com.mysql.jdbc.Driver</jdbc.driverClassName>
    <jdbc.url>jdbc:mysql://localhost:3306/development_db</jdbc.url>
    <jdbc.username>dev_user</jdbc.username>
    <jdbc.password>s3cr3tw0rd</jdbc.password>
  </properties>
  ...
  <build>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
        <filtering>true</filtering>
      </resource>
    </resources>
  </build>
  ...
  <profiles>
    <profile>
      <id>production</id>
      <properties>
        <jdbc.driverClassName>oracle.jdbc.driver.OracleDriver</jdbc.driverClassName>
        <jdbc.url>jdbc:oracle:thin:@proddb01:1521:PROD</jdbc.url>
        <jdbc.username>prod_user</jdbc.username>
        <jdbc.password>s00p3rs3cr3t</jdbc.password>
      </properties>
    </profile>  
  </profiles>
</project>

The four variables are defined in the properties element, and resource filtering is activated for resources under src/main/resources. Resource filtering is deactivated by default, and to activate it you must explicitly set filtering to true for the resources stored in your project. Filtering is deactivated by default to prevent accidental, unintentional filtering during your build. If you build a project with the resource from Example 13-3 and the POM from Example 13-4, and if you list the contents of the resource in target/classes, you should see that it contains the filtered resource:

$ mvn install
...
$ cat target/classes/applicationContext.xml
...
    <bean id="dataSource" destroy-method="close" 
             class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
        <property name="url" value="jdbc:mysql://localhost:3306/development_db"/>
        <property name="username" value="dev_user"/>
        <property name="password" value="s3cr3tw0rd"/>
    </bean>
...

The POM in Example 13-4 also defines a production profile under the profiles/profile element that overrides the default properties with values that would be appropriate for a production environment. In this particular POM, the default values for the database connection are for a local MySQL database installed on a developer’s machine. When the project is built with the production profile activated, Maven will configure the system to connect to a production Oracle database using a different driver class, URL, username, and password. If you build a project with the resource from Example 13-3 and the POM from Example 13-4, with the production profile activated, and if you list the contents of the resource in target/classes, you should see that it contains the filtered resource with production values:

$ mvn -Pproduction install
...
$ cat target/classes/applicationContext.xml
...
    <bean id="dataSource" destroy-method="close" 
            class="org.apache.commons.dbcp.BasicDataSource">
        <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver"/>
        <property name="url" value="jdbc:oracle:thin:@proddb01:1521:PROD"/>
        <property name="username" value="prod_user"/>
        <property name="password" value="s00p3rs3cr3t"/>
    </bean>
...