Maven Primer


The easiest way to get started with Maven is to first download and install the latest version; as of right now that is Maven-1.0-rc1. A final release is expected soon. First go to the Maven Web site and click on the download link at the top. From there you can choose the most appropriate download for your platform (EXE for easy Windows install, zip for Windows DIY install, and Tar-gzip for Unix). Once you've downloaded the file you can either extract the Zip or Tar- gzipped file onto your system or double-click the EXE file for installing. Instructions for installing each of these can be found at http://maven.apache.org/start/install.html. If you wish you can also install Maven from source, but depending on the status of the project this can be a painful process. Instructions for installing from source can be found on the Maven site at http://maven.apache.org/start/bootstrap.html.

Installing on Unix

To install Maven on Unix or a Unix-friendly operating system (OS X, Linux), retrieve the tar.gz file from the download section. Once you have downloaded the tar.gz file (tape archive, gnu zipped ) to your local machine, unpack it using either gnutar or your favorite archive-handling software (OS X comes equipped with StuffIt, which will automatically unzip and untar your downloaded files for you). Once you have unarchived the file, you should be left with a folder called maven-1.0-rc1 (or another name that reflects the version you downloaded). You can place this folder anywhere on your system that you have read and write access to. Note the location for the next step.

At this point you should add an environment variable called MAVEN_HOME to your startup or login shell script. We leave this exercise to since different shells have different methods . In OS X, you do this by adding a setenv command to your .tcshrc file (if you are using tc shell), which looks something like this:

 setenv MAVEN_HOME /Users/me/maven-1.0-rc1 

Then you may also wish to add this to your PATH statement like so:

 setenv PATH ${PATH}:${MAVEN_HOME}/bin 

This line adds the Maven binaries to your executable path for the user that you are logged in as.

Installing on Windows

If you are running Windows 95/98/2000 or XP, then you should download the Windows executable. It essentially does the same thing as the tar.gz file, but the EXE places Maven in your Program Files directory for you, rather than having you choose where to put it. You may also choose to download the zip file; if you go this route, then follow the directions for the Unix installation given earlier.

Adding system environment variables will vary depending on which version of Windows you are running. For Windows 2000 you can add system variables by right-clicking on My Computer and choosing Properties. From there select the Advanced tab and then click the Environment Variables button. Now you have two options: System variables or User variables. For ease of use, I recommend choosing System variables just to make sure that the command-line sees the variable properly (this may vary from version to version). To add the Maven binaries to your PATH statement, double-click on the PATH entry and go to the end of the line. Add the following after typing a semicolon to end the previous PATH statement:

 %MAVEN_HOME%\bin 

Verifying the Install

To verify that you have Maven installed properly, go to a command line, change to your project directory, and type maven g . This command runs Maven and outputs all the goals available to you. You can think of goals as Ant targets, except that these goals are available to all of your projects, not just to some custom-defined target that you created for Ant. You should see something like this:

click to expand

If you experience connection problems, perhaps you aren't actually connected, in which case you want to run Maven in offline mode, or maybe you are connected through a proxy server. The easiest way to run Maven in offline mode is to specify it on the command line using the o modifier, so it would look like maven o . To specify a proxy server, the best thing to do is to specify a build.properties file in your user home directory. In this file, specify the following properties:

  • maven.proxy.host: The IP or address of your proxy.

  • maven.proxy.port: The port number of your proxy.

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

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

What was all that stuff about downloading? Didn't Maven come with everything already? Well, yes and no. What you downloaded was the skeleton of Maven. To keep it small and easy to install, it has been stripped down to exactly what it needs to run. That's not to say that what you downloaded isn't usableit is. But a number of plug-ins are downloaded the first time you run Maven, so it's best if you're connected when you do it. Maven also checks for the latest of a particular internal dependency or plug-in and downloads that the first time it runs.

Now that it has downloaded everything, Maven needs a place to put it. It handles this by default by placing your repository and extracted plug-ins into your user home (on Windows this is Documents and Settings/ username; on OS X and other Unix-like operating systems it is in /etc/home/ username or /Users/ username ) underneath the directory .maven. Calling the directory with a dot (.) in front of it hides it by default in most Unix environments (including OS X) but doesn't do anything in a Windows environment.

Once you have Maven installed and you've verified that it's running, we can now dig into the fun stuff! Maven uses three files to define your project, additional properties, and custom goals. These files are:

  • project.xml: Where you place the project descriptor or Project Object Model (POM).

  • project.properties: Where you can override Maven and plug-in properties.

  • maven.xml: Where you define custom Maven goals using Jelly (which we will discuss later in this chapter).

Installing Plug-ins

