The first step is to create the project itself. The Maven website should be used as the main reference for this step, but we cover here the essential parts of that step. Firstly, to start a project you need to establish a file structure to use. Maven allows you to configure this to your own tastes. In our example we create a file structure as follows

project.xml
project.properties
maven.xml
log4j.properties
src/java/... (source code)
src/test/... (unit tests)
xdocs/... (documentation)

As you see we have our source code in a single tree under src/java. Since, in our example, we adopt the practice of Test Driven Development (TDD) we also have a source tree for our unit tests (using JUnit) in src/test. We provide our documentation in a directory xdocs. In addition there are several files at the top level to control the operation of the project.

This file provides the overall definition of our project. Here we present our file for this example

<?xml version="1.0"?>
<project>
    <pomVersion>3</pomVersion>
    <name>JPOX-Maven</name>
    <id>jpox-samples-maven</id>
    <currentVersion>1.1</currentVersion>
    <inceptionYear>2004</inceptionYear>
    <package>org.jpox.samples.maven</package>
    <shortDescription>JPOX Samples : Maven</shortDescription>
    <description>Demonstration of a Maven controlled project with JPOX</description>
    <siteAddress>www.jpox.org</siteAddress>

    <!-- Developers/Contributors for this project -->
    <developers>
        <developer>
            <name>Andy Jefferson</name>
            <roles>
                <role>Developer</role>
            </roles>
        </developer>
    </developers>

    <!-- Software Dependencies -->
    <dependencies>
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.8</version>
            <url>http://jakarta.apache.org/log4j/</url>
        </dependency>

        <dependency>
            <groupId>javax.jdo</groupId>
            <artifactId>jdo2-api</artifactId>
            <version>2.1-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>mysql-connector-java</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>3.1.12</version>
        </dependency>
    </dependencies>

    <!-- Build process -->
    <build>
        <sourceDirectory>src/java</sourceDirectory>
        <unitTestSourceDirectory>src/test</unitTestSourceDirectory>
    </build>
</project>

So you see that in the header we have defined our project's package naming and the current version. We then define the developers for the project. There follows a crucial part which defines the software dependencies of our project. Finally we define where our source and test code is stored. This has the effect of allowing Maven to find things when it runs its numerous plugins and means that the tasks of creating JAR's, WAR's , and EAR's is trivial.

This file allows control of the Maven plugins operation for this project. We will add things to this file later.

This file is used if we want to automate the calling of particular things when developing our system. This will be updated later.

The vast majority of software has dependencies. Any project that uses JPOX will require the JPOX JAR(s) to operate and so JPOX is a dependency of that project. Many projects adopt a policy of having a lib directory at the top level and putting all JAR's in that directory. This usually leads to the developer having multiple copies of the same JAR on their machine. Maven provides the idea of a centralised repository where these JAR's are stored. When Maven comes across a dependency it will first look in its repository for the JAR. If it doesn't find the JAR in the repository it can search for the JAR in a remote repository. The user can control where Maven searches for this repository. By default it will look at IBiblio. The location of these repositories can be defined by a file build.properties in the users home directory, and you specify the locations like this

maven.repo.local=/usr/local/maven-repository
maven.repo.remote=http://www.ibiblio.org/maven/

JPOX's website provides a list of dependencies that are required for using JPOX in your system. Maven will take care of dependencies like BCEL and Log4J. Some dependencies will however need to be downloaded from SUN's website (things like JTA, JAAS if you are using the parts of JPOX that requires these). You then need to manually copy these into your Maven Repository. For example, if you have your Maven repository at /usr/local/maven-repository and you want to put transaction-api-1.1.jar into the repo, you would create directories and copy the file so it looks like this

/usr/local/maven-repository/
/usr/local/maven-repository/javax.transaction/
/usr/local/maven-repository/javax.transaction/jars/
/usr/local/maven-repository/javax.transaction/jars/transaction-api-1.1.jar

