This archetype is currently out of date, contains an internal project-only configuration, and should not be used. |
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'). |
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 root | submodule | description |
|---|---|---|
| idp-plugin-<plugin> | the aggregator parent project | |
| ${pluginBase}-api | public API classes | |
| ${pluginBase}-impl | implementation classes of both the plugins public API, and the API of the IdP | |
| ${pluginBase}-dist | distribution configuration e.g. maven assembly information. |
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:
| Module | File | Location | Description |
|---|---|---|---|
| ${pluginBase}-impl | PluginDescription.java | src/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}-impl | plugins.props | src/main/resources/plugin/ | plugin properties that describe the plugin version, and the versions of the IdP which the plugin is compatible |
| ${pluginBase}-impl | net.shibboleth.idp.plugin.PluginDescription | src/main/resources/services | Service provider configuration, the fully qualified name of the PluginDescription file. |
| ${pluginBase}-dist | assembly.xml | src/main/assembly | The maven assembly file for building the final plugin for distribution (as a zip, and gz file). |
| ${pluginBase}-dist | id.property | src/main/resources/bootstrap | The plugin identifier fully qualified string. See Plug-in Installation#bootstrap |
| ${pluginBase}-dist | keys.txt | src/main/resources/bootstrap | Required for plugin trust, see here. |
-DarchetypeArtifactId=plugin-archetype and -DgroupId=org.example.com but that was my fault and easily fixed .gitignore would be nice<automatic.module.name> looked weird: net.shibboleth.idp.plugin.metadatagen.metadatagen.api <Implementation-Vendor>FINISH</Implementation-Vendor> vendor parameter that defaults to FIXME-VENDOR if not supplied.assembly.xml file