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

Keyple on both client and server sides
Keyple on both client and server sides

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

Keyple on server side only
Keyple on server side only

User guides


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:

ConceptDescription
Remote LibThis is the keyple-distributed-remote-java-lib library.
It must be imported and used by the application installed on the host not having local access to the smart card reader and that wishes to control the reader remotely.
Local LibThis is the keyple-distributed-local-java-lib library.
It must be imported and used by the application installed on the host 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 keyple-distributed-network-java-lib library.
It must always be imported because it contains the network elements used by Remote Lib and Local Lib.
Remote PluginPart of the Remote Lib, this is a Keyple reader plugin extension which provides only Remote Readers to the application. It manages data exchanges with the Local Service. This reader plugin extension must be registered to the smart card service like any Keyple reader plugin.
Remote ReaderPart of the Remote Lib, this is a Keyple reader extension 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;
- in some cases only, an event occurring on a local reader or plugin will be automatically forwarded to the associated remote reader or plugin.
Local ServicePart of the Local Lib, this is a Keyple distributed local service extension which ensures data exchange between the Remote Plugin and local plugins and readers. It must be registered to the smart card service.
FactoryRemote Plugin and Local Service each have a specific factory class to initialize them.
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:

Concepts - Main use case
Concepts - Main 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.

Concepts - One remote plugin connected to many local services
Concepts - One remote plugin connected to many local services

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.

Concepts - Many remote plugins connected to one local service
Concepts - Many remote plugins connected to one local service

Usage modes

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

Usage modeDescription
Reader Client SideAllows a server application to control a smart card reader available on a client (e.g. Card reader).
Reader Server SideAllows a client application to control a smart card reader available on a server (e.g. SAM reader, HSM).

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:

APIClientServer
Library to useLocal LibRemote Lib
Factory builder to be usedLocalServiceClientFactoryBuilderRemotePluginServerFactoryBuilder
Factory to be registeredLocalServiceClientFactoryRemotePluginServerFactory
Local Service / Remote PluginDistributedLocalService **ObservablePlugin **
Local Service / Remote Plugin extensionLocalServiceClientRemotePluginServer
ReaderAny kind of readerCardReader *
Reader extensionDevice specificRemoteReaderServer
It is the responsibility of the client application to observe and configure the local plugins and readers.

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:

APIClientServer
Library to useRemote LibLocal Lib
Factory builder to be usedRemotePluginClientFactoryBuilderLocalServiceServerFactoryBuilder
Factory to be registeredRemotePluginClientFactoryLocalServiceServerFactory
Remote Plugin / Local ServicePlugin ** or
ObservablePlugin **
DistributedLocalService **
Remote Plugin / Local Service extensionRemotePluginClientLocalServiceServer
ReaderCardReader * or
ObservableCardReader *
Any kind of reader
Reader extensionRemoteReaderClientDevice specific
  • 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:

APIClientServer
Library to useRemote LibLocal Lib
Factory builder to be usedRemotePoolPluginClientFactoryBuilderLocalServiceServerFactoryBuilder
Factory to be registeredRemotePluginClientFactoryLocalServiceServerFactory
Remote Plugin / Local ServicePoolPlugin **DistributedLocalService **
Remote Plugin / Local Service extensionRemotePluginClientLocalServiceServer
ReaderCardReader *Any kind of reader
Reader extensionRemoteReaderClientDevice specific
Whatever the type of plugin, it is the responsibility of the server application to configure the local plugins and readers.

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.

ClientServer
Network endpoint SPI to be implementedSyncEndpointClientSpi-
Node APISyncNodeClientSyncNodeServer
Method to be used when initializing the factorywithSyncNode(...)withSyncNode(...)
Method provided by the remote plugin or local service extension
to use to access the node
-getSyncNode()

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

Synchronous network implementation
Synchronous network implementation

In a context with several server instances, a mechanism must be implemented to ensure that all messages associated to a functional transaction are routed to the same server instance.

For the Reader Client Side usage mode, the client endpoint can use the value of the sessionId field contained in the MessageDto object transmitted by the Keyple client node to identify transactions. This value is generated for each new execution of a remote service. When the client endpoint detects a new value, it can, for example, transmit the first message without a session cookie in order to be routed to the first available server, then transmit the session cookie returned by the server in subsequent exchanges until a new transaction is detected.

For the Reader Server Side usage mode with pool plugins, if there are several server instances, each reader cycle (from reader allocation to reader release) must be performed on the same server instance. A mechanism must be put in place to inform the client endpoint that a new reader cycle is about to begin because the sessionId field is not relevant here. So, for example, when requested by the Keyple client node, the client endpoint can transmit the first message without a session cookie in order to be routed to the first available server, and then transmit the session cookie returned by the server in subsequent exchanges until the start of a new cycle.

For the Reader Server Side usage mode with regular plugins (non-pool), if several server instances exist, a remote plugin must be created for each server instance, and each remote plugin must be associated with a distinct client endpoint dedicated to a server instance.

Asynchronous

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

ClientServer
Network endpoint SPI to be implementedAsyncEndpointClientSpiAsyncEndpointServerSpi
Node APIAsyncNodeClientAsyncNodeServer
Method to be used when initializing the factorywithAsyncNode(...)withAsyncNode(...)
Method provided by the remote plugin or local service extension
to use to access the node
getAsyncNode()getAsyncNode()

Here is the minimal algorithm to implement:

Asynchronous network implementation
Asynchronous network implementation

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


Examples


Download

Previous
Next