Java Modularity

Java 9 introduced the Java Platform Module System (JPMS), allowing — amongst other advantages — better encapsulation of the internals of software components.

Current Shibboleth products are modularised in the sense of being broken into components presented as JARs, but were not designed for use with the JPMS:

• Although an API vs. implementation separation is maintained in the OpenSAML library and the Identity Provider product, this separation depends on convention rather than language-supplied mechanisms. Shibboleth JARs do not explicitly declare which of their packages are available to other modules.

• Shibboleth JARs do not declare their dependencies on other Java modules. Dependencies are instead expressed through the Maven pom.xml as being on other Maven artifacts.

• Shibboleth JARs are only tested on the class path, not the module path. As access rules are different when the module path is used, this may cause problems if a Shibboleth JAR is used as an "automatic module".

Compatibility with, and taking advantage of, the Java module system is a long-term rather than a short-term goal of the Shibboleth Project:

• Please report any modularity issues with Shibboleth using JIRA.

• Shibboleth JARs are provided with appropriate automatic module names to reduce future name stability issues.

Automatic Module Names

One of the transition mechanisms implemented by Java to assist with a migration towards fully modularised applications is to allow a conventional non-modular JAR to be placed on the application's module path. In this case it is treated as an automatic module, and given a computed list of exports and dependencies. It is also given a module name automatically derived from the JAR file name. This can result in a loss of global uniqueness in module names and lack of stability in module names both when JAR names change and when a JAR is ultimately converted to a "real" module.

To avoid these naming problems, it is regarded as best practice to provide non-modular JARs with a reserved module name through an entry in the JAR's manifest. This then replaces the default automatic module name and provides name stability for modular clients.

In general, Shibboleth modules are given reserved module names based on their root package name. The following sections describe the specific allocation for each current Shibboleth JAR.

OpenSAML

Notes:

1. No artifact, so no module name required.

2. The API module root package is (unusually for an -api module) org.opensaml.xacml.profile.saml rather than org.opensaml.xacml.saml. The proposal here goes with the root package convention for the API module and the submodule convention for the -impl module.

3. R = Named according to the root package convention.

4. S = Named as a submodule.

Identity Provider

Notes:

1. No artifact, so no module name required.

2. This module will be problematic in its current form should we move to real use of the JPMS. idp-schema has resources under a schema path, which is to say as far as Java is concerned in a package called schema. While this is valid, it's not ideal long term for the usual reasons around uniqueness: only one module may contain a given package, even if the package is not exported.

3. idp-attribute-resolver-impl does not have a root package, but two. As well as net.shibboleth packages, it also includes a legacy package edu.internet2.middleware.shibboleth.common.attribute.provider (and two classes: BasicAttribute and V2SAMLProfileRequestContext) for backwards compatibility - see https://shibboleth.atlassian.net/browse/IDP-1457. This module will be named ignoring the legacy package.

4. This module's actual root (and only) package is net.shibboleth.idp.consent.context. However, the corresponding -impl module's packages do not lie under this but under net.shibboleth.idp.consent. We therefore use the latter as the implicit root package for the module to provide consistency with other modules.

5. Note that this omits the -core part of the artifact name. Is this an issue?

6. idp-profile-api also includes net.shibboleth.idp.relyingparty so does not have a true root package. We should consider renaming this oddball package or moving it to a new module. Another one to have resolved if possible for V3.4.

7. The JAR is not used on the class path, so doesn't need to be assigned a module name. However, an implementation detail means that we want to assign one anyway, see JPAR-113.

8. R = Named according to the root package convention.

9. S = Named as a submodule.

Metadata Agggregator

aggregator-parent, aggregator-bom do not generate JARs, so don't need names.

aggregator-pipeline by root package: net.shibboleth.metadata

aggregator-cli by root package: net.shibboleth.metadata.cli

aggregator-blacklists is currently problematic due to a split package with aggregator-pipeline. Proposed resolution: net.shibboleth.metadata.blacklists

java-support Library

By root package: net.shibboleth.utilities.java.support

spring-extensions Library

By root package: net.shibboleth.ext.spring