Section 2.8. Overriding Properties

2.8. Overriding Properties

You have seen that specifying a property on the command line overrides a property defined in project.properties, and you've seen that plug-in properties are superseded by project.properties. Now that you've seen property overrides in action, take a look at how you can use property overriding to customize behavior for a specific project or a specific user.

2.8.1. How do I do that?

In the "Customizing Plug-in Behavior" lab earlier in this chapter, you set the maven.axis.serverside variable in your project.properties file. Try running the axis:wsdl2java goal and setting the maven.axis.serverside property to true:

maven axis:wsdl2java -Dmaven.axis.serverside=true

If you run this, you should see Maven generating a number of different classes and some deployment descriptors for an Apache Axis SOAP service. By setting the maven.axis.serverside property from the command line, you have just overridden the value specified in project.properties. Properties set from the command line take precedence over properties set anywhere else in Maven.

In fact, Maven has a hierarchy of properties files which you can use to customize a build for a specific project or a specific user. Maven reads properties from the following sources, in the order shown:

${basedir}/project.properties

This file is a sibling to both maven.xml and project.xml. This file customizes behavior for a particular project.

${basedir}/build.properties

This file is also a sibling to maven.xml and project.xml, but this file is used to customize a specific project's build for a specific user. If you need to change the value of a property for your own build environment but you don't want to affect the properties of other users, add a build.properties file to ${basedir}. Values defined in this file will override values defined in project.properties. build.properties should not be checked into source control; this file is for an individual user to tailor the behavior of a specific project.

${user.home}/build.properties

Your home directory can contain a build.properties file which contains user-specific properties to be used on all projects. This is the proper file in which to configure properties for a proxy server or a remote repository. Properties defined in this file are read for every project, and they supersede the values set in the previous two files.

System properties (specified with the -D flag)

You've seen this a great deal in this chapter. Setting the value of a property on the command line supersedes all other configuration files. This is the final stop for properties.

In Chapter 3 you will see how projects can inherit properties from parent projects, and Figure 3-3 illustrates the multilayered override mechanism introduced in this lab. As you will also see in Chapter 3, when a project extends another project, it also inherits the properties defined in the parent project's project.properties and build.properties files.

2.8.2. What just happened?

There are different use cases for using different configuration levels. Something like proxy server configuration is specific to your configuration, and it might be something that is universal to Maven projects you are working with. In this case, universal, user-specific configuration should go into a build.properties file in your own home directory. In another case, you may have a specific property which only you need to set for a specific project; for example, if you are the release manager for a specific project, you may need to set a maven.username property. This kind of user- and project-specific property configuration should be stored in ${basedir}/build.properties. ${basedir}/build.properties is a file which you maintain on your local machine (it is not added to a project's source code repository), and it is a mechanism for you to modify the behavior of a specific project to suit your needs. Projects used in a corporate environment demand different configuration values than open source projects using Maven. You may find yourself using the same ${basedir}/build.properties file for a set of related projects, and defining global defaults in your ${user.home}/build.properties file.

If you need to configure properties for a project and you would like to share these properties with other developers, add such properties to ${basedir}/project.properties. This file is checked into source control, and is the project-specific mechanism for setting project configuration.