javax.microedition.contactless
Class DiscoveryManager

java.lang.Object
  DiscoveryManager

public class DiscoveryManager
extends java.lang.Object

The DiscoveryManager class offers the mechanism to discover targets for contactless communication. It is the starting point for the application using the Contactless Communication API. This class also manages the different listeners in this API.

This class also provides a method to query contactless targets supported by the API implementation. Method getSupportedTargetTypes() returns the list of supported contactless targets. All the targets that can be accessed through this API are specified in the TargetType class.

TargetListener is used to request a notification for a specific contactless TargetType the application is interested in. NDEFRecordListener provides a notification about specific NDEF record type that is in the read from the NFC Forum compliant tag.

Inside a Java virtual machine, there must be at most one TargetListener for each TargetType. The restriction for one TargetListener is needed, because the RFID hardware is able to handle only one connection to the physical target at a time. The registration of TargetListener should fail, if there is an existing listener in other virtual machines or in the native platform. The addTargetListener(listener, targetType) method throws an exception, if there is an existing listener defined. The existing listener may be a native application.

The API implementation may restrict the number of simultaneous listeners set for one NDEF record type. The reason for the restiction may be usability or hardware restrictions. The addNDEFRecordListener(listener, recordType) method throws an exception if the maximum number of registered listeners for an NDEF record type is exceeded. On the MIDP 2.0 platform the PushRegistry entry for an NDEF record type in a MIDlet that is not executing increases the number of registered listeners by one. More information about PushRegistry in the Appendix B: Launching applications with MIDP 2.0 PushRegistry.

An application can get information about NDEF formatted data on a NDEF tag target through both TargetListener and NDEFRecordListener. If the application wants to write data to the tag, it must register TargetListener. If the application is only interested in the data in specified record type on the tag, it should register NDEFRecordListener for that record type. The data provided in the NDEFRecordListener notification is read-only and the application has no access to the target after receiving this notification. One application may set both of these listeners at the same time. In this case the application has to be aware that the notifications may arrive almost simultaneously and to design the application accordingly. Applications should not register listeners for targets or for NDEF records it is not interested in.

The following diagram depicts the relationships of the two listeners that the application can register for NDEF_TAG target. Diagram also specifies the order in which the notifications must be sent.

Once the TargetType.NDEF_TAG target is discovered the API implementation must read the first NDEF record on the target. After that the implementation checks the TargetListener set for NDEF_TAG target. If the listener is registered, the targetDetected notification must be sent to the registered application. If there is not a registered TargetListener for NDEF_TAG, the implementation must check if there is a registered listener for the physical type of the target. Each NDEF_TAG is also either RFID_TAG or ISO14443_CARD on the physical level. If the physical level target has a registered TargetListener, the targetDetected notification must be sent to that application.

If the target has a first NDEF record and is not empty, the API implementation must handle the NDEFRecordListener registrations. If an application has a PushRegistry entry for this NDEF record type, the system must start that application. If the first NDEF record has one or more listeners registered, NDEFRecordListener.recordDetected notification must be sent to the registered application.

TransactionListener provides a notification about the communication between an external reader device and the secure element on the device through the RFID hardware to the application. Support for the detection of the possible transactions depends on the underlying platform and of the RFID reader hardware. If the API implementation can not support this feature, the registration of the TransactionListener must throw an exception.

The implementation of this class must maintain the information about registered listeners. When an application registers a listener of any kind, the API implementation must send this notification right away if there is a corresponding target currently in the interrogation field.

Even if multiple requested targets are available in the proximity of the device, only one TargetListener.targetDetected notification is sent to the application. This notification must contain the properties of the new targets in the interrogation field, always properties of at least one target. The notification may contain properties of all the targets in the field.

Method Summary

void	addNDEFRecordListener(NDEFRecordListener listener, NDEFRecordType recordType) Adds NDEFRecordListener for the specified NDEF record type.
void	addTargetListener(TargetListener listener, TargetType targetType) Adds TargetListener for specified TargetType to receive a notification, when the requested type of target is available in the proximity of the device.
void	addTransactionListener(TransactionListener listener) Adds a TransactionListener to receive a notification of the possible transactions happening between the RFID hardware and the secure element on the device.
static DiscoveryManager	getInstance() This factory method is used to retrieve the instance of this Singleton class.
java.lang.String	getProperty(java.lang.String name) With this method the application can query the properties related to the target discovery.
static TargetType[]	getSupportedTargetTypes() Returns the list of target types supported by the API implementation.
void	removeNDEFRecordListener(NDEFRecordListener listener, NDEFRecordType recordType) Removes the NDEFRecordListener from the specified NDEF record type.
void	removeTargetListener(TargetListener listener, TargetType targetType) Removes the TargetListener from the specified TargetType.
void	removeTransactionListener(TransactionListener listener) Removes the specified TransactionListener.
void	setProperty(java.lang.String name, java.lang.String value) Allows the application to set a property related to the target discovery.