Clearly you have to write your system at some point in the process, and we don't tell you how to do that here ;-). The only thing you need to do is place your Java files under the source directory src/java, and your unit tests under src/test. Whilst writing your classes, it is advised that you structure your project in such a way that the model/domain classes are in their own area. This means that you can easily separate your data persistence layer from your business logic, or web tier, or whatever. When you identify which classes are to be persisted, you write the JDO MetaData file(s) for these classes, and put it in the same directory.

As mentioned earlier, Maven builds your project using the locations that are defined in the project.xml and using its plugins. To build a JAR of your system you simply type

maven jar

How simple was that ? This has generated the class files under target/classes and has created the JAR file under target. Similarly to clean out the previous class files you do

maven clean

To clean and then build you would do

maven clean jar

To just compile the classes

maven java:compile

To run the unit tests you would do

maven test

Each of these 'clean', 'jar', 'test' are known as goals. Each plugin provides many goals.

As shown earlier we have defined JPOX as a dependency of our project. This means that it will include the JPOX JAR in the CLASSPATH when it compiles, and runs the unit tests, etc. JPOX provides its own Maven plugin to provide enhancement and generation of the schema. You should install this plugin into your $MAVEN_HOME/plugins directory.

The next thing that you will require is the Apache JDO JAR. This can be obtained from the JPOX Download page. When you have this JAR you need to install it manually into your Maven repository.

The final thing is to download the JPOX Maven plugin. This can be downloaded from the same page as the previous download. You then install this into your Maven installation. By this I mean, install it under $MAVEN_HOME/plugins/. You are now ready to go

Once you have a set of compiled Java classes in target/classes you can enhance them for use with JPOX. The first thing we do here is to define some plugin properties in our project.properties. Here we add the lines

maven.jpox.jdo.fileset.dir=${basedir}/src/java
maven.jpox.log4j.configuration=file:${basedir}/log4j.properties
maven.jpox.verbose=true

These settings will use our log4j.properties file for log definitions and will use verbose mode for output. So let's enhance our classes.

maven jpox:enhance

Can't get much simpler than that.

Let's assume that we are creating our own database schema and we want to use SchemaTool. We can do this also using Maven. Lets add some more properties to the project.properties

maven.jpox.database.driver=com.mysql.jdbc.Driver
maven.jpox.database.url=jdbc:mysql://localhost/jpox
maven.jpox.database.user=mysql
maven.jpox.database.password=

Change these settings to match your preferred RDBMS and database location. In this example above we are going to create the schema in a MySQL database called "jpox" running on our local machine. So that only leaves us to create the schema, which we do as follows

maven jpox:schema-create

This creates our tables and we're ready to run our system!.

As you saw above we can enhance our classes very easily. We can however make this automatic after we do any compilation. To do this we need to add something to the file maven.xml

<project xmlns:maven="jelly:maven" xmlns:ant="jelly:ant"
    xmlns:j="jelly:core" xmlns:u="jelly:util">

    <!-- Perform enhance directly after compilation -->
    <postGoal name="java:compile">
        <copy todir="${basedir}/target/classes">
            <fileset dir="${basedir}/src/java">
                <include name="**/*.jdo"/>
            </fileset>
        </copy>
        <attainGoal name="jpox:enhance"/>
    </postGoal>

</project>

This code above will mean that after performing the java:compile goal (a compilation), Maven will copy the JDO MetaData files across into the target/classes area and will then run the jpox:enhance goal

Here you've seen how easy it is to integrate JPOX into the Maven build system. If you have any questions about Maven, then please ask them on the Maven site. Any questions about the Maven JPOX plugin should be asked on the JPOX Forum

If you want to get the latest JPOX, we have our own Maven repository containing the latest and greatest JPOX builds. These can be accessed by specifying a Maven repository of "http://www.jpox.org/downloads/maven/"