Maven 1 Frequently Asked Questions (FAQ)

Document Scope

This document relates to Maven's use in AstroGrid and is not a general purpose Maven tutorial. For such a tutorial and for any other questions not answered here, please refer to the Maven web site. This FAQ relates to Maven 1.

Introducing Maven

What is Maven?

Answer:

• A software build system.
• Built on top of Ant.
• Used in most Jakarta projects.
• Producer of project reports/documentation.
• Scriptable and extensible.

---

How Does it Work?

Answer

Maven accepts a project descriptor file which is declarative instead of task-oriented. The author provides information about the project instead of specifying exactly what tasks are to be done (as you must in Ant). Maven uses this file to get any information it may need to execute the goals that you request. Goals are similar to Ant targets.

 

Another significant feature of Maven is the repository for third-party libraries. Discouraging the practise of placing these libraries in CVS, Maven instead uses a single location under $MAVEN_HOME/repository and places all third-party libraries here using a special directory structure. The developer can then give Maven (via a properties file) a list of remote repository locations. Any library dependencies Maven requires during compilation are automatically downloaded and stored locally.

Advantages:

• One copy of library stored on local machine.
• CVS does not get cluttered with binary files that have no version control requirements.

---

What Can it Do?

Answer:

• Compile Java.
• Run tests.
• Produce project documentation web site.
• Deploy that web site.
• Package and deploy WAR/JAR etc. via SSH.
• Much, much more ...

---

Why should I use Maven?

Maven captures all the knowledge required to build your project - a well maintained Maven project.xml file, will help developers get started quicker, and ease cooperation between workgroups: e.g. no more hunting around for libs & apps needed to exactly reproduce the build environment of previous developers. It removes the assumptions that can be made when you're relying on a nice IDE to do the build for you - especially when astrogrid has not standardised on a particular IDE.

---

What Reports Does it Produce?

Answer:

• CVS Change Log
• File Activity
• Developer Activity
• Code Metrics
• Source Duplication
• Unit Test Coverage
• Much, much, more ...

---

What Are The Issues With Maven?

Answer:

• Maven is beta software.
  • Currently Beta 10.
• No scheduler for automated builds.
  • Cron job required.
• Still under active development.
  • No stability problems found.

---

Can I See A Sample Maven Project?

Answer

There are many examples. Maven is self-building and is (by Open Source standards) well documented. The Maven web site is produced using Maven. See the Maven web site.

 

Other examples can be found from the Maven site here.

---

Is There Documentation?

Answer

The Maven web site documents the basics. The mailing list is pretty good for answers to more involved questions. Archive at http://www.mail-archive.com/users@maven.apache.org/index.html . Then there's the documentation for each maven plugin too.

---

Is There an Official FAQ?

Answer

Yes ... look Official FAQ. There's also an [[http://wiki.codehaus.org/maven/FrequentlyAskedQuestions][Unofficial FAQ] , on the user-group wiki of other information. As with all Wikis, your milage may vary...

---

Using Maven

What are the main goals to call?

All commands should be run from the directory containing your project.xml To see the huge list of goals available, type % maven -g

Some popular goals are:

• % maven clean -- remove products from previous builds.
• % maven java:compile -- compile all code
• % maven jar -- compile code, run unit tests, produce a snapshot jar of compiled classes & resources.
• % maven site -- generate the project site - compiles code, tests, makes snapshots, generates documentation & run analyses.

How can I integrate Maven with my favourite IDE?

Maven provides goals that will generate project configuration files for a range of editors. For instance running % maven eclipse will create a project in Support.Eclipse with the classpath setup correctly, etc.

I don't want to install Maven. What can I do to build?

Why ever not?

Oh well, get someone else to run % maven ant. This generates an ant build.xml in the project directory that contains the basic tasks - compile, clean, jar, test - based on the settings in the maven project.xml file. It will also take care of setting up the classpath, and will download dependency libraries as needed.

This is not perfect however - custom tasks specified in the maven build do not get added to the ant build script.

Configuring Maven

How can I change what happens during a Maven build?

In the grid group we have some very useful ant build files with multiple tasks for invoking various globus tools, auto-generating code stubs etc etc.

