How to add a 3rd party jar

This short document answers the question “So, how do I let everyone have a copy of a jar that my code depends on?”.

Reference:

Before You Start

Please check the jar you are looking for may already be in a repository out there on the big bad internet:

Review a couple of the repository search websites:

  1. If you get a hit - confirm it is the jar you want:

  2. Navigate to the correct version and cut and paste the dependency information from the website into your modules pom.xml:

    <dependency>
  <groupId>net.java.dev.swing-layout</groupId>
  <artifactId>swing-layout</artifactId>
  <version>1.0.2</version>
</dependency>

  3. Navigate to the root pom.xml for the project and go to the dependency management section.

    Cut and past paste the dependency information here as well:

    <dependency>
  <groupId>net.java.dev.swing-layout</groupId>
  <artifactId>swing-layout</artifactId>
  <version>1.0.2</version>
</dependency>

  1. You can then adjust your pom.xml to not include the version number (as it will be retrieved from the dependency management section).:

    <dependency>
  <groupId>net.java.dev.swing-layout</groupId>
  <artifactId>swing-layout</artifactId>
  <!-- version retrieved from parent -->
</dependency>

It really is not available - how to upload?

Assuming the jar you want is not already hosted on one of these sites you need to upload it and add a dependency entry to your pom.xml file.

The GeoTools project has access to two repositories for distributing content:

  <distributionManagement>
    <repository>
      <uniqueVersion>false</uniqueVersion>
      <id>nexus</id>
      <name>OSGeo Release Repository</name>
      <url>https://repo.osgeo.org/repository/geotools-releases/</url>
    </repository>
    <snapshotRepository>
      <uniqueVersion>false</uniqueVersion>
      <id>nexus</id>
      <name>OSGeo Snapshot Repository</name>
      <url>https://repo.osgeo.org/repository/geotools-snapshots/</url>
    </snapshotRepository>
  </distributionManagement>

Uploading a jar file is not enough. A clean repository also needs the associated jar.md5, jar.sha1, pom, pom.md5, pom.sha1 files to be uploaded or generated, and needs the various maven-metadata.xml files to be updated (as well as their associated md5 and sha1 files).

This is very tedious, so don’t do that by hand! Maven will do this automatically for you.

Deploying to Open Source Geospatial Foundation Nexus Repository:

  1. This is the GeoTools repository used for stable releases; as such it is the best place to host extra 3rd party dependencies. Use your OSGeo ID login credentials:

  2. Create or update your ~/.m2/settings.xml file as below (~ is your home directory):

    <?xml version="1.0" encoding="ISO-8859-1"?>
<settings>
  <servers>
    <server>
      <id>osgeo</id>
      <username>your osgeo user id</username>
      <password>your osgeo password</password>
    </server>
  </servers>
</settings>

  3. Now you can deploy your jar:

    mvn deploy:deploy-file -DgroupId=<group-id>         \
                       -DartifactId=<artifact-id>   \
                       -Dversion=<version>          \
                       -Dfile=<path-to-file>        \
                       -Dpackaging=jar              \
                       -DrepositoryId=osgeo         \
                       -Durl=https://repo.osgeo.org/repository/geotools-releases/

  4. Or if you have a pom file:

    mvn deploy:deploy-file -DpomFile=<path-to-pom>      \
                       -Dfile=<path-to-file>        \
                       -DrepositoryId=osgeo         \
                       -Durl=https://repo.osgeo.org/repository/geotools-releases/

  5. Elements in bracket (<foo>) need to be replaced by their actual values.

Examples of deploy-file to upload JTS JAR

  1. Change into one of the GeoTools directories (the geotools pom.xml has all the repository definitions so changing directories is easier than editing your settings.xml):

    C:\> cd java\geotools

  2. Here is an example of how to deploy the JTS binary jar:

    C:\java\geotools>mvn deploy:deploy-file -DgroupId=org.locationtech -DartifactId=jts-core -Dversion=1.13 -Dfile=C:\java\jts\lib\jts-1.13.jar -Dpackaging=jar -DrepositoryId=osgeo -Durl=https://repo.osgeo.org/repository/geotools-releases/

  3. And the source code (you will need to zip this up first since JTS does not provide a source download):

    C:\java\geotools>mvn deploy:deploy-file -DgroupId=org.locationtech -DartifactId=jts -Dversion=1.13 -Dfile=C:\java\jts\jts-1.13-src.zip -Dpackaging=java-source -DrepositoryId=osgeo -Durl=https://repo.osgeo.org/repository/geotools-releases/ -DgeneratePom=false

Alternative uploading to Nexus Repository

Uploading to Open Source Geospatial Foundation Nexus Repository:

  1. Login (using your OSGeo User id) to https://repo.osgeo.org/

  2. Visit the upload page, and select geotools-releases from the list.

    If this is not shown you do not have permission, please ask on the developer list.

  3. Upload your third-party jar browsing for the jar to upload, and providing a classifier and extension if required.

    Be sure to:

    • Use Add another assest button to include a src or javadoc zip at the same time using approprite classifier.

    • Either upload a pom.xml as one of the assets, or fill in the component coordinates: groupId, artifactId, and Version.