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 developer guide :

ConceptDescription
Remote LibThis is the library keyple-java-distributed-remote.
It must be imported and used by the application installed on the terminal not having local access to the smart card reader and that wishes to control the reader remotely.
Local LibThis is the library keyple-java-distributed-local.
It must be imported and used by the application installed on the terminal having local access to the smart card reader but wishes to delegate all or part of the ticketing processing to a remote application.
Network LibThis is the library keyple-java-distributed-network.
This library is implicitly imported by Remote Lib and Local Lib because it contains common network elements.
Remote PluginPart of the Remote Lib, this is a Keyple plugin which provides only Remote Readers to the application. It manages data exchanges with the Local Service. This plugin must be registered to the smart card service like any Keyple plugin.
Remote ReaderPart of the Remote Plugin, this is a Keyple reader which has some specificities :
- each remote reader is connected to a local reader ;
- any command sent by the application to a remote reader will be forwarded to the associated local reader ;
- any event occurs on a local reader or plugin will be forwarded to the associated remote reader or plugin.
Local ServicePart of the Local Lib, this service ensures data exchange between the Remote Plugin and local plugins and readers. It must be initialized and started by the host application.
FactoryRemote Plugin and Local Service each have a specific factory class to initialize them.
UtilityRemote Plugin and Local Service each have a specific utility class to access them everywhere in the code.
NodeRemote Plugin and Local Service each are bind to a specific internal node which is responsible for the interfacing with the Network Endpoint.
Network EndpointAt the user’s charge, this component ensures the network exchanges between the Remote Plugin and Local Service nodes.

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 :

Configuration modeDescription
Reader Client SideAllows a server application to control a smart card reader available on a client (e.g. PO reader).
Reader Server SideAllows a client application to control a smart card reader available on a server (e.g. SAM reader).
Pool Reader Server SideAllows a client application to control a pool of smart cards readers available on a server (e.g. HSM readers).

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).

APIClientServer
LibraryLocal LibRemote Lib
Remote Plugin / Local ServiceLocalServiceClientRemotePluginServer
FactoryLocalServiceClientFactoryRemotePluginServerFactory
UtilityLocalServiceClientUtilsRemotePluginServerUtils

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 will only be available from version 1.1 onwards.

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.

APIClientServer
LibraryRemote LibLocal Lib
Remote Plugin / Local ServiceRemotePluginClient or
ObservableRemotePluginClient
LocalServiceServer
FactoryRemotePluginClientFactoryLocalServiceServerFactory
UtilityRemotePluginClientUtilsLocalServiceServerUtils

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).

APIClientServer
LibraryRemote LibLocal Lib
Remote Plugin / Local ServicePoolRemotePluginClientPoolLocalServiceServer
FactoryPoolRemotePluginClientFactoryPoolLocalServiceServerFactory
UtilityPoolRemotePluginClientUtilsPoolLocalServiceServerUtils

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 :

Use CaseReader typeReader endpointReader observationPlugin observation
UC 1SimpleClient
UC 2SimpleClient✔️
UC 3SimpleServer
UC 4SimpleServer✔️
UC 5SimpleServer✔️
UC 6SimpleServer✔️✔️
UC 7PoolServer

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.

ClientServer
Methods to be used when initializing the factorywithoutReaderObservation()-
Possible readers to useReader or ObservableReaderRemoteReaderServer

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.

ClientServer
Methods to be used when initializing the factorywithReaderObservation(...)-
Possible readers to useObservableReaderObservableRemoteReaderServer

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.

ClientServer
Methods to be used when initializing the factorywithoutPluginObservation()
withoutReaderObservation()
-
Possible readers to useReaderReader or ObservableReader

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.

ClientServer
Methods to be used when initializing the factorywithoutPluginObservation()
withReaderObservation()
-
Possible readers to useObservableReaderObservableReader

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.

ClientServer
Methods to be used when initializing the factorywithPluginObservation()
withoutReaderObservation()
-
Possible readers to useReaderReader or ObservableReader

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.

ClientServer
Methods to be used when initializing the factorywithPluginObservation()
withReaderObservation()
-
Possible readers to useObservableReaderObservableReader

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.

ClientServer
Methods to be used when initializing the factory--
Possible readers to useReaderReader

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.

ClientServer
SPI to be implementedSyncEndpointClient-
Node APISyncNodeClientSyncNodeServer
Methods to be used when initializing the factorywithSyncNode(...)withSyncNode()
Utility method to use to access the node-getSyncNode() or
getSyncNode(...)

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.

ClientServer
SPI to be implementedAsyncEndpointClientAsyncEndpointServer
Node APIAsyncNodeClientAsyncNodeServer
Methods to be used when initializing the factorywithAsyncNode(...)withAsyncNode(...)
Utility method to use to access the nodegetAsyncNode() or
getAsyncNode(...)
getAsyncNode() or
getAsyncNode(...)

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 :

Remote LibLocal Lib
Network API✔️✔️
Remote API✔️
Local API✔️

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


Download

Previous
Next