javax.microedition.contactless.ndef
Class NDEFMessage

java.lang.Object
  NDEFMessage

public class NDEFMessage
extends java.lang.Object

This class represents an NDEF message. An NDEF message consists of one or more NDEF records. This class allows the manipulation of the NDEF records inside the NDEF message in the memory. It provides methods to add, remove and update NDEF records in the message. The NFC Forum NDEF specification is used as basis for this class, but some features, for example, chunking defined in the NDEF specification are left to the API implementation. The NDEF message sent to the target must contain at least one NDEF record.

Constructor Summary

NDEFMessage()
Creates an NDEF message that has no NDEF records.

NDEFMessage(byte[] data, int offset)
Creates an NDEF message from the byte array starting from the specified offset in the byte array.

NDEFMessage(NDEFRecord[] records)
Creates an NDEF message containing the specified NDEF records.

Method Summary

void	appendRecord(NDEFRecord record) Adds a new NDEF record after the last NDEF record in the NDEF message.
int	getNumberOfRecords() Returns the number of NDEFRecord objects in the NDEF message.
NDEFRecord	getRecord(byte[] id) Returns the NDEF record with the specified payload identifier.
NDEFRecord	getRecord(int index) Returns the NDEF record from the specified index in the NDEF message.
NDEFRecord[]	getRecord(NDEFRecordType recordType) Returns the NDEF records with specified record type.
NDEFRecord[]	getRecords() Returns all NDEF records in the NDEF message.
NDEFRecordType[]	getRecordTypes() Returns the record type objects of all NDEF records in the NDEF message.
void	insertRecord(int index, NDEFRecord record) Adds the specified NDEF record to the NDEF records at the specified index.
void	removeRecord(int index) Removes an NDEF record from the specified index.
void	setRecord(int index, NDEFRecord record) Replaces the NDEF record at the specified index.
byte[]	toByteArray() Returns the whole NDEF message with all the NDEF records as a byte array.

Methods inherited from class java.lang.Object

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

Constructor Detail

NDEFMessage

public NDEFMessage()

Creates an NDEF message that has no NDEF records.

NDEFMessage

public NDEFMessage(byte[] data,
                   int offset)

Creates an NDEF message from the byte array starting from the specified offset in the byte array. The offset must be a value greater than or equal to 0 and less than the length of the byte array.

Parameters:

data - the byte array containing the NDEF records

offset - start index of the NFC Forum formatted data in the byte array

Throws:

java.lang.NullPointerException - if data is null

java.lang.ArrayIndexOutOfBoundsException - if offset is invalid

java.lang.IllegalArgumentException - if data can not be formed to NDEF message

NDEFMessage

public NDEFMessage(NDEFRecord[] records)

Creates an NDEF message containing the specified NDEF records. The NDEF records are added in the order they are given.

Parameters:

records - NDEF records to be added to the NDEF message

Throws:

java.lang.NullPointerException - if records is null or if any of the given record objects inside the records array is null

java.lang.IllegalArgumentException - if records is an empty array or payload identifiers in the NDEF records are not unique

Method Detail

appendRecord

public void appendRecord(NDEFRecord record)

Adds a new NDEF record after the last NDEF record in the NDEF message. The number of the NDEF records is increased by one.

Parameters:

record - the new NDEF record to be added

Throws:

java.lang.NullPointerException - if record is null

java.lang.IllegalArgumentException - if an NDEF record with the same payload identifier already exists

getNumberOfRecords

public int getNumberOfRecords()

Returns the number of NDEFRecord objects in the NDEF message.

Returns:

number of NDEF records

getRecord

public NDEFRecord getRecord(byte[] id)

Returns the NDEF record with the specified payload identifier.

Parameters:

id - payload identifier of the requested NDEF record

Returns:

the NDEF record with requested identifier, null if matching record is not found

Throws:

java.lang.NullPointerException - if id is null

getRecord

public NDEFRecord getRecord(int index)

Returns the NDEF record from the specified index in the NDEF message. The index must be a value greater than or equal to 0 and less than the current number of NDEF records in the NDEF message.

Parameters:

index - index of the requested NDEF record

Returns:

the requested NDEF record

Throws:

java.lang.IndexOutOfBoundsException - if index is invalid

getRecord

public NDEFRecord[] getRecord(NDEFRecordType recordType)

Returns the NDEF records with specified record type. If multiple records have the same record type, all these records are returned. The order of the returned records is the same as in the original NDEF records.

Parameters:

recordType - type of the requested NDEF record

Returns:

the requested NDEF records, null if no record with the requested record type are found

Throws:

java.lang.NullPointerException - if recordType is null

getRecords

public NDEFRecord[] getRecords()

Returns all NDEF records in the NDEF message.

Returns:

NDEF records in the NDEF message, zero-length array if there are no NDEF records in the NDEF message

getRecordTypes

public NDEFRecordType[] getRecordTypes()

Returns the record type objects of all NDEF records in the NDEF message. If there are several NDEF records with the same record type, they are all included in the returned array.

Returns:

the record types of the NDEF records in the NDEF message, zero-length array, if there are no NDEF records in the NDEF message

insertRecord

public void insertRecord(int index,
                         NDEFRecord record)

Adds the specified NDEF record to the NDEF records at the specified index. The index must be a value greater than or equal to 0 and less than the current number of NDEF records in the NDEF message. Each NDEF record in the NDEF records with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

Parameters:

index - index to which the new NDEF record is added

record - new NDEF record to be added

Throws:

java.lang.IndexOutOfBoundsException - if index is invalid

java.lang.NullPointerException - if record is null

java.lang.IllegalArgumentException - if a NDEF record with the same payload identifier already exists

removeRecord

public void removeRecord(int index)

Removes an NDEF record from the specified index. The index must be a value greater than or equal to 0 and less than the current number of NDEF records in the NDEF message. Each NDEF record in the NDEF records with an index greater than the specified index is shifted downward to have an index one smaller than the value it had previously.

Parameters:

index - index of the NDEF record to be removed

Throws:

java.lang.IndexOutOfBoundsException - if index is invalid

setRecord

public void setRecord(int index,
                      NDEFRecord record)

Replaces the NDEF record at the specified index. The index must be a value greater than or equal to 0 and less than the current number of NDEF records in the NDEF message.

Parameters:

index - index of the record to be updated

record - updated NDEF record

Throws:

java.lang.IndexOutOfBoundsException - if index is invalid

java.lang.NullPointerException - if record is null

java.lang.IllegalArgumentException - if an NDEF record with the same payload identifier already exists, except the one that is about to be replaced

toByteArray

public byte[] toByteArray()

Returns the whole NDEF message with all the NDEF records as a byte array.

Returns:

NDEF message as a byte array, null if NDEFMessage does not contain any NDEF records