Plugin Archetype

Owned by Former user (Deleted)
Last updated: Apr 11, 2024 by Philip Smart

Archetype is out of date

This archetype is currently out of date, contains an internal project-only configuration, and should not be used.

Status

WIP. POM contents have yet to be decided (although we are pretty sure the parent will not be the idp-parent).


Install the archetype to the local catalog manually for the time being (could be published to Nexus long term if useful).

git clone git@git.shibboleth.net:java-idp-plugin-archetype

Install the archetype

cd java-idp-plugin-archetype
mvn install

Create a new temporary directory and use the installed archetype to create a project structure:

mvn archetype:generate -DarchetypeGroupId=net.shibboleth.idp.plugin -DarchetypeArtifactId=plugin-archetype -DarchetypeVersion=0.0.1-SNAPSHOT -DgroupId=org.example.com -DartifactId=idp-plugin-test -Dversion=0.0.1-SNAPSHOT -DpluginBase=myplugin -Dvendor=vendor

Make sure you change the groupId, artifactId, pluginBase and vendor to appropriate values. Or omit them and you will be prompted to add them - or leave them as they are for testing

Running the install will cause maven to resolve multiple artifacts which are (currently) unknown to our signature checker ('The maven enforcer').

Project Structure


The archetype creates a multi-module Maven project; the aggregator (or the parent), and three submodules. There is a single submodule to handle the assembly/distribution of the plugin. For the other two, one submodule encapsulates implementation classes whilst the other encapsulates the plugin's public API. It is not always necessary to create a public API, instead developing solely against the IdP's public API that relates to the functionality of the plugin e.g. the authentication API. The module structure is shown in the table below:


module rootsubmoduledescription
idp-plugin-<plugin>
the aggregator parent project

${pluginBase}-apipublic API classes

${pluginBase}-implimplementation classes of both the plugins public API, and the API of the IdP

${pluginBase}-distdistribution configuration e.g. maven assembly information.

TODO

A property could be used to flag whether the API module should be generated.


The root module POM has the necessary boilerplate required for building IdP plugins. Each submodule has a limited, templated, POM ready for the plugin developer to specify the specific APIs of the IdP they would like to build against. In addition, the -impl module has the boilerplate required for it to interact with the IdP's plugin API (here). The -dist submodule has the boiler plate required to build an IdP compatible plugin. More specifically:


ModuleFileLocationDescription
${pluginBase}-implPluginDescription.javasrc/main/java/<groupId>/A description of the plugin that is exported for compatibility with the IdP's Plugin Service API. See Plug-in Installation#TheServiceInterface
${pluginBase}-implplugins.propssrc/main/resources/plugin/plugin properties that describe the plugin version, and the versions of the IdP which the plugin is compatible
${pluginBase}-implnet.shibboleth.idp.plugin.PluginDescriptionsrc/main/resources/servicesService provider configuration, the fully qualified name of the PluginDescription file.
${pluginBase}-distassembly.xmlsrc/main/assemblyThe maven assembly file for building the final plugin for distribution (as a zip, and gz file).
${pluginBase}-distid.propertysrc/main/resources/bootstrapThe plugin identifier fully qualified string. See Plug-in Installation#bootstrap
${pluginBase}-distkeys.txtsrc/main/resources/bootstrapRequired for plugin trust, see here.

Suggestions

  • I think that now that 4.1 of the IdP is out the versions of the upstream projects should be pinned to 4.1.0 (OpenSAML and IdP) and parent project
    • PS - pinned.
      • It may also be worth aligning the version of the archetype to the IdP e.g. v 4.1.0 of the archetype is pinning to v 4.1.0 of the IdP etc.
  • The documentation probably needs to warn about using the java-parent project if you are not us
    • PS - agreed, I just need to think through what happens if you don't so I can advise. 
  • I got confused between -DarchetypeArtifactId=plugin-archetype and -DgroupId=org.example.com  but that was my fault and easily fixed 
    • PS - so did I went I went back to it!
  • I was going to suggest moving the Version stuff into impl, but my  memory is that the tests fail and need care (because they don't run from the jar).  So lets leave it there
  • A .gitignore  would be nice
    • Added
  • The <automatic.module.name>  looked weird: net.shibboleth.idp.plugin.metadatagen.metadatagen.api 
    • PS - the format here is `${groupId}.${pluginBase}.api` do you remember what $pluginBase was when you created the project?
  • As did the <Implementation-Vendor>FINISH</Implementation-Vendor> 
    • PS - Added a vendor parameter that defaults to FIXME-VENDOR if not supplied.
  • It would be nice if there was more templating in the assembly.xml  file