com.motorola.iden.udm
Class PhoneBookEntry

java.lang.Object
  com.motorola.iden.udm.PhoneBookEntry

All Implemented Interfaces:

UDMEntry

public class PhoneBookEntry

extends java.lang.Object

implements UDMEntry

Represents a single Phonebook entry in a UDM Phonebook database.

The PhoneBookEntry class has many different field IDs that it can support. However, each individual PhoneBookEntry object supports only fields valid for its associated list. Its PhoneBook restricts what fields in a PhoneBookEntry are retained. This reflects that some native PhoneBook databases do not support all of the fields available in a PhoneBookEntry element. The methods UDMList.isSupportedField(int) and UDMList.getSupportedTypes(int) can be used to determine if a particular PhoneBookEntry field is supported by a PhoneBook and therefore persisted when the PhoneBookEntry is committed to its list. Attempts to set or get data based on field IDs not supported in the PhoneBookEntry's PhoneBook result in a UDMException.

The following are the Field IDs supported within a PhoneBookEntry and their corresponding data type.

Table: Named Fields

Field IDs	Type of Data Associated with Field	Valid Range
TEL	UDMEntry.TYPED_STRING	A string of characters in "0123456789+pwPW*#". Its length does not exceed 20 for condor SIM, 64 for falcon SIM. For Gemini product, its length does not exceed 259.
SPEED_NUM	UDMEntry.TYPED_STRING	The valid range is [0, 600] in Falcon phone, and [0, 250] in Condor phone	SPEED_NUM is not supported on Gemini product.
PRIV	UDMEntry.TYPED_STRING	A string of characters in "0123456789*". Its length does not exceed 18
REVISION	UDMEntry.DATE	No less than 915148800000L
EMAIL	UDMEntry.STRING	A valid email address
FORMATTED_NAME	UDMEntry.STRING	For Falcon SIM, its length cannot exceed 20 English characters or 10 unicode characters; For Condor SIM, its length cannot exceed 11 English characters or 5 unicode characters; For Gemini product, its length cannot exceed 259 unicode characters.
GRP	UDMEntry.STRING	Its length cannot exceed 3. Its value must be greater than 1 and less than 255
IP	UDMEntry.STRING	A valid IP address	IP is not supported on Gemini product.
RINGER	UDMEntry.INT	0xff or a positive number that does not exceed 250	RINGER is not supported on Gemini product.

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
© Copyright 2003 Motorola, Inc. All Rights Reserved.

Field Summary

static int	EMAIL EMAIL Field ID for an e-mail address.
static int	FORMATTED_NAME FORMATTED_NAME Field ID for data corresponding to the name of the PhoneBookEntry.
static int	GRP GRP Field ID for a group dispatch id.
static int	IP IP Field ID for a IP address.
static int	NAME_FAMILY NAME_FAMILY Field ID for the family name of the PhoneBookEntry.
static int	NAME_GIVEN NAME_GIVEN Field ID for the given name of the PhoneBookEntry.
static int	NAME_OTHER NAME_OTHER Field ID for another name for the PhoneBookEntry.
static int	NAME_PREFIX NAME_PREFIX Field ID for a name prefix for the PhoneBookEntry.
static int	NAME_SUFFIX NAME_SUFFIX Field ID for a name suffix for the PhoneBookEntry.
static int	NICKNAME NICKNAME Field ID corresponding to the Nickname of the PhoneBookEntry.
static int	PRIV PRIV Field ID for a private dispatch id.
static int	REVISION REVISION Field ID specifying the last modification time of a PhoneBookEntry.
static int	RINGER RINGER Field ID specifying the ringer of a PhoneBookEntry.
static int	SPEED_NUM SPEED_NUM Field ID for a speed dial number.
static int	TEL TEL Field ID for a telephone number.
static int	TYPE_FAX TYPE_FAX Type "fax" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_HOME TYPE_HOME Type "home" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_MAIN TYPE_MAIN Type "main" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_MOBILE TYPE_MOBILE Type "mobile" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_OTHER TYPE_OTHER Type "other" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_PAGER TYPE_PAGER Type "pager" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_PRIVATE TYPE_PRIVATE Type "private" for PRIV, and VOICE_NAME entries.
static int	TYPE_WORK_1 TYPE_WORK_1 Type "work_1" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	TYPE_WORK_2 TYPE_WORK_2 Type "work_2" for TEL, SPEED_NUM, and VOICE_NAME entries.
static int	VOICE_NAME VOICE_NAME Field ID for a voice tag name.

