com.motorola.iden.udm
Class DateBookEvent

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

All Implemented Interfaces:

UDMEntry

public class DateBookEvent

extends java.lang.Object

implements UDMEntry

DateBookEvent represents a single Event entry in a UDM DateBook database.

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

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

Table: Named Fields

Field IDs	Type of Data Associated with Field
LOCATION, SUMMARY	UDMEntry.STRING
ALARM, END, START	UDMEntry.DATE

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

Field Summary

static int	ALARM ALARM Field ID specifying the date and time for an Alarm for this Event.
static int	END END Field ID specifying the non-inclusive date and time a single Event ends.
static int	LOCATION LOCATION Field ID identifying the venue for this Event.
static int	MIDLET MIDLET Field ID specifying MIDlet with MIDLET_SUITE that should be launched when the DateBookEvent expires.
static int	MIDLET_SUITE MIDLET_SUITE Field ID specifying MIDlet Suite that should be opened when the DateBookEvent expires.
static int	REVISION REVISION Field ID specifying the last modification date and time of an Event element.
static int	RINGER RINGER Field ID specifying the ringer associated with the DateBookEvent.
static int	START START Field ID specifying the inclusive date and time a single Event starts.
static int	STYLE STYLE Field ID for a style.
static int	SUMMARY SUMMARY Field ID specifying the summary or subject for this Event.

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.
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.
DateBookRepeatEvent	getRepeat() Retrieves a DateBookRepeatEvent object specifying how often and when this event occurs.
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	setRepeat(DateBookRepeatEvent value) Sets the DateBookRepeatEvent specifying how often and when this event occurs.
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

START

public static final int START

START Field ID specifying the inclusive date and time a single Event starts. If START and END are the same it is an all day event.

Value 1 is assigned to START.

See Also:

Constant Field Values

END

public static final int END

END Field ID specifying the non-inclusive date and time a single Event ends. If START and END are the same it is an all day event.

Value 2 is assigned to END.

See Also:

Constant Field Values

ALARM

public static final int ALARM

ALARM Field ID specifying the date and time for an Alarm for this Event. The granularity is minutes and can only be specified from 0-10080 minutes before.

Value 3 is assigned to ALARM.

See Also:

Constant Field Values

SUMMARY

public static final int SUMMARY

SUMMARY Field ID specifying the summary or subject for this Event. The max length of the string is 64 bytes.

Value 4 is assigned to SUMMARY.

See Also:

Constant Field Values

LOCATION

public static final int LOCATION

LOCATION Field ID identifying the venue for this Event. This is a string value. For example: "Conference Room - F123, Bldg. 002". The max length of the string is 64 bytes.

Value 5 is assigned to LOCATION.

See Also:

Constant Field Values

REVISION

public static final int REVISION

REVISION Field ID specifying the last modification date and time of an Event element. This field cannot be set through the API (i.e. is a read-only field). This field is set automatically on adds, imports, and updates of an Event. This field is not supported on Gemini product.

Value 6 is assigned to REVISION.

See Also:

Constant Field Values

RINGER

public static final int RINGER

RINGER Field ID specifying the ringer associated with the DateBookEvent. This field is not supported on Gemini product.

Value 7 is assigned to RINGER.

See Also:

Constant Field Values

STYLE

public static final int STYLE

STYLE Field ID for a style. It could be set to a STYLE_* constant strings or a customized style. If the phone does not have a customized style whose title matches the string, the STYLE for the DateBookEvent will be set to STYLE_OFF. This field is not supported on Gemini product.

Value 8 is assigned to STYLE.

See Also:

Constant Field Values

MIDLET_SUITE

public static final int MIDLET_SUITE

MIDLET_SUITE Field ID specifying MIDlet Suite that should be opened when the DateBookEvent expires. This should be the MIDlet suite friendly name. If the Suite specified is not on the device then it will not be committed to the native database. This field is not supported on Gemini product.

Value 9 is assigned to MIDLET_SUITE.

See Also:

Constant Field Values

MIDLET

public static final int MIDLET

MIDLET Field ID specifying MIDlet with MIDLET_SUITE that should be launched when the DateBookEvent expires. This should be the full class path of the MIDlet. If the MIDlet specified is not on the device then it will not be committed to the native database. This field is not supported on Gemini product.

Value 10 is assigned to MIDLET.

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.

Specified by:

commit in interface UDMEntry

Throws:

UDMException - if the commit encounters an error and cannot complete. If the data to be committed is invalid, such as Summary is null, no start time or end time is specified, alarm is before current time, alarm is for untimed event, then an UDMException will be thrown.

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 supported by the native database. END date should be greater than START date. ALARM value shoud be 0-10080 minutes before.

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 or try to set Midlet name before setting Midlet Suite name.

getTypedString

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

Get a String field with a specific type in the element. Currently typed string fields are not supported for DateBook events.

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. Currently typed string fields are not supported for DateBook events.

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.

getRepeat

public DateBookRepeatEvent getRepeat()

Retrieves a DateBookRepeatEvent object specifying how often and when this event occurs.

Returns:

the DateBookRepeatEvent describing how often this Event occurs or null if a DateBookRepeatEvent has not been set.

setRepeat

public void setRepeat(DateBookRepeatEvent value)

Sets the DateBookRepeatEvent specifying how often and when this event occurs.

Parameters:

value - An DateBookRepeatEvent describing how often this Event occurs or null to clear any DateBookRepeatEvent.