Maven: The Complete Reference
9.2. Maven Properties

1.0

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 http://maven.apache.org/ref/3.0.3/maven-model/maven.html. 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>

<build>
    <finalName>${project.artifactId}</finalName>
</build>

sourceDirectory, scriptSourceDirectory, and testSourceDirectory provide access to the source directories for the project. outputDirectory and testOutputDirectory provide access to the directories where Maven is going to put bytecode or other build output. directory refers to the directory which contains all of these output directories.

For a full list of properties available on the Maven Model object, take a look at the JavaDoc for the maven-model project here http://maven.apache.org/ref/3.0.3/maven-model/apidocs/index.html. Once you load this JavaDoc, take a look at the Model class. From this Model class JavaDoc, you should be able to navigate to the POM property you wish to reference. If you needed to reference the output directory of the build, you can use the Maven Model JavaDoc to see that the output directory is referenced via model.getBuild().getOutputDirectory(); this method call would be translated to the Maven property reference ${project.build.outputDirectory}.

For more information about the Maven Model module, the module which defines the structure of the POM, see the Maven Model project page at http://maven.apache.org/ref/3.0.3/maven-model.

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 here http://maven.apache.org/ref/3.0.3/maven-settings/settings.html.

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

While they are available, you should always use the Java System properties if you have the choice. If you need a user’s home directory use ${user.home} instead of ${env.HOME}. If you do this, you’ll end up with a more portable build that is more likely to adhere to the Write-Once-Run-Anywhere (WORA) promise of the Java platform.

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:

In addition to the implicit properties provided by the POM, Maven Settings, environment variables, and the Java System properties, you have the ability to define your own arbitrary properties. Properties can be defined in a POM or in a Profile. The properties set in a POM or in a Maven Profile can be referenced just like any other property available throughout Maven. User-defined properties can be referenced in a POM, or they can be used to filter resources via the Maven Resource plugin. Here’s an example of defining some arbitrary properties in a Maven POM.

User-defined Properties in a POM. 

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

The previous example defines two properties: arbitrary.property.a and hibernate.version. The hibernate.version is referenced in a dependency declaration. Using the period character as a separator in property names is a standard practice throughout Maven POMs and Profiles. The next example shows you how to define a property in a profile from a Maven POM.

User-defined Properties in a Profile in a POM. 

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

The previous example demonstrates the process of defining a user-defined property in a profile from a Maven POM. For more information about user-defined properties and profiles, see Chapter 5, Build Profiles.