https://github.com/toolisticon/spi-annotation-processor
Annotation processor that handles creation of service file and service locator
https://github.com/toolisticon/spi-annotation-processor
annotation-processor annotation-processor-toolkit hacktoberfest java service services spi spi-annotation-processor
Last synced: about 1 year ago
JSON representation
Annotation processor that handles creation of service file and service locator
- Host: GitHub
- URL: https://github.com/toolisticon/spi-annotation-processor
- Owner: toolisticon
- License: mit
- Created: 2017-11-16T23:57:59.000Z (over 8 years ago)
- Default Branch: develop
- Last Pushed: 2023-12-15T05:15:45.000Z (over 2 years ago)
- Last Synced: 2025-03-25T19:14:39.205Z (about 1 year ago)
- Topics: annotation-processor, annotation-processor-toolkit, hacktoberfest, java, service, services, spi, spi-annotation-processor
- Language: Java
- Homepage:
- Size: 273 KB
- Stars: 7
- Watchers: 10
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SPI-Annotation-Processor
[](https://maven-badges.herokuapp.com/maven-central/io.toolisticon.spiap/spiap-processor)
[](https://travis-ci.org/toolisticon/SPI-Annotation-Processor)
[](https://codecov.io/gh/toolisticon/SPI-Annotation-Processor)
# Why you should use this project?
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.
# Prerequisites
- The generated ServiceLocator code requires at least JDK 8.
# Features
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)
# How does it work?
First you need to add the SPI annotation processor dependencies to your project.
io.toolisticon.spiap
spiap-api
The annotation processor should be applied by defining it in annotation processor path of maven-compile-plugin:
maven-compiler-plugin
io.toolisticon.spiap
spiap-processor
CURRENT_VERSION
## How to generate the service locator class
### By annotating the service provider interface
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)
### By annotating a package
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;
## How to register a service implementation
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!";
}
}
## How to use the service locator
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.
## Disable service implementations in the service locator
Just add the _OutOfService_ annotation next to the Services or Service annotation to disable the service implementation in the service locator.
# Contributing
We welcome any kind of suggestions and pull requests.
## Building and developing the SPI-Annotation-Processor
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`
## Requirements
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](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html).
## Contributions
- (2017) Tobias Stamann (Holisticon AG)
# License
This project is released under the revised [MIT License](LICENSE).
This project includes and repackages the [Annotation-Processor-Toolkit](https://github.com/holisticon/annotation-processor-toolkit) released under the [MIT License](/3rdPartyLicenses/annotation-processor-toolkit/LICENSE.txt).