Distributed Application User Guide

Overview

Keyple provides the “Keyple Distributed” solution which allows an application to communicate with a smart card reader interfaced with another host.

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

The “Keyple Distributed” solution can be deployed in two ways:

• both client and server embed Keyple components,
• only the server embeds Keyple components, the client has its own libraries to communicate with its card reader.

The diagram below illustrates the first way, the use of the Keyple Distributed components when both client and server embed Keyple components (note that the card reader can be either client-side or server-side):

The diagram below illustrates the second way, the architecture with a client not running Keyple but connected to a server based on Keyple:

User guides

• How to build a fully Keyple distributed application
• How to make a non-Keyple client interact with a Keyple-based server application

Fully Keyple distributed application

Steps:

1. In pre-requisite, read Standalone Application User Guide to understand the main concepts of Keyple in a standalone application.
2. Learn main terms and concepts of the Keyple Distributed solution.
3. Find your usage mode. This will help you to determine exactly which library and API to use.
4. Import into your project the libraries specified by your usage mode.
5. Implement the transport layer adapted to your network configuration.
6. Implement your ticketing services as specified in the associated usage mode.

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

These could be for example a ticketing reloading service, where the business logic would be on the host without local readers, with thin clients on A & B hosts 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 plugins 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.

Usage modes

The Keyple Distributed solution offers two different usage modes, each one having a specific API designed on a Client-Server model:

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

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

Reader Client Side

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

In this mode, the client is the initiator of the application processing following the local plugin or reader events (reader connection/disconnection or card insertion/removal).

He can hand over to the server whenever he wants to perform a remote ticketing service on a card present in one of his local readers.

The table below shows the classes and interfaces available for this usage mode.
Interfaces marked with an asterisk “*” come from the Keypop Reader API.
Interfaces marked with an asterisk “**” come from the Keyple Service API:

OPERATING MODE

• Server
  1. Build an instance of the RemotePluginServerFactory using the RemotePluginServerFactoryBuilder class, specifying a unique name for the Remote Plugin to be registered and your network endpoint implementation if required.
  2. Register the Remote Plugin to the smart card service by providing the previously built factory.
  3. Cast the registered plugin into an ObservablePlugin and add an event observer to it.
     
     Please note that this remote plugin is observable only to trigger ticketing services on the server side, but does not allow observation on the local plugin such as reader connection or disconnection.
  4. Await for events of type PluginEvent.Type.READER_CONNECTED.
     
     This type of event indicates to the server that a client asks it to perform a specific ticketing service using the connected remote reader.
  5. When an event occurs, you must retrieve the connected remote reader from the registered plugin using the name of the reader contained in the event.
     
     Please note that the remote reader is strictly an instance of CardReader, even if the local reader is an ObservableCardReader.
     This usage mode does not allow to observe reader events such as card insertion or removal from the server.
     It is the responsibility of the client to observe the local reader if needed, then to ask the server to execute a specific remote service depending on the case.
  6. Use information inside the RemoteReaderServer extension of the remote reader to identify the ticketing service to execute.
  7. Execute the specified ticketing service using the remote reader and all of its other information.
  8. End the remote ticketing service by invoking the associated method provided by the RemotePluginServer extension of the remote plugin.
     It is then possible to send additional information to the client if necessary.
• Client
  1. Build an instance of the LocalServiceClientFactory using the LocalServiceClientFactoryBuilder class, specifying a unique name for the Local Service to be registered and your network endpoint implementation.
  2. Register the Local Service to the smart card service by providing the previously built factory.
  3. Register at least a local plugin to the smart card service and get the name of the local reader to connect to the server.
  4. Execute the desired remote service by invoking the associated method provided by the LocalServiceClient extension of the local service by specifying the identifier of the ticketing service to be executed, the name of the target local reader, and transmitting to the server if necessary the contents of the previously read smart card or additional information.

Reader Server Side

This usage mode allows a client application to control a smart card reader or a pool of smart card readers available on a server (e.g. SAM reader, HSM).

The Keyple Distributed solution offers for this usage mode a remote control of all types of plugins (Plugin, ObservablePlugin, PoolPlugin):

• Regular plugin (Plugin or ObservablePlugin)

During the remote plugin registration process, the client automatically creates a remote reader for each local reader of the set of local plugins on the server.

If the factory has been properly configured, then the remote plugin and reader behave like the local plugins and readers.

It is then possible to observe directly from the client the plugin and/or reader events (reader connection/disconnection or card insertion/removal) if desired.

The table below shows the classes and interfaces available for this usage mode in the case of a regular plugin.
Interfaces marked with an asterisk “*” come from the Keypop Reader API.
Interfaces marked with an asterisk “**” come from the Keyple Service API:

• Pool plugin (PoolPlugin)

The dynamic reader allocation process will search for the first available reader among all or a subset of the pool plugins registered on the server.

It is possible to define during the configuration phase of the local service factory a filter on the names of the pool plugins to use.

The table below shows the classes and interfaces available for this usage mode in the case of a pool plugin.
Interfaces marked with an asterisk “*” come from the Keypop Reader API.
Interfaces marked with an asterisk “**” come from the Keyple Service API:

OPERATING MODE

• Server
  1. Build an instance of the LocalServiceServerFactory using the LocalServiceServerFactoryBuilder class, specifying a unique name for the Local Service to be registered and your network endpoint implementation if required.
  2. Register the Local Service to the smart card service by providing the previously built factory.
  3. Register at least a local plugin or pool plugin to the smart card service, depending on your case.
• Client
  1. Build an instance of the RemotePluginClientFactory using the RemotePluginClientFactoryBuilder or RemotePoolPluginClientFactoryBuilder class depends on the type of plugin that you want to manage, specifying a unique name for the Remote Plugin to be registered and your network endpoint implementation.
  2. Register the Remote Plugin to the smart card service by providing the previously built factory.
  3. Use the registered remote plugin as a local plugin.

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:

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 communication with several server instances.

API

• Local API
• Network API
• Remote API

Examples

• Java examples

Download

• Java components