Setting Up, Configuring, and Using Maven

The Java-based Shibboleth products use Maven in order to build, package, deploy and report on projects. This document will explain how to configure and use Maven within our projects. Note, this is not a general guide to Maven. For such information you need to refer to the Maven website.

Installation

1. Download and expand the latest Maven v3 package

2. Add the bin directory, found in the apache-maven-3.x.x directory, to your path

Configuration

Developers must create a user settings file ~/.m2/settings.xml as follows.

Committers who sign and deploy releases must fill in deployment username/credentials as well as GPG key name.

See https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/1122731397 for more information on deploying sites.

Note, Maven does provide a way to obfuscate the passwords in this file by encrypting them with a passphrase. However that passphrase can only be read from a file. Therefore, instead of using such a mechanism we just recommend protecting your settings.xml file with whatever mechanism you'd protect the passphrase file.

See https://maven.apache.org/guides/mini/guide-encryption.html and https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/2891317253

Building Projects

Building projects is fairly simple. For a monolithic project, change to the project directory. For a multi-module project change to the *-parent directory in the project directory. Then execute:

As projects are undergoing development there are times when unit tests don't pass. You can skip the execution of the tests by running the command:

Supressing the maven repository checks

As a bulwark against by default all projects run a signature check on all non-source, non-test, non snapshot jars in your maven repository during the install phase. Developers will usually have files that the build system does not know how to signature check (the eclipse IDE brings down a large number of uncheckable artifacts). You can avoid getting a fail in two wasy

Build into a separate repository

Set the maven.repo.local property to the name of the alternate repository

Supress the check

Set the no-check-m2 property

Uploading Third-Party Artifacts

As dependencies change, new versions of existing artifacts or new dependencies outright must be uploaded to the Nexus third-party repository for use by the product builds. This is done using the deploy:deploy-file goal after downloading and verifying the artifact out of band.

Assuming your settings.xml file is in place as above, the following example shows how an authorized developer can upload a new artifact. In the event that the artifact has no dependencies in its own right, the following command line options are needed:

• -Durl=https://build.shibboleth.net/nexus/content/repositories/thirdparty

• -DrepositoryId=release

• -Dpackaging=jar

• -Dversion=ver

• -DgroupId=group

• -DartifactId=artifact

• -Dfile=filename

The first three are fixed values based on use of the "thirdparty" repository and a settings file as above. If you use a different server ID to manage your credentials, use that ID in the repositoryId option.

The last four parameters are based on the artifact being uploaded. The groupId and artifactId will depend on how the artifact would be referenced in subsequent POM files.

Example for xercesImpl.jar

Our convention is to make sure the jar name always contains the version of the artifact.

If the artifact itself has dependencies, then a local pom.xml file must be created to document the artifact and its dependencies.

The following example deploys ldaptive with sources, javadoc, and signatures. The Nexus web interface is an alternative when uploading artifact bundles.

Example : deploying ldaptive