Sonatype

jar

Jar is the default packaging type, the most common, and thus the most commonly encountered lifecycle configuration.

• process-resources - resources:resources
• compile - compiler:compile
• process-test-resources - resources:testResources
• test-compile - compiler:testCompile
• test - surefire:test
• package - jar:jar
• install - install:install
• deploy - deploy:deploy

pom

POM is the simplest packaging type. The artifact that it generates is itself only, rather than a jar or ejb package.

• package - site:attach-descriptor
• install - install:install
• deploy - deploy:deploy

maven-plugin

You will notice that this packaging type is similar to jar with three additions: plugin:descriptor, plugin:addPluginArtifactMetadata, and plugin:updateRegistry. These goals generate a descriptor file and perform some modifications to the repository data. We cover Maven plugins in more detail in the Using Plugins Chapter. For now just know that every one of the goals bound to the lifecycle phase are themselves packaged in plugins that were built with the maven-plugin lifecycle implementation. How's that for bootstrapping?

• generate-resources - plugin:descriptor
• process-resources - resources:resources
• compile - compiler:compile
• process-test-resources - resources:testResources
• test-compile - compiler:testCompile
• test - surefire:test
• package - jar:jar, plugin:addPluginArtifactMetadata
• install - install:install, plugin:updateRegistry
• deploy - deploy:deploy

ejb

EJBs, or Enterprise Java Beans, are a common data access mechanism for model-driven development in JavaEE, and Maven provides support for EJB 2 and 3. Though you must configure the ejb plugin to specifically package for EJB3, else the plugin defaults to 2.1 and demands certain EJB configuation files.

• process-resources - resources:resources
• compile - compiler:compile
• process-test-resources - resources:testResources
• test-compile - compiler:testCompile
• test - surefire:test
• package - ejb:ejb
• install - install:install
• deploy - deploy:deploy

war

The war packaging type is similar to the jar and ejb types (notice a pattern here?). The exception being the package goal of war:war. Note that the war:war plugin requires a web.xml configuration in your src/main/webapp/WEB-INF/ directory. More on quirks like these later.

• process-resources - resources:resources
• compile - compiler:compile
• process-test-resources - resources:testResources
• test-compile - compiler:testCompile
• test - surefire:test
• package - war:war
• install - install:install
• deploy - deploy:deploy

ear

EARs are probably the simplest Java EE constructs, consisting primarily of the deployment descriptor (application.xml) file, some resources and some modules. The ear plugin offers a nice addition to the build process in the ear:generate-application-xml goal. It generates the application.xml based upon the configuration in the EAR project's POM, although this is not required since you may provide your own file if so desired, which the ear:ear goal will use when packaging.

• generate-resources - ear:generate-application-xml
• process-resources - resources:resources
• package - ear:ear
• install - install:install
• deploy - deploy:deploy

par

The par type may be a little esoteric for some people.

• process-resources - resources:resources
• compile - compiler:compile
• process-test-resources - resources:testResources
• test-compile - compiler:testCompile
• test - surefire:test
• package - par:par
• install - install:install
• deploy - deploy:deploy

Note that this list is not exhaustive of every packaging type available for Maven. There are more available through external projects, such as the NAR (native archive) packaging type. They require two things, however: access to their remote repository (by default the only repository available is Maven Central, check the SuperPOM), and the packaging plugin must be added as a build extension. The build extension is merely a mechanism to allow you to add a project's artifact into Maven's execution classpath... much simpler and more portable than manually adding "-cp /path/to/project.jar" to the mvn execution script.

As an example on how this is done, let us use the Codehaus Mojo project's jboss-sar packaging type - to create a deployable JMX Service Archive (SAR) project for JBoss.

<project>
  ...
  <package>jboss-sar</package>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>jboss-packaging-maven-plugin</artifactId>
        <version>2.0-SNAPSHOT</version>
        <extensions>true</extensions>
      <plugin>
    </plugins>
  </build>
  ...
  <repositories>
    <repository>
      <id>Codehaus Snapshots</id>
      <url>http://snapshots.repository.codehaus.org/</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </repository>
  </repositories>
  <pluginRepositories>
    <pluginRepository>
      <id>Codehaus Snapshots</id>
      <url>http://snapshots.repository.codehaus.org/</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
    </pluginRepository>
  </pluginRepositories>
  ...
</project>

We will cover presicely how to create your own packaging type later on in this chapter, but this example should give you an idea on what is required to use it.

This should give a basic understanding of the default build lifecycle, how to use it, extend it, and how to use the packaging type in the POM for altering the functions of the build phases.

Resources

