More Advanced Project Build and Deployment

As stated before, Maven uses a default value for a property if there is one when they are not overridden by a user. Some properties do not have default values because the plugin authors may not have been able to foresee a reasonable value that would work in most cases. Maven has some built-in properties that can be overridden and each plugin has a set of properties. Overriding properties can be done in two ways, either on the command-line (which has highest overriding priority) or in a properties file. Typically, command-line property settings are used for one-time settings, whereas property file settings are used to provide default values for the local or company-wide build environment.

Command-line overriding is done by passing the -D option to Maven:

maven -Dmaven.repo.local=/usr/local/maven/repository jar:install

In the above example, we're overriding the ${maven.repo.local} property (built-in Maven property), using the jar:install goal to install our artifact jar file in '/usr/local/maven/repository' rather then the default location '${user.home}/.maven/repository'.

Property files are just name value pairs in the same format as the command-line -D option:

maven.repo.remote=http://www.ibiblio.org/maven/,http://source.concord.org/repository/
maven.username=maven
maven.xdoc.date=left
maven.multiproject.basedir=..

Here, we have set a number of properties for various goals. There are typically three types of property files (listed in reverse order of priority) that are parsed by Maven:

${basedir}/project.properties
${basedir}/build.properties
${user.home}/build.properties

Our projects typically use only the project.properties file. The build.properties files are usually reserved for user specific settings.

Adding dependencies

When you have a project that is dependent on another project, the project.xml file needs to be modified to specify what the dependency is. This is done by specifying the properties that make an element unique; specifically the artifactId, groupId, dependency type, and version:

<dependencies>
    <dependency>
      <groupId>commons-jelly</groupId>
      <artifactId>commons-jelly-tags-log</artifactId>
      <version>1.0</version>
      <type>jar</type>
    </dependency>

    <dependency>
      <groupId>concord</groupId>
      <artifactId>maven-ccPlugin-plugin</artifactId>
      <version>1.0.0</version>
      <type>plugin</type>
    </dependency>
</dependencies>

Here we are showing two types of dependencies. The first shows a jar dependency and the second shows a plugin dependency. In both cases, the dependency will be downloaded once from the remote repository and installed into the '${maven.home.local}/repository' directory. If the dependency is a plugin, it will then be expanded into '${maven.home.local}/cache'. If we changed the version to SNAPSHOT, the SNAPSHOT version of the dependency would be downloaded everytime Maven is run. SNAPSHOT is normally used during development, whereas a specific version is used for released versions of dependencies. This typically locks the behavior of the dependency being built against anomalies from changes in the dependency.

As described earlier, the artifactId, version, and type specify the dependency name. The groupId is used to group artifacts together, like all the artifacts from one company could use it's company name to group the artifacts together to keep them from colliding against other artifacts with similar names. Remember, the Maven group is part of the open source community and wants all publicly available java projects built and deployed on it's central repository for accessibility by all java developers. All of Concord Consortium's projects should use something like 'concord' or 'concord-consortium' as the groupId, but it isn't in that form at the moment.

In order to avoid downloading a dependency, especially a SNAPSHOT jar file, the ${maven.jar.override} property is available. To use it, it just needs to be set to 'on' and specify the jar file that should be overridden. There are two ways o override a jar file, using a path to an alternative jar file or using a version. When specifying a version, that version must exist in your local repository, whereas specifying the path points directly to the jar to use. This is the two forms allowed:

maven.jar.artifactId = <path to jar file to use>
maven.jar.artifactId = <version number in local repository>

An example usage of a path override would be to specify the following on the command line or in a project.properties file:

maven.jar.override=on
maven.jar.datagraph=../DataGraph/lib/datagraph-1.1.0.jar

or using a version override:

maven.jar.override=on
maven.jar.datagraph=SNAPSHOT

The second case would be especially useful if you are testing a new version of a dependency that has a specific version in the project.xml file.

Maven plugins

