Card Extension Add-on Developer Guide
This guide is intended to help developers who want to create a Keyple card extension add-on for a specific card technology.
- 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.
- Calypsonet Terminal Reader API: public contract provided be Calypso Networks Association including two specific interfaces to be implemented by the card extension and required by the card selection manager.
- Calypsonet Terminal Card API: private contract provided be Calypso Networks Association 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 client application:
The table below lists the objects that must be created and indicates the interfaces to be implemented for each of them:
|Object||Common API||Calypsonet Terminal Reader API||Calypsonet Terminal Card API|
|Card extension service||
|Card selection parser||
|Smart card object||
|Card selector DTO||
|Card selection request DTO||
|Card request DTO||
|APDU request DTO||
In the case where the smart card object has fields of type
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 client application via the Keyple Service selection manager;
- explicitly, when the card has been selected, on request of the client application, by direct use of the APIs exposed by the Card API.
For explicit communication, the card extension must require the client 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
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 service.