Maven: A Developer's Notebook

Starting a New Project

Part of the hassle of setting up a new project is the amount of effort involved in creating a "development infrastructure"—automated builds, unit tests, documentation, project reporting, etc. Using Maven, you can accelerate this process by generating a skeleton project which can be used as a seed for new applications.

How do I do that?

Maven has an Application Generation plug-in (Genapp) which you can use to create a new project. Start by creating an empty c:\dev\mavenbook\code\genapp\test-application directory that will house the generated application. Run the Genapp plug-in by executing the genapp goal, selecting the default template, and supplying some information about your new project:

C:\dev\mavenbook\code\genapp\test-application>maven genapp
 _ _  _ _
|  \/  |_ _ _Apache_ _ _ _ _
| |\/| / _` \ V / -_) ' \  ~ intelligent projects ~
|_|  |_\_ _,_|\_/\_ _ _|_||_|  v. 1.0.2
  
Attempting to download commons-jelly-tags-interaction-20030211.143817.jar.
4K downloaded
Enter a project template to use: [default]
[Enter]
Please specify an id for your application:  [app]
test-application
Please specify a name for your application:  [Example Application]
Test Application
Please specify the package for your application:  [example.app]
mdn.testapp
build:start:
  
genapp:
    [copy] Copying 1 file to C:\dev\mavenbook\code\genapp\test-application\src\java\
mdn\testapp
    [copy] Copying 3 files to C:\dev\mavenbook\code\genapp\test-application\src\test\
mdn\testapp
    [copy] Copying 1 file to C:\dev\mavenbook\code\genapp\test-application\
    [copy] Copying 2 files to C:\dev\mavenbook\code\genapp\test-application\
BUILD SUCCESSFUL

This plug-in asks the user for some input, and from this output you can see that you are using the default application template, and you are supplying an application ID, application name, and package for the new project. The default application template creates a single class, mdn.testapp.App, with a static main function and two JUnit tests.

Maven's Application Generation plug-in generated the following files and directories:

test-application/
    project.properties
    project.xml
    src/
        conf/
            app.properties
        java/mdn/testapp/
            App.java
        test/mdn/testapp/
            AbstractTestCase.java
            AppTest.java
            NaughtyTest.java

All Maven projects have a standard directory structure which is referenced in a project's Project Object Model (POM), as described shortly. If you have a few existing classes you want to add to a project, add them to src/java, and if you have any unit tests add them to src/test. If these existing classes and unit tests depend on any external libraries, you'll see how to add a dependency later in this chapter. The xdocs directory contains project documentation in XDoc format.

Tip

Please note that the version of the Genapp plug-in that ships with Maven 1.0.2 creates a nonstandard project layout. src/java and src/test are no longer viewed as the proper location for source code and unit tests in a Maven project. Instead of src/java, you should use src/main/java and src/test/java. To change this, alter your project.xml file; change the reference to src/java to src/main/java and src/test to src/test/java. For more information, see "Maven Conventions" at http://maven.apache.org/reference/conventions.html.

project.xml is the project's descriptor; it is an XML file that contains the POM. Let's take a look at a copy of project.xml which has been customized for this project:

<project>
  <pomVersion>3</pomVersion>
  <artifactId>test-application</artifactId>
  <name>Test Application</name>
  <currentVersion>1.0</currentVersion>
  
  <organization>
    <name>Your Organization</name>
    <url>http://www.someorganization.biz/</url>
    <logo>http://www.someorganization.biz/logo.gif|jpg|...</logo>
  </organization>
  
  <inceptionYear>2005</inceptionYear>
  
  <package>mdn.testapp</package>
  
  <logo>http://yourproject/logo.jpg|gif|...</logo>
  <description>
    An example project
  </description>
  
  <shortDescription>
    How to use maven in different situations
  </shortDescription>
  
  <!-- Many Elements Omitted (see generated POM) -->
  
  <dependencies/>
  
  <build>
    <sourceDirectory>src/java</sourceDirectory>
    <unitTestSourceDirectory>src/test</unitTestSourceDirectory>
    <unitTest>
      <includes>
        <include>**/*Test.java</include>
      </includes>
      <excludes>
        <exclude>**/NaughtyTest.java</exclude>
      </excludes>
    </unitTest>
    <resources>
      <resource>
        <directory>src/conf</directory>
        <includes>
          <include>*.properties</include>
        </includes>
      </resource>
    </resources>
  </build>
</project>

This file tells Maven all about your project. The build element locates source code, unit tests, and resources to be packaged with your application. name, artifactId, currentVersion, inceptionYear, description, and shortDescription identify the project and provide information used to name the artifact created from this project.

Tip

If you are working with an existing Maven project, you may see the id element in place of the artifactId element. The id element has been deprecated, and you should use artifactId instead.

The resources element is used by the JAR plug-in to copy resources to a JAR artifact. In this element you specify a set of resources in resource tags. In this example, the resources from src/conf will be copied to the root of the classpath. In other words, the app.properties resource will be copied to the root of the generated JAR artifact. If you wanted all *.properties resources and *.xml resources in src/conf to be available in the mdn.testapp package of the generated JAR, you would specify a targetPath as follows:

Note

Artifact? What is that? An artifact is the output of a given project. This can be a JAR, WAR, SAR, RAR, and more.

<resource>
  <directory>src/conf</directory>
  <targetPath>mdn/testapp</targetPath>
  <includes>
    <include>*.properties</include>
    <include>*.xml</include>
  </includes>
</resource>

project.properties lets you customize the behavior of Maven and Maven plug-ins for this project. You will be using this file later in this book to customize the look and feel of a generated web site, and the contents of a JAR file.

Tip

Maven also maintains a great set of online documentation. For a quick-start guide to creating a new Maven project without the Genapp plug-in, see "The Ten Minute Test" by Brett Porter, at http://maven.apache.org/start/ten-minute-test.html.

What about...

...Maven's ability to track information about a collaborative project?

To simplify this example, we have removed some elements from the project.xml file shown earlier that describe a project's mailing lists, source repository, developers, and web site. Chapters 4 and 5 go into more detail about using Maven to publish a web site and to work with an existing source code repository.