Upgrade from an earlier version of Keyple


This guide is intended to help a user of a previous version of Keyple Java to upgrade his application to a new version of the library.

Upgrade from:


Upgrade from “1.0.0” to “2.0.0”

Here is a comparative review of the main API changes between Keyple 1.0.0 and 2.0.0:

Dependency management

Use the configuration wizard to correctly import the new artifacts into your project.

Initial configuration

Use of a provider to access the smart card service

  • 1.0.0
SmartCardService smartCardService = SmartCardService.getInstance();
  • 2.0.0
SmartCardService smartCardService = SmartCardServiceProvider.getService();

Use of builders to instantiate plugin factories

  • 1.0.0
Plugin plugin = smartCardService.registerPlugin(new PcscPluginFactory(null, new ExceptionHandlerImpl()));
...
((ObservableReader) reader).addObserver(new CardReaderObserver());
  • 2.0.0
Plugin plugin = smartCardService.registerPlugin(PcscPluginFactoryBuilder.builder().build());
...
((ObservableReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableReader) reader).addObserver(new CardReaderObserver());
Exception handlers are no longer required when registering the plugin but only when starting the observation.

Use of a new interface dedicated to the management of protocols

  • 1.0.0
reader.activateProtocol(
    PcscSupportedContactlessProtocols.ISO_14443_4.name(), 
    ContactlessCardCommonProtocols.ISO_14443_4.name());
  • 2.0.0
((ConfigurableReader) reader).activateProtocol(
    PcscSupportedContactlessProtocols.ISO_14443_4.name(), 
    ContactlessCardCommonProtocols.ISO_14443_4.name());

Use of plugin and reader extensions for specific configurations

The examples below show the evolutions for the configuration of a PC/SC reader but the principle is the same for all plugins and readers.
  • 1.0.0
reader
    .setContactless(true)
    .setIsoProtocol(PcscReader.IsoProtocol.T1);
  • 2.0.0
reader.getExtension(PcscReader.class)
    .setContactless(true)
    .setIsoProtocol(PcscReader.IsoProtocol.T1);

Card selection

Use a manager instead of service for card selection

  • 1.0.0
CardSelectionsService cardSelectionsService = new CardSelectionsService();
  • 2.0.0
CardSelectionManager cardSelectionManager = smartCardService.createCardSelectionManager();
A new instance of the card selection manager is provided by the smart card service.

Use of a card extension to create a card selection

  • 1.0.0
GenericCardSelectionRequest genericCardSelectionRequest =
    new GenericCardSelectionRequest(
        CardSelector.builder()
            .aidSelector(CardSelector.AidSelector.builder().aidToSelect(cardAid).build())
            .build());
  • 2.0.0
CardSelection cardSelection = GenericExtensionService.getInstance()
    .createCardSelection()
    .filterByDfName(cardAid);
  • The CardSelector class does not exist anymore.
  • A generic card extension is now available.
  • The card extension service is used to configure the card selection.

Explicit card selection

  • 1.0.0
CardSelectionsResult selectionResult = cardSelectionsService.processExplicitSelections(reader);
  • 2.0.0
CardSelectionResult selectionResult = cardSelectionManager.processCardSelectionScenario(reader);
Note the removal of the “s” in CardSelectionResult.

Scheduled card selection

  • 1.0.0
((ObservableReader) reader)
    .setDefaultSelectionRequest(
        defaultSelectionsRequest,
        ObservableReader.NotificationMode.MATCHED_ONLY,
        ObservableReader.PollingMode.REPEATING);
((ObservableReader) reader).addObserver(new CardReaderObserver());
  • 2.0.0
cardSelectionManager.scheduleCardSelectionScenario(
    (ObservableReader) reader,
    ObservableReader.DetectionMode.REPEATING,
    ObservableReader.NotificationMode.MATCHED_ONLY);
((ObservableReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableReader) reader).addObserver(new CardReaderObserver());
The selection data is no longer provided to the observable reader but to the selection manager. It is the observable reader that is provided to the selection manager.

The processing of the result of the selection response has changed

  • 1.0.0
AbstractSmartCard smartCard =
  defaultSelection
      .processDefaultSelectionsResponse(event.getDefaultSelectionsResponse())
      .getActiveSmartCard();
  • 2.0.0
SmartCard smartCard =
    cardSelectionManager
        .parseScheduledCardSelectionsResponse(event.getScheduledCardSelectionsResponse())
        .getActiveSmartCard();
AbstractSmartCard was changed to the SmartCard interface.

Calypso Card Extension

Vocabulary

  • PO has been replaced by Card.

SAM management

The SAM resource manager has been replaced by a generic Card Resource Service.

Card transaction

Access to the card transaction manager has changed. It is now done through the card extension service.

  • 1.0.0
PoTransaction poTransaction =
    new PoTransaction(
        new CardResource<CalypsoPo>(poReader, calypsoPo),
        CalypsoUtils.getSecuritySettings(samResource));
  • 2.0.0
CardTransactionManager transactionManager = CalypsoExtensionService.getInstance()
    .createCardTransaction(cardReader, calypsoCard, cardSecuritySetting);

Distributed systems

Remote plugin registration

  • 1.0.0
// Init the remote plugin factory.
RemotePluginServerFactory factory =
    RemotePluginServerFactory.builder()
        .withDefaultPluginName()
        .withSyncNode()
        .withPluginObserver(new RemotePluginServerObserver())
        .usingEventNotificationPool(
            Executors.newCachedThreadPool(r -> new Thread(r, "server-pool")))
        .build();

// Register the remote plugin to the smart card service using the factory.
SmartCardService.getInstance().registerPlugin(factory);
  • 2.0.0
RemotePluginServerFactory factory =
    RemotePluginServerFactoryBuilder.builder(REMOTE_PLUGIN_NAME)
        .withSyncNode()
        .build();

// Register the remote plugin to the smart card service using the factory.
ObservablePlugin plugin =
    (ObservablePlugin) SmartCardServiceProvider.getService().registerPlugin(factory);

// Init the remote plugin observer.
plugin.setPluginObservationExceptionHandler(new ExceptionHandlerImpl());
plugin.addObserver(new RemotePluginServerObserver());
  • You have to specify the name of the plugin.
  • It is no longer necessary to provide a thread pool.
  • The exception handler must be provided as for any observable plugin before adding an observer.

Local service registration

  • 1.0.0
// Init the local service using the associated factory.
LocalServiceClientFactory.builder()
    .withDefaultServiceName()
    .withSyncNode(endpointClient)
    .withoutReaderObservation()
    .getService();
  • 2.0.0
// Init the local service factory.
LocalServiceClientFactory factory =
    LocalServiceClientFactoryBuilder.builder(LOCAL_SERVICE_NAME)
        .withSyncNode(endpointClient)
        .build();

// Init the local service using the associated factory.
SmartCardServiceProvider.getService().registerDistributedLocalService(factory);
  • You have to specify the name of the local service.
  • The local service must be registered with the smart card service.
  • It behaves like a plugin or reader and also provides an extension to access specific settings.
Previous