Package org.eclipse.keypop.reader.selection

Interface CardSelectionManager

public interface CardSelectionManager
Service dedicated to card selection, based on the preparation of a card selection scenario.

A card selection scenario consists of one or more selection cases based on a CardSelectionExtension.
A card selection case targets a specific card.
Optionally, additional commands can be defined to be executed after the successful selection of the card.

If a card selection case fails, the service will try with the next card selection case defined in the scenario, until there are no further card selection cases available.

If a card selection case succeeds:

  • By default, the service stops at the first successful card selection.
  • If the multiple selection mode is set (disabled by default), the service will execute the next selection. This multiple selection mode force the execution of all card selection cases defined in the scenario. This method can be enabled using the setMultipleSelectionMode() method

The logical channel established with the card can be left open (default) or closed after card selection (by using the prepareReleaseChannel() method).

This service allows to:

  • Prepare the card selection scenario.
  • Make an explicit selection of a card (when the card is already present).
  • Schedule the execution of the selection as soon as a card is presented to an observable reader.
An instance of this interface can be obtained via the method ReaderApiFactory.createCardSelectionManager().
Since:
1.0.0

  • Method Details

    • setMultipleSelectionMode

      void setMultipleSelectionMode()
      Sets the multiple selection mode to process all selection cases even in case of a successful selection.

      The multiple selection mode is disabled by default.

      Since:
      1.0.0

    • prepareSelection

      int prepareSelection(CardSelector<?> cardSelector, CardSelectionExtension cardSelectionExtension)
      Appends a card selection case to the card selection scenario.

      The method returns the index giving the current position of the selection in the selection scenario (0 for the first application, 1 for the second, etc.). This index will be used to retrieve the corresponding result in the CardSelectionResult object.

      Parameters:
      cardSelector - The card selector containing the filters to be used to select the card.
      cardSelectionExtension - The card selection extension to be used to parse the card selection response.
      Returns:
      A non-negative int.
      Throws:
      IllegalArgumentException - If the provided card selector or card selection extension is null.
      Since:
      2.0.0

    • prepareReleaseChannel

      void prepareReleaseChannel()
      Requests the closing of the physical channel at the end of the execution of the card selection request.

      It is thus possible to chain several selections on the same card selection scenario by restarting the card connection sequence.

      Since:
      1.0.0

    • exportCardSelectionScenario

      String exportCardSelectionScenario()
      Exports the content of the current prepared card selection scenario in string format.

      This string can be imported into the same or another card selection manager via the method importCardSelectionScenario(String).

      Returns:
      A non-null string.
      Since:
      1.1.0
      See Also:

    • importCardSelectionScenario

      int importCardSelectionScenario(String cardSelectionScenario)
      Imports a previously exported card selection scenario in string format.

      Prerequisite: the string must have been exported from a card selection manager via the method exportCardSelectionScenario().

      Parameters:
      cardSelectionScenario - The string containing the exported card selection scenario.
      Returns:
      The index of the last imported selection in the card selection scenario.
      Throws:
      IllegalArgumentException - If the string is null or malformed.
      Since:
      1.1.0
      See Also:

    • processCardSelectionScenario

      CardSelectionResult processCardSelectionScenario(CardReader reader)
      Explicitly executes a previously prepared card selection scenario and returns the card selection result.
      Parameters:
      reader - The reader to communicate with the card.
      Returns:
      A non-null reference.
      Throws:
      IllegalArgumentException - If the provided reader is null.
      ReaderCommunicationException - If the communication with the reader has failed.
      CardCommunicationException - If communication with the card has failed or if the status word check is enabled in the card request and the card has returned an unexpected code.
      InvalidCardResponseException - If the card returned invalid data during the selection process.
      Since:
      1.0.0

    • scheduleCardSelectionScenario

      void scheduleCardSelectionScenario(ObservableCardReader observableCardReader, ObservableCardReader.NotificationMode notificationMode)
      Schedules the execution of the prepared card selection scenario as soon as a card is presented to the provided ObservableCardReader.

      CardReaderEvent are pushed to the observer according to the specified notification mode.

      The result of the scenario execution will be analyzed by parseScheduledCardSelectionsResponse(ScheduledCardSelectionsResponse).

      Parameters:
      observableCardReader - The reader with which the card communication is carried out.
      notificationMode - The card notification mode to use when a card is detected.
      Throws:
      IllegalArgumentException - If one of the parameters is null.
      Since:
      1.0.0

    • parseScheduledCardSelectionsResponse

      CardSelectionResult parseScheduledCardSelectionsResponse(ScheduledCardSelectionsResponse scheduledCardSelectionsResponse)
      Analyzes the responses provided by a CardReaderEvent following the insertion of a card and the execution of the card selection scenario.
      Parameters:
      scheduledCardSelectionsResponse - The card selection scenario execution response.
      Returns:
      A non-null reference.
      Throws:
      IllegalArgumentException - If the provided card selection response is null.
      InvalidCardResponseException - If the data returned by the card could not be interpreted.
      Since:
      1.0.0

    • exportProcessedCardSelectionScenario

      String exportProcessedCardSelectionScenario()
      Exports the content of the previously processed card selection scenario in string format.

      This string can be imported into the same or another card selection manager via the method importProcessedCardSelectionScenario(String).

      Prerequisite: the card selection scenario must first have been processed via the processCardSelectionScenario(CardReader) or parseScheduledCardSelectionsResponse(ScheduledCardSelectionsResponse) method.

      Caution: if the local environment does not have the card extensions involved in the selection scenario, then methods processCardSelectionScenario(CardReader) and parseScheduledCardSelectionsResponse(ScheduledCardSelectionsResponse) will not be able to interpret the content of the result, and consequently, the content of the result object CardSelectionResult will not contain any active selection. It will then be necessary to export the processed scenario in order to import it and interpret it correctly by a card selection manager that has all the card extensions involved in the selection scenario.

      Returns:
      A non-null string.
      Throws:
      IllegalStateException - If the card selection scenario has not yet been processed or has failed.
      Since:
      1.3.0
      See Also:

    • importProcessedCardSelectionScenario

      CardSelectionResult importProcessedCardSelectionScenario(String processedCardSelectionScenario)
      Imports a previously exported processed card selection scenario in string format and returns the card selection result.

      Prerequisites:

      • the string must have been exported from a card selection manager via the method exportProcessedCardSelectionScenario(),
      • the local environment must have the card extensions involved in the card selection scenario,
      • the current manager must first be configured with the same card selection scenario as the manager that was used to export the processed card selection scenario.
      Parameters:
      processedCardSelectionScenario - The string containing the exported processed card selection scenario.
      Returns:
      A non-null reference.
      Throws:
      IllegalArgumentException - If the string is null, malformed or contains more card selection cases than the current card selection scenario.
      InvalidCardResponseException - If the data returned by the card could not be interpreted.
      Since:
      1.3.0
      See Also: