Distributed application

Overview

Keyple provides the “Keyple Distributed” solution which allows a terminal to communicate with a smart card reader available in another terminal.

In this way, you can manage transactions within a distributed architecture.

The diagram below shows the role of the Keyple Distributed components in the software layers used in a distributed architecture :

How to use it ?

1. In pre-requisite, read page Standalone application to understand the main concepts of Keyple in a standalone application.
2. Read chapter Concepts to understand the main terms and concepts of the Keyple Distributed solution.
3. Read the introduction of chapter Configuration modes to be informed about the different features and APIs proposed by the solution.
4. Using chapter Use cases, find your use case. This will help you to determine exactly which library and API to use.
5. Using chapter Download, import into your project the libraries specified by your use case.
6. Using chapter Network configuration, implement the transport layer adapted to your network configuration.
7. Implement your ticketing services as specified in the associated use case.

Concepts

Here are the main concepts to keep in mind before continuing to read this user guide :

The diagram below illustrates the main functional concepts through a standard use case :

The second diagram below illustrates an arbitrary more complex possible use case with several hardware readers connected to different terminals.

These could be for example a ticketing reloading service, where the business logic would be on the terminal with remote readers, with thin clients on A & B terminals communicating locally with the cards.

In this use case, the Keyple Distributed solution is use for card communication.

Here is another example, but this time it illustrates several Remote Plugin components connected to the same Local Service.

These could be for example ticketing terminals with transaction logic, which communicate locally with cards, but which do not have SAM, and which use a SAM server with hardware reader.

In this use case, the Keyple Distributed solution is use for SAM communication.

Configuration modes

The Keyple Distributed solution provides 3 different configuration modes, each one having a specific API designed on a Client-Server model :

Each mode provides a different Remote Plugin and Local Service components and their associated factories and utility classes.

Each Remote Plugin and Local Service has a default name, but it’s possible to specify a custom name during the initialization phase.

In an application, it is thus possible to use simultaneously several configuration modes and as many instances of a configuration mode as you want, as long as the components are initialized with different names.

Reader Client Side

This configuration mode allows a server application to control a smart card reader available on a client (e.g. PO reader).

OPERATING MODE

• Server side :
  1. configure the factory by providing the network and plugin observer implementation. Please note that this plugin is observable only to trigger ticketing services on the server side, but does not allow observation on the local plugin (reader insertion, etc…),
  2. register the Remote Plugin to the smart card service using the factory,
  3. await for events of type PluginEvent.READER_CONNECTED,
  4. when an event occurs, get the specified remote reader from the Remote Plugin,
  5. use information inside the remote reader to identify the ticketing service to execute,
  6. execute the specified ticketing service using the remote reader and all of its others information,
  7. terminate the remote ticketing service using the Remote Plugin API by transmitting if needed personal information to the client.
• Client side :
  1. configure the factory and start the Local Service by providing the network implementation,
  2. register at least a local plugin to the smart card service and get the local reader to connect to the server,
  3. execute the remote service using the Local Service API by indicating the ticketing service id to execute and transmitting to the server if needed personal information or smart card content previously read.

ILLUSTRATION

The following sequence diagram shows the capabilities of the plugin through an arbitrary example that illustrates :

• the initialization phase of the local and remote components ;
• the registration of the local plugin and observable reader ;
• the selection phase of an observable reader carried out directly by the client ;
• the sending of the selection result and additional information to the server to remotely perform a specific ticketing service (materialization, validation, etc…) ;
• the reception by the server of the transmitted data ;
• the execution of the remote ticketing service ;
• the server subscription to observable reader events ;
• the sending of information to the client at the end of processing.

Note that the network layer is deliberately hide in this diagram. Its implementation is described in the Network configuration chapter.

Reader Server Side

This configuration mode allows a client application to control a smart card reader available on a server (e.g. SAM reader).

It also allows to observe the plugin events (such as reader connection, etc…) if desired.

OPERATING MODE

• Server side :
  1. configure the factory and start the Local Service by providing the network implementation,
  2. register at least a local plugin to the smart card service.
