Maven Architecture

Maven at its core is based around its plug-in architecture and the POM. This architecture uses the Jelly scripting language (which we examine in the next section) for its goal processing. The POM, as the project descriptor, controls what features your project will use, what libraries it depends on, who is working on the project, project mailing lists, and so forth. All installed plug-ins are stored in your MAVEN_HOME directory. Each plug-in that is deployed is in a named directory, such as maven-java-plugin-1.3, and under that directory are a number of files, such as plugin.jelly, plugin.properties, project.properties, and project.xml. A Maven plug-in is similar to a Maven project.

Each plug-in consists of two items: goals and properties. Goals are items that you as a developer can execute to perform an action on your project. Some example goals are:

• jar:install: Builds your JAR file and places it in your local Maven repository for use among other projects locally.

• war:war: Builds a Web application and packages it into a WAR file for you.

• test:test: Builds and executes your JUnit unit tests, outputting test results as XML and text files for easy perusal.

Every plug-in has executable goals . To see what each goal does, you can either look at the plug-in documentation on the Maven Web site or type maven g (which displays all available goals for installed plug-ins). Most goals are not stand-alone, which means they rely on other goals being executed before them. To better understand this, let's look at one of the core plug-ins and examine its goals:

 Java plugin.jelly file <?xml version="1.0"?> <project    xmlns:j="jelly:core"   xmlns:ant="jelly:ant"   xmlns:define="jelly:define"   xmlns:maven="jelly:maven">   <goal name="java:prepare-filesystem"         description="Create the directory structure needed to compile">     <ant:mkdir dir="${maven.build.dest}"/>   </goal>   <goal name="java:compile"         description="Compile the project"         prereqs="java:prepare-filesystem">   ....   </goal> 

As you can see from this Jelly file, the plug-in is essentially an XML file with custom processing that will be interpreted by the Jelly engine. First we start with a project element, which allows you to create namespace declarations. These declarations are then interpreted by Jelly, and it loads those tag files. For right now, don't worry about these too much; we discuss them in more detail in the "Understanding Jelly" section. Now we need to concentrate on the java:compile goal. As you can see, there is a prereqs attribute that describes what goals need to execute prior to this goal being attained. There is also a description attribute that will display when you type maven g on the command line. Later we use a similar technique when we write our maven.xml file to execute a custom goal of our definition.

Plug-in properties allow you to modify the default behavior or to specify things like additional source directories specific to that plug-in. Most of the plug-ins properties that can be set are documented on the Maven site (if they are distributed with Maven) or in the plug-in's own documentation. If neither of these is available, you can go into the plug-in's directory and view its plugin.properties file. This file should not be modified. Here is an example of one from the CruiseControl plug-in:

 maven.cruisecontrol.config=${basedir}/cruisecontrol.xml maven.cruisecontrol.schedule.interval=300 maven.cruisecontrol.checkout.dir=${basedir}/checkout maven.cruisecontrol.logs.dir=${basedir}/target/cc-logs maven.cruisecontrol.goals=scm:updateclean testsite:deploy maven.cruisecontrol.home=CC_HOME_NOT_SET maven.cruisecontrol.mail.host=localhost maven.cruisecontrol.mail.defaultsuffix=DEFAULT_SUFFIX_NOT_SET maven.cruisecontrol.mail.subjectprefix=[BUILD] 

These are all properties that you can set in your own project.properties file. In fact, a number of these are required to be set, such as the cruisecontrol.home property, to tell the plug-in where you have installed CruiseControl (see chapter 27 for more information about CruiseControl).

Now that we've examined some of the Maven underpinnings, the next step is to look at how Maven works. The easiest way to do this is to run Maven in debug mode by typing maven X jar:jar . This executes the jar command, which first builds your classes, then runs the unit tests and finally jars your project for deployment or distribution, as shown below.

You should see a lot of text flying by as the debug output goes to the console. I'll walk through some of the initial phases of Maven:

1. Sets references : Maven sets up all of its internal references, including the JAR dependency locations, test source, Java source, and whatever other references you have defined specific to your project. These also include project and personal properties files.

2. Downloads dependencies: If there are missing dependencies in the local repository, Maven attempts to download these, according to your maven.repo.remote property (which defaults to ibiblio .org/maven).

3. Updates plug-in dependencies: Maven updates the class path dependencies with internal dependencies required by installed plug-ins.

4. Prepares filesystem: If the target directory has not been created, Maven creates it and populates it with required directories according the plug-in's goals.

5. Scans files: Maven scans for package.html in the source tree to exclude automatically.

6. Builds: It builds the Java source.

7. Unit-tests: It compiles and runs unit tests.

8. Jars: It jars classes for deployment and places them in the target directory.

Maven processes the following properties files in this order:

1. ${project.home}/project.properties

2. ${project.home}/build.properties

3. ${ user .home}/build.properties

So, each project can override Maven properties, and each user can override project and Maven properties.

Maven Properties

There are a number of properties specific to Maven that you can override to provide a custom look and feel for your generated site, to turn on and off XML declarations in HTML headers, and other behavior. Here are some of the properties that you may want to change depending on your needs:

• maven.build.dest: Contains the directory where generated classes go.

• maven.build.src: Specifies the directory where the generated source goes.

• maven.conf.dir: Specifies the directory that holds configuration files.

• maven.docs.dest: Indicates the output directory for the generated HTML from reports .

• maven.docs.omitXmlDeclaration: Specifies whether generated documentation should have an XML declaration, e.g., <?xml version="1.0"?>.

• maven.docs.outputencoding: Indicates the character encoding for generated documentation.

• maven.docs.src: Contains the directory for user-supplied documentation.

• maven.gen.docs: Specifies the directory where generated XDocs that need to be changed to HTML are placed.

• maven.home.local: Indicates the directory on the local machine Maven uses to write user-specific details to, such as expanded plug-ins and cache data.

• maven.mode.online: Indicates whether you are connected to the Internet.

• maven.plugin.dir: Indicates where Maven can find its plug-ins.

• maven.plugin.unpacked.dir: Specifies where Maven expands installed plug-ins for processing.

• maven.repo.central: Specifies the host that Maven will attempt to deploy the distribution to during a dist:deploy.

• maven.repo.central.directory: Specifies the directory that Maven will copy the distribution to during a dist:deploy.

• maven.repo.local: Indicates the repository on the local machine Maven should use to store downloaded artifacts (JARs, etc.).

• maven.repo.remote: Specifies the repository Maven should use to download artifacts (JARs, etc.) that it can't find in the local repository.

• maven.repo.remote.enabled: Indicates whether or not a remote repository should be used.

• maven.scp.executable: Indicates the executable to use for secure copies.

• maven.src.dir: Contains the base directory for the source code.

• maven.ssh.executable: Specifies the executable to use for executing commands remotely.

• maven.proxy.host: Contains the IP or address of your proxy.

• maven.proxy.port: Contains the port number of your proxy.

• maven.proxy.username: Specifies username if your proxy requires authentication.

• maven.proxy.password: Specifies password if your proxy requires authentication.