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:

• 1.0.0 to 2.0.0

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());
...
((ObservableCardReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableCardReader) reader).addObserver(new CardReaderObserver());

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

((ConfigurableCardReader) reader).activateProtocol(
    PcscSupportedContactlessProtocols.ISO_14443_4.name(), 
    CARD_ISO_14443_4);

Use of plugin and reader extensions for specific configurations

• 1.0.0

reader
    .setContactless(true)
    .setIsoProtocol(PcscReader.IsoProtocol.T1);

• 2.0.0

plugin.getReaderExtension(PcscReader.class, reader.getName())
    .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();

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

Explicit card selection

• 1.0.0

CardSelectionsResult selectionResult = cardSelectionsService.processExplicitSelections(reader);

• 2.0.0

CardSelectionResult selectionResult = cardSelectionManager.processCardSelectionScenario(reader);

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(
    (ObservableCardReader) reader,
    ObservableCardReader.DetectionMode.REPEATING,
    ObservableCardReader.NotificationMode.MATCHED_ONLY);
((ObservableCardReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableCardReader) reader).addObserver(new CardReaderObserver());

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();

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());

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