• Client side :
  1. configure the factory by providing the network implementation,
  2. register the Remote Plugin to the smart card service using the factory,
  3. use the Remote Plugin and its remote readers as a local plugin (or observable plugin) with local readers.

Pool Reader Server Side

This configuration mode allows a client application to control a pool of smart cards readers available on a server (e.g. HSM readers).

OPERATING MODE

• Server
  1. configure the factory and start the Local Service by providing the network implementation,
  2. register at least a local pool plugin to the smart card service.
• Client
  1. configure the factory by providing the network implementation,
  2. register the Remote Plugin to the smart card service using the factory,
  3. use the Remote Plugin and its remote readers as a local pool plugin with local readers.

Use cases

Here is a summary table of all proposed use cases. Search for the one that corresponds to your need and then look at the associated description :

UC 1

This use case requires to use the Reader Client Side configuration mode.

Use this mode if you don’t plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that it is still possible to observe locally the reader on the client side if needed.

UC 2

This use case requires to use the Reader Client Side configuration mode.

Use this mode if you plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that this mode is only possible if the local reader is observable.

To observe “remotely” the reader events, you must :

• Server
  1. register at least one observer to the remote reader created during the first client call and await for reader events,
  2. retrieve the remote reader from the Remote Plugin imperatively using the reader name contained in the received event,
  3. execute the ticketing service associated to the event using the remote reader and all of its others information,
  4. terminate the remote ticketing service associated to the event using the Remote Plugin API by transmitting if needed personal information to the client.
• Client
  1. execute a remote service first in order to connect a remote reader to the local reader and to allow the remote application to subscribe to the events of the remote reader.

UC 3

This use case requires to use the Reader Server Side configuration mode with the RemotePluginClient plugin.

Use this mode if you don’t plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that it is still possible to observe locally the reader on the server side if needed.

UC 4

This use case requires to use the Reader Server Side configuration mode with the RemotePluginClient plugin.

Use this mode if you plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that this mode is only possible if the local reader is observable.

UC 5

This use case requires to use the Reader Server Side configuration mode with the ObservableRemotePluginClient plugin.

Use this mode if you don’t plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that it is still possible to observe locally the reader on the server side if needed.

UC 6

This use case requires to use the Reader Server Side configuration mode with the ObservableRemotePluginClient plugin.

Use this mode if you plan to observe “remotely” the events related to the local reader (smart card insertion, removal, etc…).

Please note that this mode is only possible if the local reader is observable.

UC 7

This use case requires to use the Pool Reader Server Side configuration mode.

This unique mode proposed for this plugin does not allow to observe the local reader.

Network configuration

The Keyple Distributed solution does not provide the network layer implementation, but it provides a set of SPIs (Service Provider Interfaces) to be implemented by the user in order to enable it to exchange data between Remote Plugin and Local Service components.

Synchronous

Choose this mode if you want to implement a Client-Server Synchronous communication protocol, such as standard HTTP for example.

Here is the minimal algorithm to implement in a context with a single server instance :

In a context with several server instances, a mechanism must be implemented to ensure that all messages containing information about a serverNodeId are routed to the server associated with a SyncNodeServer node having the serverNodeId.

Asynchronous

Choose this mode if you want to implement a Full-Duplex Asynchronous communication protocol, such as Web Sockets for example.

Here is the minimal algorithm to implement :

Exchanged data

The data exchanged between Remote Plugin and Local Service components are contained in the DTO (Data Transfer Object) MessageDto. It is built and processed by the plugin and you don’t need to modify it.

However, it is necessary in some contexts to access certain information such as the sessionId in the case of asynchronous communication or the serverNodeId in the case of synchronous communication with several server instances.

APIs

The class diagrams below shows the different APIs exposed and SPIs required by the Keyple Distributed solution.

An SPI (Service Provider Interface) is an interface that must be implemented by the user.

Here are the available APIs depending on the library imported by your project :

The associated API documentations are accessible from the page API Reference.

Network API

The associated API documentation is available here.

Remote API

The associated API documentation is available here.

Local API

The associated API documentation is available here.

Examples

• Java examples

Download

• Java components