If you wish to install other plug-ins not available through the Maven distribution or want to install newer versions of them, there are a few ways to go about it:

  1. Manually download and install.

  2. Install through Maven itself.

  3. Declare the plug-in as a dependency.

Manual Download and Install

To perform a manual install of a plug-in, simply download the plug-in JAR file in question and place it in the MAVEN_HOME/plug-ins directory. Maven should then automatically unjar the file and deploy it to your local .maven/plugins directory. If it does not do this, see the "Gotchas" section.

Installing Through Maven

To install a plug-in through Maven, make sure that the repository that contains the plug-in is specified in your maven.repo.remote project property. If it isn't Maven won't know where to find the plug-in.

 maven plugin:download -DartifactId=cactus-maven -DgroupId=cactus  -Dversion=1.6dev-20040226 

This code tells Maven that we want to download the cactus-maven plug-in, version 1.6dev-20040226, and install it to our local repository.

Declaring the Plug-in as a Dependency

By declaring a plug-in as a dependency, you enable Maven to download and install it into your plug-ins directory as long as it can find the dependency to download. If a plug-in is stored at another repository make sure that repository location is added to your maven.repo.remote property in project.properties; otherwise Maven will not be able to find it.

 <dependency>     <groupId>xdoclet</groupId>     <artifactId>maven-xdoclet-plugin</artifactId>     <type>plugin</type>     <version>1.2b3</version> </dependency> 

As you can see, this is rather straightforward: We are telling Maven that we need the maven-xdoclet-plug-in, version 1.2b3, installed as a plug-in so that we can use it. Once it has downloaded and installed the dependency, we can use this plug-in throughout our code (including other projects as well).

Gotchas

Here are some items to be aware of once you have downloaded and installed the plug-ins:

  • Older versions of the same plug-in: Browse the plug-ins directory and look for previous versions of the downloaded plug-in. These will need to be removed.

  • Cached data: Maven caches data when it runs builds so it doesn't constantly have to read the plug-in goals and properties. These are called .cache files. Remove all of these once old plug-ins have been removed or new ones have been added, if you are having problems.

  • Plug-ins not extracted: If you did a manual install, the plug-in JAR file may not have extracted itself. This will require a manual unjar: jar xvf jarname.jar.

Now let's look at the Project Object Model (POM). First we focus on the elements inside it that are most important to us right now, and then we look at how a Maven project is structured.

The Project Object Model (POM)

The POM is an XML file called project.xml that describes your project to Maven so that it can build the project, run the appropriate tests, and build reports . All of these are core plug-ins for Maven so there is no extra coding or tweaking you need to do; you just supply the appropriate information in the POM for Maven to get ready to go. When you run Maven in a directory that contains a project.xml file, it attempts to use that as the POM, just as Ant looks for a build.xml file in the current directory it is being run in. Here is a sample project.xml file:

 <?xml version="1.0"?> <project>   <pomVersion>3</pomVersion>   <name>XPToolkit Maven Test Project</name>   <id>test</id>   <groupId>xptoolkit</groupId>   <currentVersion>1.0-b1</currentVersion>   <organization>     <name>Wrox</name>     <url>http://wrox.com/</url>   </organization>   <inceptionYear>2004</inceptionYear>   <package>com.wrox.xptoolkit</package>   <shortDescription>Test Project for Java Tools for Extreme Programming 2nd Edition</shortDescription>   <description>     This is a simple test project to highlight the structure of a Maven project for the 'Java Tools for  Extreme Programming' 2nd Edition book published by Wrox in its Professional series.   </description>   <url>http://www.wrox.com/javatools/</url>   <issueTrackingUrl/>   <siteAddress/>   <siteDirectory/>   <distributionSite/>   <distributionDirectory/>   <repository/>   <versions/>   <mailingLists/>   <developers>     <developer>       <name>Rick Hightower</name>       <id>rick</id>       <email>rick@arc-mind.com</email>       <organization>Arc-Mind</organization>     </developer>     <developer>       <name>Warner Onstine</name>       <id>warner</id>       <email>warner@sandcastsoftware.com</email>       <organization>Sandcast Software</organization>     </developer>   </developers>      <contributors/>   <licenses/>   <dependencies>     <dependency>       <groupId>test-dependency</groupId>       <artifactId>test-dependency</artifactId>       <version>1.0</version>       <url>http://www.test.org/</url>     </dependency>   </dependencies>   <build>     <nagEmailAddress/>     <sourceDirectory>src/java</sourceDirectory>     <unitTestSourceDirectory>src/test</unitTestSourceDirectory>     <aspectSourceDirectory/>     <!-- Unit test cases -->     <unitTest>       <includes>         <include>**/*Test.java</include>       </includes>       <excludes>         <exclude>**/ExcludedTest.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>       <resource>         <directory>${basedir}/src/resources/misc</directory>         <includes>           <include>*.xsd</include>         </includes>       </resource>       <resource>         <directory>${basedir}/src/resources/logging</directory>         <includes>           <include>log4j.properties</include>         </includes>       </resource>     </resources>     <jars/>   </build>   <reports/> </project> 

