Creating an Add-On

SeedStack is an extensible solution that can be enriched with add-ons to provide new functionality or features. Writing an add-on is not a difficult task as it is very similar to writing an application but some rules and conventions must be obeyed. This guide will describe these rules and conventions.

Project structure

An add-on almost always consists in an API/SPI with one or more implementations. Depending on the complexity of the add-on and the re-usability requirements, several project structures can be used.

Single-module add-on

The simplest form of add-on is a single module project. In this case, the API/SPI and the implementation will be contained in a single JAR artifact. The typical single-module add-on structure is:

single-addon
    |- src/main/java
    |   |- org.myorg.feature    <-- API goes in the add-on base package
    |       |- internal         <-- Implementation            
    |       |- spi              <-- SPI if any
    |- src/test/java
        ...

Example single module add-on: https://github.com/seedstack/jpa-addon

Add-on with a separated API/SPI

When you need to provide the API/SPI to clients separately from the implementation you need to create a multi-module add-on:

  • The specs module will contain the API (and the SPI if any),
  • The core module will contain the implementation.

The typical structure for such add-on is:

multi-addon
    |- core
    |   |- src/main/java
    |   |   |- org.myorg.feature    
    |   |       |- internal         <-- Implementation            
    |   |- src/test/java
    |       ...
    |- specs        
    |   |- src/main/java
    |   |   |- org.myorg.feature    <-- API goes in the add-on base package
    |   |       |- spi              <-- SPI if any
    |   |- src/test/java
            ...

Java packages are still the same that found in the single module add-on but segregated in two maven modules.

Multiple implementations add-on

When you have multiple implementations or implementation extensions for an add-on you can add a new sub-module per implementation/extension. This type of add-on is the same a the previous one with additional sub-modules:

  • The specs module will contain the API (and the SPI if any),
  • The core module will contain the main/common implementation,
  • The impl1 module will contain the impl1 implementation,
  • The impl2 module will contain the impl2 implementation,
  • …
multi-addon
    |- core
    |   |- src/main/java
    |   |   |- org.myorg.feature    
    |   |       |- internal         <-- Main/common implementation            
    |   |- src/test/java
    |       ...
    |- impl1
    |   |- src/main/java
    |   |   |- org.myorg.feature.impl1    
    |   |       |- internal         <-- Implementation/extension 1            
    |   |- src/test/java
    |       ...
    |- impl2
    |   |- src/main/java
    |   |   |- org.myorg.feature.impl2    
    |   |       |- internal         <-- Implementation/extension 2            
    |   |- src/test/java
    |       ...
    |- specs        
    |   |- src/main/java
    |   |   |- org.myorg.feature    <-- API goes in the add-on base package
    |   |       |- spi              <-- SPI if any
    |   |- src/test/java
            ...

If you don’t have any API, like when it is provided by a third party, you can omit the specs module completely.

Example multi-module add-on: https://github.com/seedstack/i18n-addon

Dependencies

As the add-on is a reusable component which will be used in various contexts, the rules on dependencies are tighter than on applications.

As a general rule, try to minimize the number of dependencies in your add-on to help avoid unintended side-effects and limit its impact on client projects.

  • Any dependency that will be provided by the client project or its runtime environment must be specified with a provided scope. The meaning here is that the dependency is required for proper operation but must be provided downstream.
  • If your add-on contains optional features that have dependencies you have two options:
    • Either package those features in their own implementation sub-module with their own dependencies,
    • Or package those features in the core implementation, mark their dependencies as optional and use conditional code to initialize those features only when their dependency requirements are met.

API/SPI

All API classes go in the base package of the add-on. All SPI classes go in a spi subpackage of the base package. Try to keep the API classes as flat as possible, ideally without subpackage.

Implementation

All implementation classes go in a *.internal.* which is completely excluded from backwards compatibility requirements between versions.


On this page


Edit