There are a wide array of Maven plugins available. Plugins are jar files that may or may not have any Java classes, but will definitely contain Jelly code. In fact, when it comes time to develop your own plugins, the easiest way to learn Jelly will probably be to download the source of a Maven plugin and look at the maven.xml file for it. Anyway, the plugins contain the goals that are used for all Maven tasks.

After using Maven for some time, you will most undoubtably be visiting Maven's plugin page to find out what goals and properties are available for each plugin. The individual plugin pages are built using Maven, so they have a menu on the left-hand side of each plugin homepage:

plugin menu

This image is from the Maven Changes plugin, but is typical of any Maven plugin homepage. The menus have a link to the plugin goals and one to the plugin properties.

Modifying default goal behavior

If you need to modify the behavior of a goal and a property setting is not available to make the modification, Maven allows you to create a project maven.xml file with pre and/or post scripting for the goal to be modified. This is where the real power of Maven lies, but it is suggested to avoid using project specific maven.xml files, but rather, do things the Maven way or create plugins for goals, which we do later. In our example below, which would be in the ${basedir} of our project, we want to put the artifact jar file in a 'lib' directory rather than the default 'target' directory:

<?xml version="1.0"?>
<project 
  xmlns:ant="jelly:ant">

  <!--
     Since setting maven.build.dir or maven.build.dest will effect most built
     residuals, create this post goal to get just the jar file into the lib directory
  -->
  <postGoal name="jar:jar">
    <ant:mkdir dir="${basedir}/lib" />
    <ant:copy file="${maven.build.dir}/${maven.final.name}.jar" todir="${basedir}/lib" />
  </postGoal>

  <!--
     Extend the cleanup to remove the extra 'lib' directory
  -->
  <postGoal name="clean:clean">
    <!-- Delete the lib directory -->
    <ant:delete dir="${basedir}/lib" />
  </postGoal>
</project>

The first thing of note is the namespacing that is done in the opening <project> tag. The xmlns:ant="jelly:ant" attribute is associating the namespace 'ant' with the jelly ant tag library. Each tag library has a tag (action) and associated attributes (properties). The ant tag library is one of the most useful, especially if you know Apache Ant fairly well.

The next thing in the maven.xml file is the <postGoal> element for the jar:jar goal. This section of Jelly code will be run everytime after jar:jar has run if it doesn't fail. In this code, we use the mkdir and copy ant tags to create the lib directory and copy the artifact jar to the lib directory. We also created a post goal for the clean:clean goal to delete the lib directory we created.

That's all there is to modifying goal default behavior. See Jelly Hints for more information.

Remote deployment

Now let's say you have the build working the way you want it and you are ready to share your new jar file with the rest of your development group. Assuming you have an http or ftp server that you are able to deploy and download from, you would modify your project.xml file in a manner similar to the following:

<url>http://source.concord.org/</url>
<siteAddress>source.concord.org</siteAddress>
<siteDirectory>/var/www/source.concord.org/html/software/${pom.artifactId}</siteDirectory>


<distributionSite>source.concord.org</distributionSite>
<distributionDirectory>/var/www/source.concord.org/html/software/repository</distributionDirectory>

As you can see from some of the comments, the first part is for the deployed documents and website created by the 'site:deploy' goal. The second set of properties are for the 'dist:deploy' and 'jar:deploy' goals, the latter being the goal we are most interested at this point. This scheme makes it necessary for a remote login, either ssh or rlogin to the remote server. Then you can run the goals previously mentioned to deploy the artifacts. To download the artifacts from the remote server, you will need to specify the '${maven.repo.remote}' property on the command line or in the project.properties file of the dependent project:

maven.repo.remote=http://www.ibiblio.org/maven/,http://source.concord.org/repository/

This example matches the project.xml code above it. Notice we can have multiple repositories separated by a comma. The trailing '/', as well as the order of repositories is also important.

We have a customized goal for jnlp deployment as described in 'ccjnlp:deploy'. More information describing remote deployment is in the Repository Building page.