So, what does this all mean? Starting from the top level we have the project element as the root element. Every POM file needs to have this as the root element.

The project Element

Under the project element we have several top-level elements:

  • pomVersion: This is the version of POM we are adhering to. Currently it is at version 3. It should not be necessary to change this once you have set it. When you upgrade your instance of Maven, it will automatically update this reference for you if necessary.

  • groupId: The groupId element is the short, Unix-like version of the group name. Say your company is the one sponsoring this project; then the name could be the company name. Or the name could be the parent project name. This element may change in the near future since it is potentially confusing.

  • id: This is the artifact's ID, or what will be generated from this particular project. When a build is done, the name of the JAR, WAR, or EAR file will be groupId-id-version.jar (.war or .ear).

  • name: This element contains the full version of the project's name.

  • version: This element specifies the current version of this project's artifact, in our case 1.0-b1, which is shorthand for version 1.0 beta release 1. However, you can put whatever you want in here. So our final artifact that will be generated would be xptoolkit-test-1.0-b1.jar (.war or .ear).

  • organization: This element describes what organization this project belongs to. The URL and text information will be used in generating the site generation as well as JavaDoc.

  • inceptionYear: This element specifies when this particular project started. It is also used in site generation and JavaDoc.

  • package: This element contains the main package that this project builds under, used in generating the JavaDoc.

  • shortDescription and description: These elements are used for generating the site's home page (they can be replaced by creating an index.xml file with more information in the xdocs directory, which we cover later).

  • url: This element contains the project page URL used for site generation.

  • issueTrackingUrl: This element specifies the issue tracking URL (for example, the Web site address for your BugZilla, Scarab, or Jira installation for this project).

  • siteAddress/siteDirectory: This element specifies the hostname of the Web server and the directory where you want to deploy the generated Web site.

  • distributionSite/distributionDirectory: This element specifies the hostname of the server and the directory where you want to deploy released distributions. It is very useful if you are using your own repository and need to keep things internal.

  • repository: This element specifies information regarding the type of source code management software you are using for this project (CVS, SourceSafe, SVN, etc.).

  • versions/version: This element provides information on previous versions and their tags so that it is easy to check out and build a previous release.

  • mailingLists/mailingList: This element provides information regarding mailing lists that are devoted to this project. Use this element when generating your Web site.

  • developers/developer: This element lists the developers who have active commit status on the project along with their contact information.

  • contributors/ contributor : This element lists the contributors and their roles in the project.

  • licenses: This element describes all the licenses for this project. Use it when generating the license page of your Web site. These licenses are typically only for this project and not its dependencies.

  • dependencies/dependency: This element contains all the dependencies of the project needed in order to build and/or deploy it.

  • build: This element describes the build environment of the project: source locations, test locations, unit test flags, etc.

  • reports : We examine reports in more detail in the case study later in this chapter.

The dependencies Element

