Integrating Maven with a Project

Now that you have Maven installed on your system, this section will show you how to integrate it with an existing project. All of the current Turbine projects have been Maven-enabled, and can be used as references. They will be used as examples in this section. There is really only one step to integration Maven with a project: the creation of the project descriptor. You may also create an ancillar maven.xml file which contains project specific goals, preGoals, and postGoals.

Creating a Project Descriptor

Everything in Maven gravitates around the definition of a project. The unit of work in Maven is the project, so before you can get started with Maven you need to create your project definition. The easiest way to do this is to create an XML representation of this definition. In Maven-terms, this is called the project descriptor.

You'll need to create a project descriptor to use Maven with your project. The project descriptor must be called project.xml and must reside in the top-level directory of your project's directory hierarchy. The contents of the descriptor are described in detail in the Project Descriptor document. A sample project descriptor is included below for reference. In addition, all of the Turbine projects have valid project descriptors that you can examine.

We are working on a tool that will help you create your project descriptor automatically, but if you want to get started right away with Maven, then you'll have to create your own project.xml file manually (probably easiest to just modify an existing one such as the one below). The following is the project descriptor used to describe the Maven project: 

<?xml version="1.0"?>
<project>
  <pomVersion>3</pomVersion>
  <name>jakarta-turbine-maven</name>
  <id>maven</id>
  <currentVersion>1.0-b4-dev</currentVersion>
  <organization>
    <name>Apache Software Foundation</name>
    <url>http://jakarta.apache.org/</url>
  </organization>
  <inceptionYear>2001</inceptionYear>
  <package>org.apache.maven</package>

  <shortDescription>Java Project Management Tools</shortDescription>

  <!-- Gump integration -->
  <gumpRepositoryId>jakarta</gumpRepositoryId>

  <description>
    Maven is a project management and project comprehension
    tool. Maven is based on the concept of a project object
    model: builds, documentation creation, site publication,
    and distribution publication are all controlled from the
    project object model. Maven also provides tools to
    create source metrics, change logs based directly on
    source repository, and source cross-references.
  </description>

  <url>http://jakarta.apache.org/turbine/maven/</url>
  <issueTrackingUrl>
    http://nagoya.apache.org/scarab/servlet/scarab/
  </issueTrackingUrl>
  <siteAddress>jakarta.apache.org</siteAddress>
  <siteDirectory>
    /www/jakarta.apache.org/turbine/maven/
  </siteDirectory>
  <distributionDirectory>
    /www/jakarta.apache.org/builds/jakarta-turbine-maven/
  </distributionDirectory>

  <repository>
    <connection>
      scm:cvs:pserver:anoncvs@cvs.apache.org:/home/cvspublic:jakarta-turbine-maven
    </connection>
    <url>
      http://cvs.apache.org/viewcvs/jakarta-turbine-maven/
    </url>
  </repository>

  <versions>
    <version>
      <id>b3</id>
      <name>1.0-b3</name>
      <tag>MAVEN_1_0_B3</tag>
    </version>
    <version>
      <id>b4</id>
      <name>1.0-b4</name>
      <tag>HEAD</tag>
    </version>
  </versions>

  <mailingLists>
    <mailingList>
      <name>Maven User List</name>
      <subscribe>
        turbine-maven-user-subscribe@jakarta.apache.org
      </subscribe>
      <unsubscribe>
        turbine-maven-user-unsubscribe@jakarta.apache.org
      </unsubscribe>
      <archive>
        http://www.mail-archive.com/turbine-maven-user@jakarta.apache.org/
      </archive>
    </mailingList>
    <mailingList>
      <name>Maven Developer List</name>
      <subscribe>
        turbine-maven-dev-subscribe@jakarta.apache.org
      </subscribe>
      <unsubscribe>
        turbine-maven-dev-unsubscribe@jakarta.apache.org
      </unsubscribe>
      <archive>
        http://www.mail-archive.com/turbine-maven-dev@jakarta.apache.org/
      </archive>
    </mailingList>
  </mailingLists>

  <developers>

    <developer>
      <name>Juancarlo Anez</name>
      <id>juanco</id>
      <email>juanco@apache.org</email>
      <organization></organization>
    </developer>

    <developer>
      <name>Stephane Bailliez</name>
      <id>sbailliez</id>
      <email>sbailliez@apache.org</email>
      <organization></organization>
    </developer>
    
    .
    .
    .

    <developer>
      <name>Glenn McAllister</name>
      <id>glennm</id>
      <email>glenn@somanetworks.com</email>
      <organization>SOMA Networks, Inc.</organization>
    </developer>

  </developers>

  <dependencies>

    <dependency>
      <id>dom4j</id>
      <version>1.3</version>
      <url>http://www.dom4j.org/</url>
    </dependency>

    <dependency>
      <id>bcel</id>
      <version>5.0</version>
      <url>http://jakarta.apache.org/bcel/</url>
    </dependency>

    .
    .
    .

    <dependency>
      <id>regexp</id>
      <version>1.2</version>
      <url>http://jakarta.apache.org/regexp/</url>
    </dependency>
    
  </dependencies>

  <build>

    <nagEmailAddress>
      turbine-maven-dev@jakarta.apache.org
    </nagEmailAddress>

    <sourceDirectory>src/java</sourceDirectory>

    <unitTestSourceDirectory>src/test</unitTestSourceDirectory>
    <integrationUnitTestSourceDirectory/>

    <aspectSourceDirectory/>

    <!-- Unit test cases -->
    <unitTest>
      <includes>
        <include>**/*Test.java</include>
      </includes>
      <excludes>
        <exclude>**/RepositoryTest.java</exclude>
      </excludes>
    </unitTest>
              
    <!-- J A R  R E S O U R C E S -->
    <!-- Resources that are packaged up inside the JAR file -->
    <resources>
      <includes>
        <include>*.xsd</include>
        <include>log4j.properties</include>
      </includes>
    </resources>

    <!-- Integration unit test cases -->
    <integrationUnitTest/>

    <jars>
    </jars>
  </build>
</project>

Using Maven with your existing build

Maven doesn't require the use of any Ant build files so you can try to using Maven without affecting the way you traditionally build your project.

Extending Maven's build system

There are two main ways you can extend Maven's build system: creating new plug-ins, and adding additional processing in a project specific maven.xml file.