Dependency analysis

From time to time it becomes advisable to run an analysis over the pom files to ensure that each sub-projects dependencies are listed and that any needless dependencies are removed.  Maven provides a tool to help with this, but it needs to be treated with circumspection.

1. Ensure that the (entire) project builds cleanly

2. Run dependency analysis from the parent directory using the command 'mvn dependency:analyze'.  The key part of the log will look like this for each subproject:

   mvn dependency:analyze output

   [WARNING] Used undeclared dependencies found:
   [WARNING]    org.opensaml:opensaml-profile-api:jar:3.0-SNAPSHOT:compile
   [WARNING]    com.google.guava:guava:jar:14.0.1:compile
   [WARNING]    joda-time:joda-time:jar:2.2:compile
   [WARNING] Unused declared dependencies found:
   [WARNING]    net.shibboleth.idp:idp-profile-api:jar:3.0-SNAPSHOT:compile
   [WARNING]    org.springframework.webflow:spring-webflow:jar:2.3.2.RELEASE:compile
   [WARNING]    org.glassfish:javax.json:jar:1.0.2:runtime
   [WARNING]    org.codehaus.janino:janino:jar:2.6.1:compile
   [WARNING]    ch.qos.logback:logback-classic:jar:1.0.11:runtime
   [WARNING]    javax.mail:mail:jar:1.4.7:compile
   [WARNING]    org.springframework:spring-context-support:jar:3.2.2.RELEASE:compile
   [WARNING]    javax.servlet:servlet-api:jar:2.5:provided
   [WARNING]    org.springframework:spring-test:jar:3.2.2.RELEASE:test
   [WARNING]    net.shibboleth.utilities:java-support:test-jar:tests:2.0-SNAPSHOT:test
   [WARNING]    org.slf4j:jcl-over-slf4j:jar:1.7.5:runtime
   [WARNING]    org.slf4j:jul-to-slf4j:jar:1.7.5:runtime
   [WARNING]    org.slf4j:log4j-over-slf4j:jar:1.7.5:runtime
   [WARNING]    xmlunit:xmlunit:jar:1.4:test

3. If in doubt, you can normally ignore any "unused declared" dependencies which have either the runtime or test scope when performing a review, as long as everything still works. If you use the command mvn -DignoreNonCompile dependency:analyze, these will be filtered out from the log.
4. Move any commonly "Used undeclared dependency" into the parent pom (in this case this was guava which occurred as missing in more than 50% of the projects).
5. Iterate over each subproject (its is probably easiest to do this in the order in the log file - that is from most dependent to least)
   
   1. Add any missing "Used undeclared dependency"s to the subproject's pom. Note that sometimes dependencies are specified as required for compile when they are only actually required for test; this should be fixed by changing their scope.
   2. Carefully remove any "Unused declared dependency"s.  This list will contain modules which are not listed in the pom file and have been inherited, either from the parent pom, or from some dependent module.  Care is needed because
      
      1. Maven can only analyze static dependencies, run time loaded dependencies (such as injecting opensaml-impl into the test scope) need to be listed to allow the test to run, equally several modules (e,g, janino, mail) are needed by the logging providers.
      2. Removing an unused dependency may well break "downstream" poms which require this module to be present.  You may wish to 'skip forward' and add the missing module to these modules at the same time that you remove the explicit dependency.
         Eclipse is quite good at warning that this has happened, but you need to keep it refreshed if editing outside eclipse.
   3. Run a build and test inside the subproject
6. Once all subprojects have been completed do a project level build and test - use of 'mvn site' rather than 'mvn install' can be helpful
7. Eyeball all the [changed] poms:
   
   • (Advisable) Ensure that the ordering of the dependencies is consistent; the order currently used is:
     

     • Project supplied, versioned dependencies 

       <dependency>
           <groupId>${project.groupId}</groupId>
           <artifactId>idp-authn-api</artifactId>
           <version>${project.version}</version>
       </dependency>

     • Project supplied, unversioned dependencies: 

       <dependency>
           <groupId>net.shibboleth.ext</groupId>
           <artifactId>spring-extensions</artifactId>
       </dependency>
       

     • Unversioned, non-project dependencies: 

       <dependency>
           <groupId>org.apache.velocity</groupId>
           <artifactId>velocity</artifactId>
       </dependency>

   • Check for -impl modules being included in -api and -impl modules (except for test scope)
8. Check in.  It is advisable to provoke a jenkins build at this stage "just in case".

Which Scope Should It Be?

• provided dependencies should be used only for APIs which are supplied by the run-time container.
• compile dependencies should be used for all other modules whose APIs are referenced by the source code.
• If a compile dependency is used by optional code in a project like java-support, the dependency should be compile but marked as optional. Client projects which require the optional functionality must manually include the missing transitive dependency with runtime scope if they do not already require it at compile scope.
• If a module is required to be present at run time but is not referenced by the source code, it is a runtime scope dependency.
• If a module is not required by the main source code but is required for testing, it is a test scope dependency.

Dependency updates

Dependencies can be updated when new versions become available during development. It is also sensible to perform a check for dependency updates of which we are not otherwise aware prior to a release.

To review the available dependency updates in a particular context (either the parent POM or a subordinate project which defines its own dependencies not managed by the parent project) the command of interest is:

mvn versions:display-dependency-updates

Beta and alpha release suggested as upgrades should be ignored (although there are sometimes other releases between current and the beta which may warrant an upgrade).

Test scopes can usually be upgraded easily, equally minor revisions.  

Obviously critical subsystems (XML handling, beans, encoders) need further discussion.

As of 2020-01-30, for the Java 11 platform, the following exceptions can be noted:

ch.qos.logback:*

com.sun.activation:jakarta.activation

commons-collections:commons-collections

jakarta.activation:jakarta.activation-api

jakarta.json:jakarta.json-api

javax.servlet:javax.servlet-api

org.glassfish:jakarta.json

org.glassfish.jaxb:jaxb-runtime

org.hibernate:hibernate-core

org.ldaptive:ldaptive

org.slf4j:*

Plugin Maintenance

The simplest way to find what is out of date is to run 

mvn versions:display-plugin-updates

Then edit the requisite pom file (which will usually be the parent pom).  Do a complete build  prior to checking in. Use of 'mvn site' rather than 'mvn install' can be helpful in heading off Jenkins issues.