Overview
This guide is intended to help developers who want to create a Keyple card extension add-on for a specific card technology.
Operating mode
- Learn the card extension architecture concepts
- Take note of the minimal requirements
- Define the card commands
- Set up the development environment
- Implement the solution
Card extension architecture
A Keyple card extension contains a set of objects which meet the following three interface specifications:
- Common API: public contract including a generic type common to all card extensions.
- Keypop Reader API: public contract provided by the Eclipse Keypop project including two specific interfaces to be implemented by the card extension and required by the card selection manager.
- Keypop Card API: private contract provided by the Eclipse Keypop project based on two types of
interfaces:
- API (Application Programming Interface): interface implemented by Keyple Service and directly usable by the card extension code.
- SPI (Service Provider Interface): interface to be implemented by the card extension and directly used by Keyple Service.
The component diagram below illustrates the internal API/SPI links between the card extension and Keyple Service, as
well as the public APIs exposed to the application:
Minimal requirements
The table below lists the objects that must be created and indicates the interfaces to be implemented for each of them:
| Object | Common API | Keypop Reader API | Keypop Card API |
|---|---|---|---|
| Card extension service | KeypleCardExtension | ||
| Card selection parser | CardSelectionExtension | CardSelectionExtensionSpi | |
| Smart card object | SmartCard or IsoSmartCard | SmartCardSpi | |
| Card selection request DTO | CardSelectionRequestSpi | ||
| Card request DTO | CardRequestSpi | ||
| APDU request DTO | ApduRequestSpi |
In the case where the smart card object has fields of type interface,
it will then be necessary to define for each of them and recursively a JSON deserializer and register it during the
service initialization with the method JsonUtil.registerTypeAdapter(...) provided by the
Keyple Util library.
This will allow the transport of this object through the network when using the Keyple Distributed solution.
Define the card commands
The card extension takes part in the communication with the card in two ways:
- implicitly, when the card is being selected, which is done directly by the application via the Keyple Service selection manager;
- explicitly, when the card has been selected, on request of the application, by direct use of the APIs exposed by the Card API.
For explicit communication, the card extension must require the application to provide a reference to a CardReader of
the Reader API.
This can then be cast internally to a ProxyReaderApi of the Card API through which it will be possible to transmit
card commands.
Each card extension is free to define the APIs it considers relevant to perform card transactions.
Set up dev environment
If the card extension add-on is to be integrated into the Eclipse Keyple® project, it must use the following project template:
- Java template
- adapt fields
[CARD_EXTENSION_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) not accessible from a public service.