Fields inherited from interface com.motorola.iden.udm.UDMEntry

DATE, INT, STRING, TYPED_STRING

Method Summary

void	commit() This method commits that data to the underlying data storage for the list.
int	getAvailSpeedNum(boolean reverseOrder) This method returns the next available speed dial number.
long	getDate(int fieldID) Get a Date field from the Element.
int	getFieldDataType(int fieldID) Returns an int representing the data type of the data associated with the given field ID.
java.lang.String	getFieldLabel(int fieldID) Returns a String label associated with the given field ID.
int[]	getFields() Returns all field IDs in the element that have data stored for them.
int	getInt(int fieldID) Get an integer field from the Element.
java.lang.String	getString(int fieldID) Get a String field from the Element.
java.lang.String	getTypedString(int fieldID, int typeID) Get a String field with a specific type in the element.
UDMList	getUDMList() Returns the UDMList associated with this element.
boolean	isModified() This method returns a boolean indicating whether any of this element's fields have been modified since the element was retrieved or last committed.
void	setDate(int fieldID, long value) Set a Date field in the Element.
void	setInt(int fieldID, int value) Set an integer field in the Element.
void	setString(int fieldID, java.lang.String value) Set a String field in the Element.
void	setTypedString(int fieldID, int typeID, java.lang.String value) Set a String field with a specific type ID in the element.

Methods inherited from class java.lang.Object

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

Field Detail

EMAIL

public static final int EMAIL

EMAIL Field ID for an e-mail address.

Value 1 is assigned to EMAIL

See Also:

Constant Field Values

FORMATTED_NAME

public static final int FORMATTED_NAME

FORMATTED_NAME Field ID for data corresponding to the name of the PhoneBookEntry.

Value 2 is assigned to FORMATTED_NAME

See Also:

Constant Field Values

NAME_FAMILY

public static final int NAME_FAMILY

NAME_FAMILY Field ID for the family name of the PhoneBookEntry.

Value 3 is assigned to NAME_FAMILY

See Also:

Constant Field Values

NAME_GIVEN

public static final int NAME_GIVEN

NAME_GIVEN Field ID for the given name of the PhoneBookEntry.

Value 4 is assigned to NAME_GIVEN

See Also:

Constant Field Values

NAME_OTHER

public static final int NAME_OTHER

NAME_OTHER Field ID for another name for the PhoneBookEntry.

Value 5 is assigned to NAME_OTHER

See Also:

Constant Field Values

NAME_PREFIX

public static final int NAME_PREFIX

NAME_PREFIX Field ID for a name prefix for the PhoneBookEntry.

Value 6 is assigned to NAME_PREFIX

See Also:

Constant Field Values

NAME_SUFFIX

public static final int NAME_SUFFIX

NAME_SUFFIX Field ID for a name suffix for the PhoneBookEntry.

Value 7 is assigned to NAME_SUFFIX

See Also:

Constant Field Values

NICKNAME

public static final int NICKNAME

NICKNAME Field ID corresponding to the Nickname of the PhoneBookEntry.

Value 8 is assigned to NICKNAME

See Also:

Constant Field Values

RINGER

public static final int RINGER

RINGER Field ID specifying the ringer of a PhoneBookEntry.

Value 9 is assigned to RINGER

See Also:

Constant Field Values

REVISION

public static final int REVISION

REVISION Field ID specifying the last modification time of a PhoneBookEntry.

Value 10 is assigned to REVISION

See Also:

Constant Field Values

TEL

public static final int TEL

TEL Field ID for a telephone number.

Value 11 is assigned to TEL

See Also:

Constant Field Values

PRIV

public static final int PRIV

PRIV Field ID for a private dispatch id.

