Overview
This guide is intended to help developers who want to create a Keyple reader plugin add-on for a specific device.
Operating mode
- Learn the plugin architecture concepts
- Select the predefined features that meet your need
- Define specific features (optional)
- Set up the development environment
- Implement the solution
Plugin architecture
A Keyple reader plugin consists of three objects, a plugin factory, a plugin and a reader, which meet the following two interface specifications:
- Common API: public contract containing only generic types common to all plugins.
- Plugin API: private contract based on two types of interfaces:
- API (Application Programming Interface): interface implemented by Keyple Service and directly usable by the plugin code.
- SPI (Service Provider Interface): interface to be implemented by the plugin and directly used by Keyple Service.
The component diagram below illustrates the internal API/SPI links between the plugin and Keyple Service, as well as the public APIs exposed to the application:
Select predefined features
The diagram below helps you to determine exactly which interfaces to implement according to the characteristics of the reader:
XxxPluginFactory
, XxxPlugin
and XxxReader
interfaces must be created.
They are specific to the plugin Xxx
to be created but can remain empty if there is no specific feature.Define specific features
Depending on the characteristics of the reader, it may be necessary to add in the specific APIs configuration methods appropriate to the technical context.
These features can be exposed at three levels:
- In the plugin factory (
XxxPluginFactory
interface), for the initial configuration of the plugin (e.g. set custom plugin name). - In the plugin (
XxxPlugin
interface), for dynamic configurations that can be applied to all the readers (e.g. put the readers in sleep mode).
The API will then be directly accessible from the application through thegetExtension(...)
method of the plugin registered with Keyple Service. - In the reader (
XxxReader
interface), for dynamic configurations specific to each reader (e.g. activate/deactivate a LED).
The API will then be directly accessible from the application through thegetReaderExtension(...)
method of the reader provided by the plugin registered with Keyple Service.
Set up dev environment
If the reader plugin add-on is to be integrated into the Eclipse Keyple® project, it must use one of the following project templates:
- Java template
- adapt fields
[READER_PLUGIN_NAME]
,Xxx
,xxx
,TODO
- Android template
- adapt fields
[ANDROID_READER_PLUGIN_NAME]
,Xxx
,xxx
,TODO
Before pushing the project to GitHub the first time, you must give write permission to some scripts files via the following commands:
git update-index --chmod=+x "gradlew"
git update-index --chmod=+x "scripts/check_version.sh"
git update-index --chmod=+x "scripts/prepare_javadoc.sh"
If examples are proposed, they should be placed in the keyple-java-example repository.
The contribution procedure is described here.
Implement the solution
For this purpose, it is suggested to respect the following programming pattern based on the use of:
- public interfaces,
- private interfaces adapters (package visibility) accessible from a public provider/builder.