Properties and Resource Filtering

9.1. Introduction

Throughout this book, you will notice references to properties which can be used in a POM file. Sibling dependencies in a multi-project 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 seen yet 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 which 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.

9.2. Maven Properties

• 9.2.1. Maven Project Properties
  When a Maven Project Property is referenced, the property name is referencing a property of the Maven Project Object Model (POM). Specifically, you are referencing a property of the org.apache.maven.model.Model class which is being exposed as the implicit variable project. When you reference a property using this implicit variable, you are using simple dot notation to reference a bean property of the Model object. For example, when you reference ${project.version}, you are really invoking the getVersion() method on the instance of Model that is being exposed as project.

The POM is also represented in the pom.xml document present in all Maven projects. Anything in a Maven POM can be referenced with a property. A complete reference for the POM structure is available at Maven POM Reference. The following list shows some common property references from the Maven project.

<dependencies>
    <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>sibling-project</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

• Other Project Property references
  There are hundreds of properties to reference in a POM. A complete reference for the POM structure is available at Maven POM Reference.

For a full list of properties available on the Maven Model object, take a look at the JavaDoc for the maven-model project here JavaDoc.

9.2.2. Maven Settings Properties

You can also reference any properties in the Maven Local Settings file which is usually stored in ~/.m2/settings.xml. This file contains user-specific configuration such as the location of the local repository and any servers, profiles, and mirrors configured by a specific user.
A full reference for the Local Settings file and corresponding properties is available Maven Settings Reference.

9.2.3. Environment Variable Properties

Environment variables can be referenced with the env.* prefix. Some interesting environment variables are listed below:

• env.PATH
• env.HOME
• env.JAVA_HOME
• env.M2_HOME

While they are available, you should always use the Java System properties if you have the choice.

9.2.4. Java System Properties

Maven exposes all properties from java.lang.System. Anything you can retrieve from System.getProperty() you can reference in a Maven property. The following table lists available properties:

9.2.5. User-defined Properties

You can define your own arbitrary properties in a POM or in a Profile.

<project>
    ...
    <properties>
        <arbitrary.property.a>This is some text</arbitrary.property.a>
        <hibernate.version>3.3.0.ga</hibernate.version>
    </properties>
    ...
</project>

9.3. Resource Filtering

You can use Maven to perform variable replacement on project resources. When resource filtering is activated, Maven will scan resources for property references surrounded by ${ and }. This feature is especially helpful when you need to parameterize a build with different configuration values depending on the target deployment platform.

<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="dataSource" 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>

To turn on resource filtering, you need to use the resources child element of the build element in a POM.

<project>
    ...
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
    </build>
    ...
</project>

When the project is built using a profile, Maven will configure the system to connect to the appropriate database using different properties.