javax.microedition.contactless.ndef
Class NDEFRecord

java.lang.Object
  javax.microedition.contactless.ndef.NDEFRecord

public class NDEFRecord
extends java.lang.Object

This class represents an NDEF record. An NDEF record consists of type, type format, identifier for the payload and the actual payload in a byte array. This class is an abstraction of the NDEF record defined by the NFC Forum NDEF specification and it hides some of the fields defined in that specification and leaves them to the API implementation. NDEF record may contain subrecords. Nested records can be accessed by getting the record payload and then parsing that payload into new NDEF records.

A record type gives an identity to the payload in the record. Based on the record type information the application knows the meaning of the record payload. This information is used to guide the processing of the payload, like for example in the application start as described in the appendix B. The type of the first NDEF record inside NDEF message, by convention, should provide the processing context not only for the first record but for the whole NDEF message.

The NDEF record also contains an optional identifier for the payload. This identifier may be used to refer to the payload in other records. The value of the ID field is an identifier in the form of a URI RFC (3986). This class provides methods for getting and setting this identifier. Character encoding used in identifier field must be UTF-8.

The chunking feature defined in the NDEF specification must be handled below the Java API level. Only complete NDEF records are provided to the Java application. This means that the device implementing this API should have enough memory to handle complete NDEF records.

Version:

1.0

Author:

Nokia Corporation

Constructor Summary

NDEFRecord(byte[] data, int offset)
Formulates a new NDEF record from the given byte array starting from the specified index.

NDEFRecord(NDEFRecordType recordType, byte[] id, byte[] payload)
Creates a new NDEFRecord with specified record type, identifier and payload.

Method Summary

void	appendPayload(byte[] payload) This method appends payload into the end of the NDEF record payload.
byte[]	getId() Returns the identifier for the record payload.
NDEFMessage	getNestedNDEFMessage(int offset) Returns the nested NDEF message from the record payload.
byte[]	getPayload() Returns the payload in the NDEF record as byte array.
long	getPayloadLength() Returns the length of the payload in the NDEF record.
NDEFRecordType	getRecordType() Returns the record type of this record.
void	setId(byte[] id) Sets the identifier for the record payload.
byte[]	toByteArray() Returns the NDEF record as byte array, containing the record type name, type format, identifier, length and the payload of the record.

Methods inherited from class java.lang.Object

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

Constructor Detail

NDEFRecord

public NDEFRecord(byte[] data,
                  int offset)

Formulates a new NDEF record from the given byte array starting from the specified index. The byte array should contain the record type name, type format, identifier, length and the payload of the record. The offset must be a value greater than or equal to 0 and less than the length of the payload byte array.

Parameters:

data - the byte array containing the NDEF record

offset - start index of the NDEF record data in the payload byte array

Throws:

java.lang.NullPointerException - if data is null

java.lang.ArrayIndexOutOfBoundsException - if the offset is invalid

java.lang.IllegalArgumentException - if the data cannot be formulated to NDEF record

NDEFRecord

public NDEFRecord(NDEFRecordType recordType,
                  byte[] id,
                  byte[] payload)

Creates a new NDEFRecord with specified record type, identifier and payload. The constructor implementation must make a copy from the original identifier and payload.

Record identifier is given in the URL format and it may be null. In this case it must be omitted from the NDEF record.

Payload of the NDEF record may be null or a zero-length array. Both these cases mean that payload must be omitted from the NDEF record.

If record type format is NDEFRecordType.EMPTY the identifier and the payload must be omitted from the NDEF record.

Parameters:

recordType - record type of the NDEF record

id - payload identifier

payload - payload of the record as byte array

Throws:

java.lang.NullPointerException - if recordType is null

Method Detail

appendPayload

public void appendPayload(byte[] payload)

This method appends payload into the end of the NDEF record payload. If payload is an empty array or null, this method returns without any additions to the existing payload. If the record type format is EMPTY, the payload must be omitted from the NDEF record and using this method causes an IllegalArgumentException to the thrown.

Parameters:

payload - payload to be added

Throws:

java.lang.IllegalArgumentException - if record type format is EMPTY and this method is called

getId

public byte[] getId()

Returns the identifier for the record payload. This can be used to refer to this payload from other records.

Returns:

data identifier, null if identifier has been omitted from the NDEF record

getNestedNDEFMessage

public NDEFMessage getNestedNDEFMessage(int offset)

Returns the nested NDEF message from the record payload. The beginning of the message is identified by the offset. The offset must be a value greater than or equal to 0 and less than the length of the payload byte array. If the NDEF record does not have payload null is returned.

Parameters:

offset - the start index of the NDEF message in the payload byte array

Returns:

the nested NDEF message, null if the NDEF record does not have payload

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the offset is invalid

java.lang.IllegalArgumentException - if the record payload can not be formulated to NDEF message

getPayload

public byte[] getPayload()

Returns the payload in the NDEF record as byte array.

Returns:

the payload of the NDEF record, null if payload has been omitted from the NDEF record

getPayloadLength

public long getPayloadLength()

Returns the length of the payload in the NDEF record. This method is offered for convenience, so that the payload length is available before actually retrieving it.

Returns:

the length of the payload, 0 if payload has been omitted from the NDEF record

getRecordType

public NDEFRecordType getRecordType()

Returns the record type of this record. This object contains the actual type and the type format information.

Returns:

Returns the reference to record type object of this record

setId

public void setId(byte[] id)

Sets the identifier for the record payload. This identifier can be used to refer to the payload in this record from other records and it is given in the URL format. Identifier may be null. In this case it must be omitted from the NDEF record. If the record type format is EMPTY, the identifier must be omitted from the NDEF record and using this method causes an IllegalArgumentException to the thrown. The implementation must make a copy from the original identifier.

Parameters:

id - identifier of the payload

Throws:

java.lang.IllegalArgumentException - if record type format is EMPTY and this method is called

toByteArray

public byte[] toByteArray()

Returns the NDEF record as byte array, containing the record type name, type format, identifier, length and the payload of the record. This method has the same effect as calling NDEFMessage.toByteArray() for an NDEFMessage object that has only a single NDEFRecord object. The NDEFRecord must have both the MB and ME set.

Returns:

NDEF record as a byte array