Creating a Maven project for the common packages

This posting continues the series on moving from an Ant to a Maven build.

When you have replaced all your external libraries with Maven dependencies you can move on to the next stage in moving from Ant to Maven. This stage is to separate out one or more of your Java packages into their own Maven projects. There are a number of good reasons to separate out packages, but the practical one is that Maven is best used to build one deliverable.

Every organization has a "common" package that contains classes adding general purpose functionality. There are likely several "utility" packages that augment the standard Java libraries for IO, networking, text, collections, functions, streams, etc. There are packages for data structures and algorithms that were sufficiently independent of the primary application to be have been separated out from its packages. These common packages are also likely used by supplementary tools to your primary application. If you already build separate jars for your common packages this step is not that much work. If you don't then you are likely to find some unexpected and unwanted entanglements with application code that needs to be worked out.

A note about the version control. Separating out packages does not mean you also have to move from a monorepo if that is what you are currently using. Moving away from a monorepo does simplify assuring that your common packages are isolated from your application code, however. If you have been building separate jars for your common packages then you have already established build mechanisms to maintain the isolation. If you haven't then this is something you will need to do in your monorepo. This tutorial, however, assumes you are not using a monorepo.

The common packages will be your first Maven project. Create an empty Maven project using archetype:generate

mvn archetype:generate \
  -DgroupId=com.andrewgilmartin \
  -DartifactId=system-common \
  -DarchetypeArtifactId=maven-archetype-quickstart \
  -DarchetypeVersion=1.4 \
  -DinteractiveMode=false

Change the "groupId" and "artifactId" appropriately. The command will create the tree

.
└── system-common
    ├── pom.xml
    └── src
        ├── main
        │   └── java
        │       └── com
        │           └── andrewgilmartin
        │               └── App.java
        └── test
            └── java
                └── com
                    └── andrewgilmartin
                        └── AppTest.java

Move your common packages into the src/main/java tree. Move any tests you have for these packages into the src/test/java tree. (Delete AppTest.java from both trees at some point.) Your IDE will likely be very helpful in moving files and even version histories.

A build now will very likely fail due to Java language level and missing dependencies. Edit "pom.xml" and update the "maven.compiler.source" and "maven.compiler.target" properties appropriately, eg for Java 8 use

<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.9</maven.compiler.target>

Try a compile just to see what happens!

mvn package

Lots of missing dependencies! Using the information you gathered before add each dependency under the pom.xml file's <dependencies/> element. For example, if the common package is dependent on Apache's HTTP Client 4 then add

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
    <version>4.5.10</version>
</dependency>

The org.apache.httpcomponents are located at Central and this is most likely already listed in your Maven installation's $HOME/.m2/settings.xml file. If it is not or you would rather not depend on the installation's settings (a good practice) then add the <repository/> element under the <repositories/> element. If the <repositories/> is missing from pom.xml then add it above the <project/> end tag.

<project>
  ...
  <repositories>
    <repository>
      <id>central</id>
      <name>Central Repository</name>
      <url>https://repo1.maven.org/maven2/</url>
    </repository>
  </repositories>
</project>

Continue adding dependencies and building and testing until you get a clean result.

You now have your common packages in their own jar

target/system-common-1.0-SNAPSHOT.jar

After installing this in you local Maven cache, $HOME/.m2/repository/, you can use it in your Ant build.xml. To install it use

mvn install

And you should see the logged output similar to

[INFO] Installing /home/ajg/src/system-common/target/system-common-1.0-SNAPSHOT.jar to /home/ajg/.m2/repository/com/andrewgilmartin/system-common/1.0-SNAPSHOT/system-common-1.0-SNAPSHOT.jar
[INFO] Installing /home/ajg/src/system-common/pom.xml to /home/ajg/.m2/repository/com/andrewgilmartin/system-common/1.0-SNAPSHOT/system-common-1.0-SNAPSHOT.pom

To use the installed jar in your Ant build you need only to add the new dependency, eg

<mvn-dependencies pathId="runtime-dependencies.classpath" ... >
  ...
  <dependency groupId="com.andrewgilmartin" artifactid="system-common" version="1.0-SNAPSHOT"/>
  ...
</mvn-dependencies>

Remove from the system's source tree all the common packages now compiled into system-common-1.0-SNAPSHOT.jar. Also remove all the <dependency/> elements that were only used by the common packages as Maven already knows the jar's dependencies (from its pom.xml file that was also installed into $HOME/.m2/repository).

If you have other common packages, eg enhancements to Swing or extensions to J2EE, then repeat the above procedure for each of them.