The dependencies and build elements are the biggest part of any Maven POM. The dependencies element describes to Maven what JARs you will need when building and distributing your project. If you have no dependencies for your project, you can simply make this an empty XML element <dependencies/>. Most won't be that fortunate, so let's look at the subelement of dependencies, dependency, and what is required in that element. One of the best things about dependencies is that the majority of them probably already reside on the Maven repository, which has been graciously hosted on Ibiblio (http:// ibiblio .org). If the dependency isn't hosted and the license allows for it to be freely downloaded, then a simple request to the Maven developers will generally get the dependency installed on the repository.

So, how do we describe a dependency so that Maven knows where to get it?

  • artifactId (formerly id): This element contains the unique ID for an artifact produced by the project group.

  • groupId: This element provides unique ID for the group that created this dependency (i.e., jboss for the jBoss group).

  • version: This element specifies the version of the dependency that your project relies on.

  • jar: This element is useful if the dependency doesn't follow the <artifactId>-<version>.jar pattern.

  • type: This element specifies the type of dependency. Allowed values are jar, ejb, and plugin. It is not a required element.

  • url: This element specifies the alternate location for the download if it cannot be found on the Maven repository.

  • properties: This element contains properties about the dependency. Some plug-ins allow you to set their properties in the POM, and you would do so here. One plug-in that does allow this is the WAR plug-in, which we will look at in greater detail when we discuss the case study.

The build Element

The build element is the other critical section of the POM. It contains several elements that describe the build environment to Maven:

  • nagEmailAddress: This element provides an e-mail address where you want to send build status. This element is useful to plug-ins that perform automatic integration builds, such as AntHill, CruiseControl, or Gump.

  • sourceDirectory: This element specifies the directory beneath this one that contains your Java source files. Typically this directory is src/java (we discuss the proposed project layout shortly).

  • sourceModifications: This element is used to look for a particular class, and if that class cannot be loaded, it includes or excludes certain classes from your build and tests.

  • unitTestSourceDirectory: This element specifies the directory beneath this one that contains your standard unit tests. Typically, this directory is src/tests.

  • aspectSourceDirectory: This element specifies the directory containing Aspect sources of the project. The build will compile the Aspects in this directory using the AspectJ plug-in.

  • unitTest: This element specifies which unit tests should be included or excluded from running.

  • resources: This element describes any resources that you need included in the final distribution. The unitTest element also contains a similar element for defining specific resources or files specific to testing.

Project Properties

The project.properties file resides at the same level as the project.xml file. This file allows you to override specific Maven properties and plug-in properties for your project to use. One common property that is typically used is maven.repo.remote, which allows you to specify where your remote repository resides as an HTTP address. When overriding this property, you must separate the repositories with commas. Use the Maven repository first and then any custom repositories afterwards.

The code looks like this:

 maven.repo.remote=http://www.ibiblio.org/maven,http://mywebsite.com/path/to /repo 

Before setting up a custom repository, make sure you understand what structure Maven expects the filesystem to follow in order for it to find any JARs that you have placed there.

maven.xml

This file describes additional goals that you may want to execute before others, such as custom goals or custom Ant tasks that have not been created as plug-ins yet. This file is a Jelly file (which we discuss later in the chapter). A maven.xml file includes several elements, starting with the top-level project element. In this element you define the default goal of your project. Here is a bare-bones maven.xml file that tells Maven to build your project by default whenever you simply type maven in your project directory:

 <project default="java:compile"/> 

Project Layout

Now we're going to take a look at a basic project structure that Maven recommends:

 LICENSE.txt project.properties project.xml maven.xml build.properties src     test     java     announcements (optional) xdocs     navigation.xml 

The basic structure of a Maven project is a very well-defined layout. You can customize the layout to a certain degree by specifying items in the build element in addition to setting custom properties in the project.properties file. The src directory is where all of your source and configuration code will go. Place all of your custom documentation for the project in the xdocs directory. Maven automatically converts this documentation to HTML or PDF format, depending on which Maven goal you execute (either site:generate or pdf:pdf goal). Now let's examine the src directory a bit more.

The src directory typically consists of at least two subdirectories: java and test. The java directory contains all of your base code for the project, and the test directory contains all of your JUnit unit tests. You can also place a conf directory in here for storing things like additional properties files or configuration files that you need copied into your final JAR or testing JAR.

When Maven executes a JAR goal it will always run through the tests in the test directory. You can control what files are executed by modifying the excludes element in the unitTest section of your POM. You can optionally turn off running the tests entirely by adding a maven.test.skip=true or maven.test.failure .ignore=true property in your project.properties file. Neither of these is recommended for obvious reasonsby turning off testing you run the risk of failing code.

Maven generates the following when building distributions, the project Web site, and other documentation:

 target     classes     test-classes     iutest-classes     generated-docs     test-reports     docs         index.html         apidocs         xref         xref-test         mail-lists.html         team-list.html         dependencies.html         changelog.html         file-activity-report.html         developer-activity-report.html         jdepend-report.html         junit-report.html         checkstyle-report.html 

The target directory is where everything that gets built (source, tests, documentation, and reports) end up. Most of these can also be controlled either by setting properties for specific plug-ins or by changing elements in your POM. Maven generates a number of these documentation and report files automatically for you when you run a site:generate or pdf:pdf goal. Most of these files and folders, such as apidocs, xref, mail-lists.html, and dependencies.html, are pulled directly from the POM. Others, such as developer-activity-report.html and junit-report.html, are generated from plug-ins such as changelog and test.

As you can see, there isn't too much to setting up a project to use Maven initially. The real fun comes afterwards when you want to start doing some customization, like separating your project into discrete modules, specifying new reports to run, or adding in Ant tasks that haven't been turned into plug-ins yet. Next we're going to look at the architecture a bit so that you understand how Maven works with those files you've just supplied to it.




Professional Java Tools for Extreme Programming
Professional Java Tools for Extreme Programming: Ant, XDoclet, JUnit, Cactus, and Maven (Programmer to Programmer)
ISBN: 0764556177
EAN: 2147483647
Year: 2003
Pages: 228

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net