How I can tell maven to build the source using (eg) the "ant build" task (with all our specialised subtasks), rather than the standard maven build (which just tries to compile a limited subset of the source?). -- KonaAndrews

Answer:

You need a maven.xml file, as well as the project.xml file. The maven.xml is where you can specify new goals, and where you can add tasks to existing goals. It has similar syntax to an ant build.xml file - infact in here you can use standard ant tags. This file is described (all too briefly ) here: http://maven.apache.org/reference/user-guide.html#maven.xml

the main different is that while ant has 'target' tags, maven has 'goal' tags, which are used to specify new goals. Even better, it has 'preGoal' and 'postGoal' tags, which are used to specify extra stuff to run before or after a goal.These tags are documented at http://wiki.codehaus.org/maven/WerkzTagDocumentation?action=highlight&value=preGoal

---

How do I access the Maven Classpath from my own goals?

Maven constructs a classpath based on the dependencies declared in project.xml. This classpath is available as a reference called 'maven.dependency.classpath'.

Note that as this is a reference, not a property, you refer to it by name, without dereferencing it via ${..}. Furthermore, to pass it to a call to <ant> or <antcall> ant tasks, the inheritRefs="true" should be set.

How do I generate classes from WSDL as part of the build?

Here's what you need to put in your maven.xml file:

 <?xml version="1.0" ?>
 <project xmlns:j="jelly:core"  xmlns:maven="jelly:maven"  default="jar:jar">

This is the header - similar to the start of an ant script, but need to set up xml namespaces here for the different tag libraries you're using. - these two seem to be pretty standard. The default attribute gives the default goal to attain.

  <preGoal name="java:compile"><!-- generate classes from schema first -->
     <mkdir dir="${basedir}/generated/java" />
     <path id="generated.src" location="${basedir}/generated/java"/> 
     <maven:addPath id="maven.compile.src.set" refid="generated.src"/>  <!-- declares new src tree to maven -->
     <attainGoal name="generate-delegate" />
  </preGoal>

this adds a hook to the start of the java:compile goal. The tags without namespaces are standard ant tags. It makes a new directory for generated code, adds this directory to the maven compile set (set of directories to build up), and then instructs maven to attain the goal 'generate-delegate' before starting the 'java:compile' goal.

 
  <preGoal name="clean"> <!-- delete generated classes too-->
       <delete dir="${basedir}/generated/java" />
 </preGoal>

here's another hook - it makes sure the generated code gets cleaned up whenever the 'clean' goal is run

  <goal name="generate-delegate" description="generate client classes from wsdl">
       <taskdef resource="axis-tasks.properties"  classpathref="maven.dependency.classpath" /> <!-- let ant know about this new task -->
       <axis-wsdl2java
               output="${basedir}/generated/java"
               verbose="true"
               noimports="true"
               url="wsdl/AxisDataServer.wsdl">
               <mapping
                       namespace="http://localhost:8080/axis/services/AxisDataServer"
                       package="org.astrogrid.datacenter.delegate.axisdataserver" />
       </axis-wsdl2java>
  </goal>