Value 12 is assigned to PRIV

See Also:

Constant Field Values

GRP

public static final int GRP

GRP Field ID for a group dispatch id.

Value 13 is assigned to GRP

See Also:

Constant Field Values

IP

public static final int IP

IP Field ID for a IP address.

Value 14 is assigned to IP

See Also:

Constant Field Values

SPEED_NUM

public static final int SPEED_NUM

SPEED_NUM Field ID for a speed dial number.

Value 15 is assigned to SPEED_NUM

See Also:

Constant Field Values

VOICE_NAME

public static final int VOICE_NAME

VOICE_NAME Field ID for a voice tag name.

Value 16 is assigned to VOICE_NAME

See Also:

Constant Field Values

TYPE_OTHER

public static final int TYPE_OTHER

TYPE_OTHER Type "other" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 256 is assigned to TYPE_OTHER

See Also:

Constant Field Values

TYPE_PRIVATE

public static final int TYPE_PRIVATE

TYPE_PRIVATE Type "private" for PRIV, and VOICE_NAME entries.

Value 257 is assigned to TYPE_PRIVATE

See Also:

Constant Field Values

TYPE_HOME

public static final int TYPE_HOME

TYPE_HOME Type "home" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 258 is assigned to TYPE_HOME

See Also:

Constant Field Values

TYPE_MOBILE

public static final int TYPE_MOBILE

TYPE_MOBILE Type "mobile" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 259 is assigned to TYPE_MOBILE

See Also:

Constant Field Values

TYPE_PAGER

public static final int TYPE_PAGER

TYPE_PAGER Type "pager" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 260 is assigned to TYPE_PAGER

See Also:

Constant Field Values

TYPE_WORK_1

public static final int TYPE_WORK_1

TYPE_WORK_1 Type "work_1" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 261 is assigned to TYPE_WORK_1

See Also:

Constant Field Values

TYPE_WORK_2

public static final int TYPE_WORK_2

TYPE_WORK_2 Type "work_2" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 262 is assigned to TYPE_WORK_2

See Also:

Constant Field Values

TYPE_FAX

public static final int TYPE_FAX

TYPE_FAX Type "fax" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 263 is assigned to TYPE_FAX

See Also:

Constant Field Values

TYPE_MAIN

public static final int TYPE_MAIN

TYPE_MAIN Type "main" for TEL, SPEED_NUM, and VOICE_NAME entries.

Value 264 is assigned to TYPE_FAX

See Also:

Constant Field Values

Method Detail

getUDMList

public UDMList getUDMList()

Returns the UDMList associated with this element.

Specified by:

getUDMList in interface UDMEntry

Returns:

UDMList associated with this element.

commit

public void commit()
            throws UDMException

This method commits that data to the underlying data storage for the list. This will lock the native database, write the data, and then free the lock. The PhoneBook.isCurrent() will be triggered by commit(). The application should ignore it, since it was the initiator of the action.

Specified by:

commit in interface UDMEntry

Throws:

UDMException - if the commit encounters an error and cannot complete.

java.lang.SecurityException - if the application has not been granted write access to the UDM list.

isModified

public boolean isModified()

This method returns a boolean indicating whether any of this element's fields have been modified since the element was retrieved or last committed.

Specified by:

isModified in interface UDMEntry

Returns:

boolean true if any fields have been modified since the element was last retrieved or committed, false otherwise.

getFieldDataType

public int getFieldDataType(int fieldID)
                     throws UDMException

Returns an int representing the data type of the data associated with the given field ID. This method is useful for some field IDs that may have different types of data per element.

Specified by:

getFieldDataType in interface UDMEntry

Parameters:

fieldID - The ID of the field for which the data type is being queried.

Returns:

int representing the type of the data associated with the field.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.

UDMException - if the field ID is not supported in the implementing instance of the class.

getFieldLabel

public java.lang.String getFieldLabel(int fieldID)
                               throws UDMException

Returns a String label associated with the given field ID.

Specified by:

getFieldLabel in interface UDMEntry

Returns:

String label for the field.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the implementing class.

UDMException - if the field ID is not supported in the implementing instance of the class.