Methods inherited from class java.lang.Object

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

Method Detail

addNDEFRecordListener

public void addNDEFRecordListener(NDEFRecordListener listener,
                                  NDEFRecordType recordType)
                           throws ContactlessException

Adds NDEFRecordListener for the specified NDEF record type. Setting a listener for a NDEF record type that already has the maximum number of listeners registered, will cause an IllegalStateException to be thrown.

The registration of new NDEFRecordListener must throw an IllegalStateException if the maximum number of registered listeners is exceeded. If the registering application has a PushRegistry entry for the specified NDEF record type, the listener registration must be successful.

Parameters:

listener - listener to be added

recordType - NDEF record type the application is interested in

Throws:

java.lang.IllegalStateException - if NDEFRecordListener for the NDEF record has already been maximum number of listeners registered

java.lang.NullPointerException - if listener or recordType is null

ContactlessException - if NDEF_TAG target is not supported by the API implementation

addTargetListener

public void addTargetListener(TargetListener listener,
                              TargetType targetType)
                       throws ContactlessException,
                              java.lang.IllegalStateException

Adds TargetListener for specified TargetType to receive a notification, when the requested type of target is available in the proximity of the device. One TargetListener for each TargetType is allowed. Setting a listener for a target type that already has a registered TargetListener, will cause an IllegalStateException to be thrown. The existing listener may be a native application.

Parameters:

listener - listener to be added

targetType - contactless target the application is interested in

Throws:

ContactlessException - if targetType is not supported by the API implementation

java.lang.IllegalStateException - if TargetListener for the targetType has already been registered

java.lang.NullPointerException - if listener or targetType is null

addTransactionListener

public void addTransactionListener(TransactionListener listener)
                            throws ContactlessException

Adds a TransactionListener to receive a notification of the possible transactions happening between the RFID hardware and the secure element on the device. This transaction happens when an external reader device is accessing secure element on the device through the RFID hardware. If this feature cannot be supported a ContactlessException must be thrown when trying to register this listener. Multiple listeners are allowed and the notification must be sent to all of them.

Parameters:

listener - listener to be added

Throws:

java.lang.NullPointerException - if listener is null

ContactlessException - if ISO14443_CARD target is not supported or if the API implementation can not support this feature

getInstance

public static DiscoveryManager getInstance()

This factory method is used to retrieve the instance of this Singleton class. Permission needed to instantiate this class can be found from Appendix A: Security.

Returns:

the instance of the class

Throws:

java.lang.SecurityException - if the application does not have the permission to instantiate this class

getProperty

public java.lang.String getProperty(java.lang.String name)

With this method the application can query the properties related to the target discovery. The property can be, for example, the speed to be used in the communication. The property name values are implementation dependant and not specified in the API.

Parameters:

name - the name of the property

Returns:

the value of the property, null if the property with the specified name has not been defined

Throws:

java.lang.NullPointerException - if name is null

getSupportedTargetTypes

public static TargetType[] getSupportedTargetTypes()

Returns the list of target types supported by the API implementation. Possible target types are specified in the TargetType class.

Returns:

supported target types

removeNDEFRecordListener

public void removeNDEFRecordListener(NDEFRecordListener listener,
                                     NDEFRecordType recordType)

Removes the NDEFRecordListener from the specified NDEF record type. This method should be used, when the application is not interested in the NDEF record type anymore. If the specified listener and record type pair is not registered, this method returns silently without actions.

Parameters:

listener - listener to be removed

recordType - NDEF record type

Throws:

java.lang.NullPointerException - if listener or recordType is null

removeTargetListener

public void removeTargetListener(TargetListener listener,
                                 TargetType targetType)

Removes the TargetListener from the specified TargetType. This method should be used when the application is not interested in the target anymore. If the listener and target type pair is not registered, this method returns silently without actions.

Parameters:

listener - listener to be removed

targetType - the contactless target

Throws:

java.lang.NullPointerException - if listener or targetType is null

removeTransactionListener

public void removeTransactionListener(TransactionListener listener)

Removes the specified TransactionListener. If the specified listener is not registered, this method returns silently without actions.

Parameters:

listener - listener to be removed

Throws:

java.lang.NullPointerException - if listener is null

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

Allows the application to set a property related to the target discovery. The property can be, for example, the speed to be used in the communication. The name values for these discovery-related properties are implementation dependant and not specified in the API.

Parameters:

name - the name of the property

value - the value for the property

Throws:

java.lang.NullPointerException - if name or value is null

java.lang.IllegalArgumentException - if the property name is not supported by the API implementation or if the value of the property is invalid