JARs in Maven

---

Why?

Maven intends to be the solution for managing all dependencies, but sometimes this does not work. There are several reasons why a library is not available in any public Maven repository.

• A library must be patched or is outdated.
• A library's licence does not allow that kind of redistribution.
• People who create the library do not use Maven and don't upload current versions.

This Best Practice is based on the structure of the Thin SWE Client API Project (see SVN). The structure presented in the following was designed by Carsten Hollmann and Henning Bredel.

The presented method has the following advantages: It is transparent (it uses Maven rules and regulations), it is easily upgradeable (dependencies that are available online at a later stage can just be removed - the user will not notice a difference), it works seamlessly with the normal maven goals (the user does not have to trigger an installation of the files manually), and more (please add if you have another one!).

While the process might seem cumbersome at first, the steps presented below are only a very detailed description and many details will become very obvious, even more so if you are familiar with Maven.

How?

Using maven-external-dependency-plugin

https://code.google.com/p/maven-external-dependency-plugin/

Adding a local JAR Dependency with a local repository

• Create a directory lib-repository. Here you will create a file based Maven repository including jar and simple POM files.
• Create a file README in that directory with the following content. Also, read the content to understand how everything works :-).

This directory contains dependencies which are not migrated to maven dependency
mechanism yet. It's subdirectoy structure contains a file based Maven repository.

To run a successful maven test/compile/package/... you first have to install the
libs into your local repository (normally located at ~/.m2). Then Maven will find
the libs on its path during upcoming builds. This installation is done
automatically by installing the parent project, which references the file
repository in this directory.

For updates on this procedure take a look at https://wiki.52north.org/bin/view/Documentation/BestPracticeJarsInMaven#Adding_a_JAR_Dependency

• Add the local file repository to the POM of the project. It is treated exactly like remote repositories, i.e. libraries from it will be installed into the local user repository (located at ~/.m2).To do that, add the following text into the <repositories> element.

         <repository>
         <!-- Tentative local repo for libs that are not migrated to Maven dependency 
            mechanism and available in online repositories. -->
         <id>lib-repository</id>
         <name>Local Repository</name>
         <url>file:///${basedir}/lib-repository/</url>
      </repository>

• Add libraries to the repository by repeating the following steps:
  • Create a minimal POM file for each library using the following template and steps.

        <?xml version="1.0" encoding="UTF-8"?>
        <project xmlns="http://maven.apache.org/POM/4.0.0"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> 
            <modelVersion>4.0.0</modelVersion>
            <groupId>[enter groupId here]</groupId>
            <artifactId>[enter artifactId here]</artifactId>
            <packaging>jar</packaging>
            <version>[enter version here]</version>
        </project>

• • • groupId: Normally this roughly resembles the package names, for example if you include a library from a company X with the product/sofware name CoolSoftware, and the root package com.companyX.coolsoftware, then the groupId would be com.companyx.coolsoftware. Note: You can have even more layers here.
    • artifactId: The name of the component, can also be a the last element of the Java package structure: com.companyx.coolsoftware.bestComponentEver would imply an artifactId of bestcomponentever.
    • groupId, artifactId and version identify the library in the POM and should be chosen carefully. For example if you just provide a patched version of an existing library, then re-use the correct groupId and artifactId but change the verision, for example to 1.2.3-patched, to allow the build system to match the library to other versions of the same component and potentially use newer versions once they are available. Here the presented best practice shows its full potential!
  • Create a directory hierarchy that resembles the identification elements (identifiers and version), i.e. /[groupId]/[artifactId]/[version]/, for example /com/companyx/coolsoftware/bestcomponentever/1.2.3-patched.
  • Save the new POM file in that folder as [artifactId]-[version].pom, for example bestcomponentever-1.2.3-patched.pom. Of course you can add a lot more information into the POM file here, like maintainers, contacts, licences. See the POM documentation for details.
• Add the newly created libraries as dependencies to the project POM file within the <dependencies> element.

        <dependency>
           <groupId>com.companyx.coolsoftware</groupId>
           <artifactId>bestcomponentever</artifactId>
           <version>1.2.3-patched</version>
        </dependency>

• Optional: If you use Eclipse and m2e, run "Update Project" from the Maven context menu of the project.
• Run mvn install
• Done.

Adding a native/dll Dependency

To be done.