getFields

public int[] getFields()

Returns all field IDs in the element that have data stored for them. This allows quick access to all of the data stored in the element without having to iterate through all supported fields and checking if data is stored for the field or not.

Specified by:

getFields in interface UDMEntry

Returns:

int array of field IDs that have data stored for them.

getDate

public long getDate(int fieldID)
             throws UDMException

Get a Date field from the Element.

Specified by:

getDate in interface UDMEntry

Parameters:

fieldID - The field ID to get.

Returns:

a Date in long ms format representing the value of the field or null to indicate the field has not been set.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.

UDMException - if the field ID is not supported in the implementing instance of the class.

setDate

public void setDate(int fieldID,
                    long value)
             throws UDMException

Set a Date field in the Element.

Specified by:

setDate in interface UDMEntry

Parameters:

fieldID - The field ID to set.

value - The value to set the field to. Setting a field to 0 has the effect of clearing it.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class or if the value is outside the range of supported by the native database.

UDMException - if the field ID is not supported in the implementing instance of the class.

getInt

public int getInt(int fieldID)
           throws UDMException

Get an integer field from the Element.

Specified by:

getInt in interface UDMEntry

Parameters:

fieldID - The field ID to get.

Returns:

an int representing the value of the field.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.

UDMException - if the field ID is not supported in the implementing instance of the class.

setInt

public void setInt(int fieldID,
                   int value)
            throws UDMException

Set an integer field in the Element.

Specified by:

setInt in interface UDMEntry

Parameters:

fieldID - The field ID to set.

value - The value to set the field to.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class or if the value is outside the range of supported by the native database.

UDMException - if the field ID is not supported in the implementing instance of the class. or the value is invalid for the class.

getString

public java.lang.String getString(int fieldID)
                           throws UDMException

Get a String field from the Element.

Specified by:

getString in interface UDMEntry

Parameters:

fieldID - The field ID to get.

Returns:

a String representing the value of the field or null to indicate the field has not been set.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.

UDMException - if the field ID is not supported in the implementing instance of the class.

setString

public void setString(int fieldID,
                      java.lang.String value)
               throws UDMException

Set a String field in the Element.

Specified by:

setString in interface UDMEntry

Parameters:

fieldID - The field ID to set.

value - The value to set the field to. Setting a field to null has the effect of clearing it.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid for the derived class or if the value is outside the range of supported by the native database.

UDMException - if the field ID is not supported in the implementing instance of the class. or the value is invalid for the class.

getTypedString

public java.lang.String getTypedString(int fieldID,
                                       int typeID)
                                throws UDMException

Get a String field with a specific type in the element.

Specified by:

getTypedString in interface UDMEntry

Parameters:

fieldID - The field ID to get.

typeID - The specific type for the field to retrieve.

Returns:

a String representing the value of the field/type or null to indicate the field/type has not been set.

Throws:

java.lang.IllegalArgumentException - if the field ID or type ID is not valid for the derived class.

UDMException - if the field ID is not supported in the implementing instance of the class.

setTypedString

public void setTypedString(int fieldID,
                           int typeID,
                           java.lang.String value)
                    throws UDMException

Set a String field with a specific type ID in the element.

Specified by:

setTypedString in interface UDMEntry

Parameters:

fieldID - The field ID to set.

typeID - The type ID for the field.

value - The value to set the field to. Setting a field to null has the effect of clearing it.

Throws:

java.lang.IllegalArgumentException - if the field ID or type ID is not valid for the derived class or if the value is outside the range of supported by the native database.

UDMException - if the field ID is not supported in the implementing instance of the class. or the value is invalid for the class.

getAvailSpeedNum

public int getAvailSpeedNum(boolean reverseOrder)
                     throws UDMException

This method returns the next available speed dial number. It should be used to populate the SPEED_NUM field. This method is not supported on Gemini product.

Parameters:

reverseOrder - Indicates from which direction (lowest or highest) the caller want phonebook to search the DB for an available speed number.

Returns:

An int representing the next available speed dial number

Throws:

UDMException - This method throws an exception when there are no more available speed numbers.