This is the definition of the goal that generates classes from the wsdl file for the DataCenter workgroup. (obviously you'd change this for your own needs). Axis provides a predefined ant-task to do the generation (ant-wsdl2java). However, as usual with ant, before we can call this external task, it has to be defined.

This task is implemented by classes in the axis-ant.jar. So if you add this to the project dependency list in project.xml, then you can be sure the jar will always be available, and present on the 'maven.dependency.classpath' The rest of this snippet is standard ant code.

Here's how you add the dependency on axis-ant.jar to the project.xml:

   <dependency>
      <groupId>axis</groupId>
      <artifactId>axis-ant</artifactId>
      <version>1.1</version>
   </dependency>

---

Some question or other about properties

Properties for use in maven.xml can be set in number of different places

• project.properties file in the project directory
• build.properties file in the project directory
• build.properties file in the user's home directory.

The order of precendence for these files is described here, while the list of predefined properties is documented here

---

What libraries are available in the Maven Central Repository?

Astrogrid is running off of two repositories at the moment. The standard Maven repository has a browable list of whats available at http://www.ibiblio.org/maven . Astrogrid also has its own repository of lesser-known libraries (think VOTable stuff). This is served from http://www.astrogrid.org/maven/ , but is not browsable. (could this be fixed?)

---

How can I build multiple projects at once?

I have a toplevel directory called ogsa, quite empty except for a subproject directory called ag-ogsa-echo (a complete, standalone sub-project with maven config files, etc).

Would you know what to put in the ogsa directory to tell maven to pass any build goals (maven java:compile, maven jar etc) down to the sub-project directory and run them there?

The ultimate goal here might be a series of standalone sub-projects, with maven config in the parent directory just to build all the subprojects. -- KonaAndrews

I think what you need is the 'multiproject' maven plugin. It's documented at http://maven.apache.org/reference/plugins/multiproject/index.html

I've not used this, but it looks pretty straightforwards. For building on the astrogrid maven site, you'll need to add a hook to get it to run the multiproject goals as part of the build . something like

 <preGoal name="site">
   <attainGoal name="multiproject:site" />
 </preGoal>

---

-- PeterShillan - 23 Jul 2003

-- NoelWinstanley - 29/09/03

Can I find out the jar versions selected in the project.xml ?

If I have this in my project.xml

  <dependency>
    <groupId>castor</groupId>
    <artifactId>castor</artifactId>
    <version>0.9.5</version>
    <type>jar</type>
    <url>http://www.castor.org/</url>
  </dependency>

Can I get at the jar versions as a property in the build script ? Reason is I want to do something like this ....

  <copy verbose="true" todir="${axis.webapp}/WEB-INF/lib">
    <fileset dir="${jar.cache.local}/castor/jars">
       <include name="castor-${castor.version}.jar"/>
       <include name="castor-${castor.version}-xml.jar"/>
    </fileset>
    ....
  </copy>

I need be specific about the versions because the local maven repository is shared between all projects, so it may contain different versions of the castor jars.

Note, I don't want to transfer all of the jars listed in the project.xml depends.

-- DaveMorris - 12 Nov 2003

Ok, solved it - UsefulMavenNotes#Access_to_individual_dependencie

-- DaveMorris - 13 Nov 2003

Generating Documentation with Maven

-- NoelWinstanley - 15 Mar 2004

Produce better documentation with maven.

Improving Javadoc

Command to run javadoc by itself (its also run as part of the 'site' command')

maven javadoc

http://maven.apache.org/reference/plugins/javadoc/properties.html contains a list of the properties you can set to tweak the javadoc.

Read http://java.sun.com/j2se/javadoc/writingdoccomments/

Package.html

Each package can contain a text file called 'package.html'. These are included automatically in the javadoc summary page for each package.

Overview.html

Similarly, you can specify a top-level overview file, to be included in the topmost javadoc summary page. This is by convention called 'overview.html', and lives in the root package of your package hierarchy. To tell maven about it, set the property maven.javadoc.overview to the location of the overview.html file.

doc-files

Each package can contain a subdirectory called doc-files. Any resources placed in this directory (e.g. images, xml documents, schema, togetherJ models, PDF specs) will be copied across to the javadoc output. Javadoc comments can include normal HTML <a href="doc-files/.."> tags to link to these resources.

Partition your packages

Javadoc allows related packages to be gathered together into logical 'groups'. Groups of packages appear under a common subheading in the javadoc overview documentation. This makes it easier for a reader to find the public interface without getting bogged down in implementation details, for example.

To make javadoc organize packages into groups, edit your project.xml, and add a <packageGroups> declaration (between <repository> and <build>). The format is as follows.(example from JES project)

        <packageGroups>
                <packageGroup>
                        <title>Web Service Delegate - Public Interface</title>
                        <packages>org.astrogrid.jes.delegate</packages>
                </packageGroup>
                <packageGroup>
                        <title>Web Service Delegate - Implementation</title>
                        <packages>org.astrogrid.jes.delegate.impl</packages>
                </packageGroup>
                <packageGroup>
                   <title>Service Components Configuration</title>
                   <packages>org.astrogrid.jes.component*</packages>
                </packageGroup>
                <packageGroup>
                        <title>Job Store</title>
                        <packages>org.astrogrid.jes.job:org.astrogrid.jes.impl.workflow</packages>
                </packageGroup>               
                <packageGroup>
                        <title>Scheduler</title>
                        <packages>org.astrogrid.jes.jobscheduler*</packages>
                </packageGroup>
                <packageGroup>
                        <title>Controller and Monitor</title>
                        <packages>org.astrogrid.jes.jobcontroller:org.astrogrid.jes.jobmonitor</packages>
                </packageGroup>
   </packageGroups>

Site Documentation

XDOC

Maven has its own documentation system called xdoc - its a simplified HTML, with some additions (author, navigation). Its based on the xml vocabulary used to generate apache sites.

XDOC is strict XML - ill-formed documents (like most HTML) won't work and break the build. I've found that most html tags pass through unchanged, so you can write simple forms, JSPs, etc in it. Martin's reported that attributes need to be quoted with double quotes - single quotes don't work for some reason.

Some examples of XDOC http://jakarta.apache.org/site/jakarta-site-tags.html

Adding Documents to the site.

Any files in the /xdocs directory with file suffix '.xml' are assumed to be XDOC files, and are transformed into HTML as part of the site generation goal.

Any other files in the /xdocs subdirectory of a maven build are copied across to the generated site - so you can include PDF, images, etc in this directory, and link to them from your xdocs using normal <a href=".."> tags.

Front Page

If the xdocs directory contains a file index.xml then this will form the front page of the generated site. Otherwise a default front page is constructed from the contents of the project.xml - in particular the <description> tag.

Menu

The top level menu, which ties a maven site together, is defined in the file /xdocs/navigation.xml. This is XDOC too. http://maven.apache.org/reference/plugins/xdoc/faq.html may be of some help here.

Webapp Documentation

Astrogrid is distributing its components as web applications, packaged up as webapps. Maven is handy for generating HTML-formatted documentation. Here's how to get maven to generate the webpages for the webapp.

Separate xdocs directory

You'll probably want different documentation to go in the webapp, compared to the normal generated buildsite. Create a folder called /site-xdocs and put the xdoc pages just destined for the webapp site in here.

New goals in maven.xml

Maven needs to be instructed to build the site-xdocs as part of assembling the war file. Here's what to add to the maven.xml file.

<!-- define a destination for the generated documentation -->
<property name="webapp.docs" location="${basedir}/target/webapp-docs" />

<!-- hook our custom goals into the standard war goal -->
<preGoal name="war:war" >
        <attainGoal name="site-webapp" />
        <copy todir="${maven.build.dir}/${pom.artifactId}" overwrite="yes">
                <fileset dir="${webapp.docs}" />
        </copy>
</preGoal>

<goal name="site-webapp">
        <echo> generating webapp site into ${webapp.docs}" </echo>
        <!-- first merge two doc sets - site xdocs take precendence  -->
        <property name="tmp.docs" location="${basedir}/target/webapp-docs-src" />
        <mkdir dir="${tmp.docs}" />
        <copy todir="${tmp.docs}">
                <fileset dir="${basedir}/site-xdocs" />
        </copy>
        <copy overwrite="false" todir="${tmp.docs}">
                <fileset dir="${basedir}/xdocs" />
        </copy>

        <j:set var="maven.docs.dest" value="${webapp.docs}" />
        <j:set var="maven.docs.src" value="${tmp.docs}" />
        <j:set var="maven.xdoc.poweredby.title" value="Provided by Astrogrid" />
        <j:set var="maven.xdoc.poweredby.url" value="http://www.astrogrid.org" />
        <j:set var="maven.xdoc.poweredby.image" value="http://www.astrogrid.org/images/AGlogo" />
        <mkdir dir="${webapp.docs}" />
        <attainGoal name="site:generate" />
</goal>

This will generate a site documentation set, and copy it into the webapp folder before it is packaged into a war file.

TODO: find out how to run just a few of the site reports, rather than all of them.

Customization

http://maven.apache.org/reference/plugins/xdoc/properties.html gives a list of properties that can be set to customize site generation. To set a property for both site and webapp docs, place it in project.properties. To set a property for just one of the documentation sets, you'll need to set it in code in maven.xml using j:set (as in the above example)