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:
1.0
There are some implicit properties available in any Maven project,
these implicit properties are:
-
project.*
-
Maven Project Object Model (POM). You can use the
project.*
prefix to reference values in a Maven POM.
-
settings.*
-
Maven Settings. You use the
settings.*
prefix to reference values
from your Maven Settings in ~/.m2/settings.xml.
-
env.*
-
Environment variables like
PATH
and M2_HOME
can be referenced
using the env.*
prefix.
-
System Properties
-
Any property which can be retrieved from the
System.getProperty()
method can be referenced as a Maven property.
In addition to the implicit properties listed above, a Maven POM,
Maven Settings, or a Maven Profile can define a set of arbitrary,
user-defined properties. The following sections provide some detail on
the various properties available in a Maven project.
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
http://maven.apache.org/ref/3.0.3/maven-model/maven.html.
The following list shows some common property references from the
Maven project.
-
project.groupId
and project.version
-
Projects in a large, multi-module build often share the same
groupId
and version
identifiers. When you are declaring
interdependencies between two modules which share the same
groupId
and version
, it is a good idea to use a property
reference for both:
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>sibling-project</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
-
project.artifactId
-
A project’s artifactId is often used as the name of a
deliverable. For example, in a project with WAR packaging, you will
want to generate a WAR file without the version identifiers. To do
this, you would reference the
project.artifactId
in your POM file
like this:
<build>
<finalName>${project.artifactId}</finalName>
</build>
-
project.name
and project.description
-
The name and project description can often be useful properties to
reference from documentation. Instead of having to worry that all
of your site documents maintain the same short descriptions, you
can just reference these properties.
-
project.build.*
-
If you are ever trying to reference output directories in Maven,
you should never use a literal value like target/classes. Instead
you should use property references to refer to these directories.
-
project.build.sourceDirectory
-
project.build.scriptSourceDirectory
-
project.build.testSourceDirectory
-
project.build.outputDirectory
-
project.build.testOutputDirectory
-
project.build.directory
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.
-
project.baseUri
-
If you need a valid URI for your project’s base directory, you can
use the
${project.baseUri}
property. If your project is stored in
the directory /tmp/simple, ${project.baseUri}
will resolve to
file:/private/tmp/simple/.
-
Other Project Property references
-
There are hundreds of properties to reference in a POM. A complete
reference for the POM structure is available at
http://maven.apache.org/ref/3.0.3/maven-model/maven.html.
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.
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 here
http://maven.apache.org/ref/3.0.3/maven-settings/settings.html.
9.2.3. Environment Variable Properties
Environment variables can be referenced with the env.* prefix. Some
interesting environment variables are listed in the following list:
-
env.PATH
-
Contains the current
PATH
in which Maven is running. The PATH
contains a list of directories used to locate executable scripts
and programs.
-
env.HOME
-
(On *nix systems) this variable points to a user’s home
directory. Instead of referencing this, you should use the
${user.home}
-
env.JAVA_HOME
-
Contains the Java installation directory. This can point to either
a Java Development Kit (JDK) installation or a Java Runtime
Environment (JRE). Instead of using this, you should consider
referencing the ${java.home} property.
-
env.M2_HOME
-
Contains the Maven 2 installation directory.
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.
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:
Table 9.1. Java System Properties
System Property
|
Description
|
java.version
|
Java Runtime Environment version
|
java.vendor
|
Java Runtime Environment vendor
|
java.vendor.url
|
Java vendor URL
|
java.home
|
Java installation directory
|
java.vm.specification.version
|
Java Virtual Machine specification version
|
java.vm.specification.vendor
|
Java Virtual Machine specification vendor
|
java.vm.specification.name
|
Java Virtual Machine specification name
|
java.vm.version
|
Java Virtual Machine implementation version
|
java.vm.vendor
|
Java Virtual Machine implementation vendor
|
java.vm.name
|
Java Virtual Machine implementation name
|
java.specification.version
|
Java Runtime Environment specification version
|
java.specification.vendor
|
Java Runtime Environment specification vendor
|
java.specification.name
|
Java Runtime Environment specification name
|
java.class.version
|
Java class format version number
|
java.class.path
|
Java class path
|
java.ext.dirs
|
Path of extension directory or directories
|
os.name
|
Operating system name
|
os.arch
|
Operating system architecture
|
os.version
|
Operating system version
|
file.separator
|
File separator ("/" on UNIX, "\" on Windows)
|
path.separator
|
Path separator (":" on UNIX, ";" on Windows)
|
line.separator
|
Line separator ("\n" on UNIX and Windows)
|
user.name
|
User’s account name
|
user.home
|
User’s home directory
|
user.dir
|
User’s current working
|
9.2.5. User-defined 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.