The first is the process-resources phase, implemented by the resources:resources goal. As mentioned above, the process-resources phase processes the resources to the destination directory. What does this mean to "process" resources? In the default case, this means simply to copy the files from the src/main/resources directory to target/classes (the ${project.build.outputDirectory}) - but there is a more advanced behavior makes this seemingly benign phase interesting: filters. Filters are used by the resources plugin to replace the values in text files with properties in the standard ${...} form. It has been said (seriously) that people come to Maven for the dependency management, but stay for the filtering.

For example, let us say that you have a project with an xml file src/main/resources/META-INF/service.xml. Rather than create one file per distribution, you create a skeleton file, replacing actual values with \${...} delimited properties.

<service>
  <!-- This URL was set by project version ${project.version} -->
  <url>${jdbc.url}</url>
  <user>${jdbc.username}</user>
  <password>${jdbc.password}</password>
</service>

There is also a file src/main/filters/default.properties. These types of "filter files" contains name=value pairs which will replace \${name} strings within filtered resources.

jdbc.url=jdbc:hsqldb:mem:mydb
jdbc.username=sa
jdbc.password=

In the project's POM we specify two items, a list of files that contain properties to filter by, and a flag to Maven that the resources directory is to be filtered (by default it is not, and will merely be copied to the target directory).

<build>
  <filters>
    <filter>src/main/filters/default.properties</filter>
  </filters>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

Note: The resources directory is not required to be under src/main/resources, this is simply the default that we adhere to for this example.

Filtering resources do not require using filter files since you can filter with any Maven properties (like we did with \${project.version}, a default POM property). What good is this? Did we not just move the configuration from the resource file to the POM? Yes, in this limited example case. Let's take a look at the KillerApp. In the killerapp-cli project we use a custom resources directory and filters to match the jar's final name.

        <resources>
          <resource>
            <filtering>true</filtering>
            <directory>${basedir}/src/main/command</directory>
            <includes>
              <include>killerapp.bat</include>
            </includes>
            <targetPath>..</targetPath>
          </resource>
        </resources>

The command-line bat file generated in turn, converts the killerapp.bat file from this:

@echo off
java -jar ${project.build.finalName}-jar-with-dependencies.jar %*

to this:

@echo off
java -jar killerapp-cli-1.0-SNAPSHOT-jar-with-dependencies.jar %*

Compile

The compile phase is straightforward enough. All you usually need to know in normal operations is that the compiler:compile goal assumes you are compiling JDK 1.3 complient code. If you wish to use a different version, you must configure.

<project>
  ...
  <build>
    ...
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source>
          <target>1.5</target>
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

Notice we are configuring the plugin maven-compiler-plugin, and not the specific goal compile:compile (in other words, the configuration element is under the plugin element, and not under execution element as we have used it before). When you configure the plugin, the settings are propogated to all of a plugin's executed goals, therefore, the compile:testCompile goal bound to the test-compile phase will be set with a JDK 1.5 source and target as well.

Test Resources

process-test-resources is similar to process-resources. The glaring difference being that you define test resources in the POM under the element testResources with a set of children testResource, and they are copied to target/test-classes (the ${project.build.testOutputDirectory}). All other things are equal.

Test

The test phase is bound by surefire:test. Surefire executes files ending with *Test.java by default, though other values may be set (see Appendix B for more information). JUnit tests are executed by default, although others like TestNG are available. You can add TestNG as a dependency to your test project, just like you would with JUnit (remember chapter 2?) but with the extra classifier element.

<project>
  ...
  <dependencies>
    <dependency>
      <groupId>org.testng</groupId>
      <artifactId>testng</artifactId>
      <version>4.7</version>
      <scope>test</scope>
      <classifier>jdk14</classifier>
    </dependency>

If you wish to use Java 5 annotations rather than JDK 1.4 javadoc annotations, change the classifier to jdk15.

Installation and deployment to local and remote repositories will be covered in a later chapter.

site

Up until now we have focused clearly on the concept of building and placing artifacts to the repositories. But Maven can do more than simply generate code, it is also well equiped to generate documentation and reports about the project, or a collection of projects (aggregation). This is such an important task of Maven that "site" generation has its own lifecycle. The site lifecycle contains four phases:

• pre-site
• site - generate the site and reports
• post-site
• site-deploy - deploys the site to a remote server

The default goals bound to the site lifecycle is:

• site - site:site
• site-deploy - site:deploy

Unlike the default build lifecycle - but similar to clean - the packaging type does not tend to alter this lifecycle since packaging types are concerned primarily with artifact creation, not with the type of site generated. This is actually a good thing as sites of all types will get a similar look-and-feel.

The site plugin is a powerful thing in Maven. It kicks off the execution of Doxia document generation and other report generation plugins.

mvn site

We will cover site and report generation in depth in Site Generation and the Reporting chapters, respectively.