org.eclipse.keyple.core.plugin

Class AbstractObservableLocalReader

java.lang.Object

org.eclipse.keyple.core.plugin.AbstractReader

org.eclipse.keyple.core.plugin.AbstractLocalReader

org.eclipse.keyple.core.plugin.AbstractObservableLocalReader

All Implemented Interfaces:

ProxyReader, ObservableReaderNotifier, ObservableReader, Reader

Direct Known Subclasses:

AbstractObservableLocalAutonomousReader

public abstract class AbstractObservableLocalReader
extends AbstractLocalReader
implements ObservableReaderNotifier

Extends AbstractLocalReader to manage the observation of card events.

It provides the means to configure the reader's behavior when a card is detected.

The event management implements a ObservableReaderStateService state machine that is composed of four states.

1. WAIT_FOR_START_DETECTION

   Infinitely waiting for a signal from the application to start card detection by changing to WAIT_FOR_SE_INSERTION state. This signal is given by calling the setDefaultSelectionRequest method.

   Note: The system always starts in the WAIT_FOR_START_DETECTION state.

2. WAIT_FOR_SE_INSERTION

   Awaiting the card insertion. After insertion, the processCardInserted method is called.

   A number of cases arise:

   • A default selection is defined: in this case it is played and its result leads to an event notification CARD_INSERTED or CARD_MATCHED or no event (see setDefaultSelectionRequest)
   • There is no default selection: a CARD_INSERTED event is then notified.

     In the case where an event has been notified to the application, the state machine changes to the WAIT_FOR_SE_PROCESSING state otherwise it remains in the WAIT_FOR_SE_INSERTION state.

   The notification consists in calling the "update" methods of the defined observers. In the case where several observers have been defined, it is up to the application developer to ensure that there is no long processing in these methods, by making their execution asynchronous for example.

3. WAIT_FOR_SE_PROCESSING

   Waiting for the end of processing by the application. The end signal is triggered by a transmission made with a CLOSE_AFTER parameter.

   If the instruction given when defining the default selection request is to stop (ObservableReader.PollingMode.SINGLESHOT) then the logical and physical channels are closed immediately and the machine state changes to WAIT_FOR_START_DETECTION state.

   If the instruction given is continue (ObservableReader.PollingMode.REPEATING) then the state machine changes to WAIT_FOR_SE_REMOVAL.

4. WAIT_FOR_SE_REMOVAL:

   Waiting for the card to be removed. When the card is removed, a CARD_REMOVED event is notified to the application and the state machine changes to the WAIT_FOR_SE_INSERTION or WAIT_FOR_START_DETECTION state according the polling mode (ObservableReader.PollingMode).

Since:

0.9

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstractObservableLocalReader.InternalEvent Internal events

Nested classes/interfaces inherited from interface org.eclipse.keyple.core.service.event.ObservableReader

ObservableReader.NotificationMode, ObservableReader.PollingMode, ObservableReader.ReaderObserver

Field Summary

Fields

Modifier and Type	Field and Description
protected org.eclipse.keyple.core.plugin.ObservableReaderStateService	stateService

Fields inherited from class org.eclipse.keyple.core.plugin.AbstractReader

isRegistered

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractObservableLocalReader(java.lang.String pluginName, java.lang.String readerName) (protected) Constructor.

Method Summary

Modifier and Type	Method and Description
void	addObserver(ObservableReader.ReaderObserver observer) Add a ObservableReader.ReaderObserver.
void	clearObservers() Remove all observers at once
int	countObservers() Gets the number of observers.
void	finalizeCardProcessing() Terminates the processing of the card, in particular after an interruption by exception Do nothing if the channel is already closed. Channel closing is nominally managed by using the ChannelControl.CLOSE_AFTER flag during the last transmission with the card.
protected abstract ReaderObservationExceptionHandler	getObservationExceptionHandler() Allows to call the defined handler when an exception condition needs to be transmitted to the application level.
boolean	isCardPresent() Check the presence of a card
void	notifyObservers(ReaderEvent event) Notify all registered observers with the provided ReaderEvent
protected abstract void	onStartDetection() Method called when the card detection is started by the Keyple Plugin
protected abstract void	onStopDetection() Method called when the card detection is stopped by the Keyple Plugin
void	removeObserver(ObservableReader.ReaderObserver observer) Remove a ObservableReader.ReaderObserver.
void	setDefaultSelectionRequest(AbstractDefaultSelectionsRequest defaultSelectionsRequest, ObservableReader.NotificationMode notificationMode) If defined, the prepared DefaultSelectionRequest will be processed as soon as a card is inserted.
void	setDefaultSelectionRequest(AbstractDefaultSelectionsRequest defaultSelectionsRequest, ObservableReader.NotificationMode notificationMode, ObservableReader.PollingMode pollingMode) A combination of defining the default selection request and starting the card detection.
void	startCardDetection(ObservableReader.PollingMode pollingMode) Starts the card detection.
void	stopCardDetection() Stops the card detection.
protected void	unregister() (package-private) Change the reader status to unregistered

Methods inherited from class org.eclipse.keyple.core.plugin.AbstractLocalReader

activateProtocol, activateReaderProtocol, checkCardPresence, closePhysicalChannel, deactivateProtocol, deactivateReaderProtocol, getATR, isCurrentProtocol, isPhysicalChannelOpen, openPhysicalChannel, processCardRequest, processCardSelectionRequests, releaseChannel, transmitApdu

Methods inherited from class org.eclipse.keyple.core.plugin.AbstractReader

getName, getPluginName, transmitCardRequest, transmitCardSelectionRequests

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.keyple.core.service.Reader

activateProtocol, deactivateProtocol, getName, isContactless

Field Detail

stateService

