Package org.calypsonet.terminal.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 CardSelection.
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.

Since:

1.0.0

Method Summary

Modifier and Type	Method	Description
java.lang.String	exportCardSelectionScenario()	Exports the current prepared card selection scenario to a string in JSON format.
int	importCardSelectionScenario(java.lang.String cardSelectionScenario)	Imports a card selection scenario provided as a string in JSON format.
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.
void	prepareReleaseChannel()	Requests the closing of the physical channel at the end of the execution of the card selection request.
int	prepareSelection(CardSelection cardSelection)	Appends a card selection case to the card selection scenario.
CardSelectionResult	processCardSelectionScenario(CardReader reader)	Explicitly executes a previously prepared card selection scenario and returns the card selection result.
void	scheduleCardSelectionScenario(ObservableCardReader observableCardReader, ObservableCardReader.DetectionMode detectionMode, ObservableCardReader.NotificationMode notificationMode)	Schedules the execution of the prepared card selection scenario as soon as a card is presented to the provided ObservableCardReader.
void	setMultipleSelectionMode()	Sets the multiple selection mode to process all selection cases even in case of a successful selection.

Method Detail

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(CardSelection cardSelection)

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:

cardSelection - The card selection.

Returns:

A non-negative int.

Throws:

java.lang.IllegalArgumentException - If the provided card selection is null.

Since:

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

java.lang.String exportCardSelectionScenario()

Exports the current prepared card selection scenario to a string in JSON format.

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

Returns:

A not null JSON string.

Since:

1.1.0

See Also:

importCardSelectionScenario(String)

importCardSelectionScenario

int importCardSelectionScenario(java.lang.String cardSelectionScenario)

Imports a card selection scenario provided as a string in JSON format.

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

Parameters:

cardSelectionScenario - The string in JSON format containing the card selection scenario.

Returns:

The index of the last imported selection in the card selection scenario.

Throws:

java.lang.IllegalArgumentException - If the string is null or malformed.

Since:

1.1.0

See Also:

exportCardSelectionScenario()

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:

java.lang.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.DetectionMode detectionMode,
                                   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 reader's behavior at the end of the card processing is defined by the specified ObservableCardReader.DetectionMode.

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

Parameters:

observableCardReader - The reader with which the card communication is carried out.

detectionMode - The card detection mode to use when searching for a card.

notificationMode - The card notification mode to use when a card is detected.

Throws:

java.lang.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:

java.lang.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