If you want to use a service provider interface (SPI) you need to register your service implementation in the /META-INF/services/<Full qualified spi interface name> file. Additionally, you usually need to write a service locator to be able to use the service implementation.
The annotation processor offered by this project provides exactly this. It allows you to create the service locator file just by adding an annotation to you spi implementation. Additionally, it will generate a service locator for you.
- The generated ServiceLocator code requires at least JDK 8.
Annotation processor that
- provides support for generating service locator file in /META-INF/services/<Full qualified spi interface name>
- provides support for generating service locator class for accessing the SPI implementations
- compatible with Java >= 8 (Java 7 support up to version 0.8.2)
First you need to add the SPI annotation processor dependencies to your project.
<dependencies>
<!-- api is just needed in compile scope if you want to use the ServiceLocator features -->
<dependency>
<groupId>io.toolisticon.spiap</groupId>
<artifactId>spiap-api</artifactId>
</dependency>
</dependencies>
The annotation processor should be applied by defining it in annotation processor path of maven-compile-plugin:
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.toolisticon.spiap</groupId>
<artifactId>spiap-processor</artifactId>
<version>CURRENT_VERSION</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
Just add the Spi annotation to your SPI:
@Spi
public interface ExampleSpiInterface {
String doSomething();
}
The locator is named like the SPI suffixed with ServiceLocator (ExampleSpiInterfaceServiceLocator in this example)
Create a package-info.java file in the package were you want to create the service locator in. Then add the SpiServiceLocator annotation in it:
@SpiServiceLocator(ExampleSpiInterface.class)
package your.target.package;
import io.toolisticon.spiap.api.SpiServiceLocator;
import your.spi.package.ExampleSpiInterface;
The locator will be created in the annotated package. It is named like the SPI suffixed with ServiceLocator (ExampleSpiInterfaceServiceLocator in this example)
To create multiple service locators in the same package use @SpiServiceLocators:
@SpiServiceLocators({
@SpiServiceLocator(FirstExampleSpiInterface.class),
@SpiServiceLocator(SecondExampleSpiInterface.class)
})
package your.target.package;
import io.toolisticon.spiap.api.SpiServiceLocator;
import your.spi.package.FirstExampleSpiInterface;
import your.spi.package.SecondExampleSpiInterface;
Just add a Service annotation to your service implementation:
@SpiService(value = ExampleSpiInterface.class, id = "YOUR_OPTIONAL_SERVICE_ID", description = "OPTIONAL DESCRIPTION", priority = 0)
public class ExampleSpiService implements ExampleSpiInterface {
@Override
public String doSomething() {
return "IT WORKS !";
}
}
Service annotations mandatory value must declare the SPI you want the service class to be registered to. All other annotation attributes are optional.
- id defines a custom id which can be used to locate a specific services implementation via the generated service locator class. Defaults to fully qualified service class name in generated service locator.
- description declares a short description about the implementation
- priority is used to define a specific order in which the services are located
It's also possible to implement more than one SPI in a class by using the Services annotation:
@SpiServices({
@SpiService(value = ExampleSpiInterface1.class, id = "YOUR_OPTIONAL_SERVICE_ID", description = "OPTIONAL DESCRIPTION", priority = 0),
@SpiService(value = ExampleSpiInterface2.class)
})
public class ExampleSpiService implements ExampleSpiInterface1, ExampeSpiInterface2 {
@Override
public String doSomething1() {
return "IT WORKS !";
}
@Override
public String doSomething2() {
return "IT WORKS TOO!";
}
}
System.out.println(ExampleSpiInterfaceServiceLocator.locate().doSomething());
It's not required to have the spiap-api dependency at runtime anymore since settings of annotations will be stored in a generated property file (stored in /META-INF/spiap/<service interface fqn>/<service implementation fqn>.properties). See our examples subprojects for further information.
Just add the OutOfService annotation next to the Services or Service annotation to disable the service implementation in the service locator.
We welcome any kind of suggestions and pull requests.
The SPI-Annotation-Processor is built using Maven (at least version 3.0.0).
A simple import of the pom in your IDE should get you up and running. To build the annotation-processor-toolkit on the commandline, just run mvn
or mvn clean install
The likelihood of a pull request being used rises with the following properties:
- You have used a feature branch.
- You have included a test that demonstrates the functionality added or fixed.
- You adhered to the code conventions.
- (2017) Tobias Stamann (Holisticon AG)
This project is released under the revised MIT License.
This project includes and repackages the Annotation-Processor-Toolkit released under the MIT License.