protected final org.eclipse.keyple.core.plugin.ObservableReaderStateService stateService

Constructor Detail

AbstractObservableLocalReader

protected AbstractObservableLocalReader(java.lang.String pluginName,
                                        java.lang.String readerName)

(protected)
Constructor.

Force the definition of a name through the use of super method.

Initialize the ObservableReaderStateService with the possible states and their implementation. ObservableReaderStateService define the initial state.

Parameters:

pluginName - the name of the plugin that instantiated the reader

readerName - the name of the reader

Since:

0.9

Method Detail

onStartDetection

protected abstract void onStartDetection()

Method called when the card detection is started by the Keyple Plugin

onStopDetection

protected abstract void onStopDetection()

Method called when the card detection is stopped by the Keyple Plugin

addObserver

public final void addObserver(ObservableReader.ReaderObserver observer)

Add a ObservableReader.ReaderObserver.

The observer will receive all the events produced by this reader (card insertion, removal, etc.)

Specified by:

addObserver in interface ObservableReader

Parameters:

observer - the observer object

Throws:

java.lang.IllegalStateException - If observer is null or no PluginObservationExceptionHandler has been set.

Since:

0.9

removeObserver

public final void removeObserver(ObservableReader.ReaderObserver observer)

Remove a ObservableReader.ReaderObserver.

The observer will do not receive any of the events produced by this reader.

Specified by:

removeObserver in interface ObservableReader

Parameters:

observer - the observer object

Since:

0.9

notifyObservers

public final void notifyObservers(ReaderEvent event)

Notify all registered observers with the provided ReaderEvent

Specified by:

notifyObservers in interface ObservableReaderNotifier

Parameters:

event - the reader event

Since:

0.9

countObservers

public final int countObservers()

Gets the number of observers.

Specified by:

countObservers in interface ObservableReader

Returns:

An int

Since:

0.9

clearObservers

public final void clearObservers()

Remove all observers at once

Specified by:

clearObservers in interface ObservableReader

isCardPresent

public final boolean isCardPresent()

Check the presence of a card

This method is recommended for non-observable readers.

When the card is not present the logical and physical channels status may be refreshed through a call to the processCardRemoved method.

Specified by:

isCardPresent in interface Reader

Overrides:

isCardPresent in class AbstractLocalReader

Returns:

true if the card is present

Throws:

KeypleReaderIOException - if the communication with the reader or the card has failed

java.lang.IllegalStateException - is called when reader is no longer registered

startCardDetection

public final void startCardDetection(ObservableReader.PollingMode pollingMode)

Starts the card detection. Once activated, the application can be notified of the arrival of a card.

This method must be overloaded by readers depending on the particularity of their management of the start of the card detection.

Note: they must call the super method with the argument PollingMode.

Specified by:

startCardDetection in interface ObservableReader

Parameters:

pollingMode - indicates the action to be followed after processing the card: if REPEATING, the card detection is restarted, if SINGLESHOT, the card detection is stopped until a new call to startCardDetection is made.

stopCardDetection

public final void stopCardDetection()

Stops the card detection.

This method must be overloaded by readers depending on the particularity of their management of the start of card detection.

Specified by:

stopCardDetection in interface ObservableReader

setDefaultSelectionRequest

public final void setDefaultSelectionRequest(AbstractDefaultSelectionsRequest defaultSelectionsRequest,
                                             ObservableReader.NotificationMode notificationMode)

If defined, the prepared DefaultSelectionRequest will be processed as soon as a card is inserted. The result of this request set will be added to the reader event notified to the application.

If it is not defined (set to null), a simple card detection will be notified in the end.

Depending on the notification mode, the observer will be notified whenever a card is inserted, regardless of the selection status, or only if the current card matches the selection criteria.

Specified by:

setDefaultSelectionRequest in interface ObservableReader

Parameters:

defaultSelectionsRequest - the AbstractDefaultSelectionsRequest to be executed when a card is inserted

notificationMode - the notification mode enum (ALWAYS or MATCHED_ONLY)

setDefaultSelectionRequest

public final void setDefaultSelectionRequest(AbstractDefaultSelectionsRequest defaultSelectionsRequest,
                                             ObservableReader.NotificationMode notificationMode,
                                             ObservableReader.PollingMode pollingMode)

A combination of defining the default selection request and starting the card detection.

Specified by:

setDefaultSelectionRequest in interface ObservableReader

Parameters:

defaultSelectionsRequest - the selection request to be operated

notificationMode - indicates whether a CARD_INSERTED event should be notified even if the selection has failed (ALWAYS) or whether the card insertion should be ignored in this case (MATCHED_ONLY).

pollingMode - indicates the action to be followed after processing the card: if CONTINUE, the card detection is restarted, if STOP, the card detection is stopped until a new call to startCardDetection is made.

finalizeCardProcessing

public final void finalizeCardProcessing()

Terminates the processing of the card, in particular after an interruption by exception
Do nothing if the channel is already closed.
Channel closing is nominally managed by using the ChannelControl.CLOSE_AFTER flag during the last transmission with the card. However, there are cases where exchanges with the card are interrupted by an exception, in which case it is necessary to explicitly close the channel using this method.

Specified by:

finalizeCardProcessing in interface ObservableReader

Since:

0.9

unregister

protected void unregister()

(package-private)
Change the reader status to unregistered

This method may be overridden in order to meet specific needs in certain implementations of readers.

Notifies all observers of the UNREGISTERED event.
Stops the card detection unconditionally.
Shuts down the reader's executor service.

getObservationExceptionHandler

protected abstract ReaderObservationExceptionHandler getObservationExceptionHandler()

Allows to call the defined handler when an exception condition needs to be transmitted to the application level.

Returns:

A not null reference to an object implementing the PluginObservationExceptionHandler interface.