net.rim.blackberry.api.pim
Interface PIMItem

All Known Subinterfaces:

BlackBerryContact, BlackBerryEvent, Contact, Event, ToDo

Deprecated. In favour of PIMItem.

public interface PIMItem

Represents a personal information management (PIM) item.

A PIMItem, such as an event, is created, populated, added to a list, then associated with that list for life. PIMItems can be created or PIM information can be imported from pre-existing PIMItems.

A PIMItem contains data fields that represent information about the item itself. For example, the Contact object contains information about a contact entry such as a phone number, street address or job title. While the item may contain many fields, the list object that the item belongs to defines which fields it's objects can contain. If a list encounters a PIMItem object that contains unsupported fields, those fields are discarded.

The PIMList.isSupportedField(int) is invoked to determine if a field (as specified by the integer argument) is supported by a PIMList. Similarly, the PIMList.getSupportedAttributes(int) method is invoked to return an integer array representing all fields supported by the list.

The PIMItem object represents the common interfaces of the Event, Contact and ToDo objects.

Each field has the following information associated with it:

• a label
• 0 or more data values
• attributes for data values
• a data type

A field can have more than one value associated with it. All values must be of the same data type. An index is used to reference multiple values within a field, beginning with zero and ending with n-1, where n is the total number of values. The index values must be assigned to a value. If a value is removed or added, using the appropriate method, the index is reordered.

Each field has an associated label used for display purposes. The label can be returned by invoking the PIMList.getFieldLabel(int) method.

The supported field data types are INT, BINARY, BOOLEAN, DATE, or STRING.

For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:

PDAP 1.0

See Also:

Event, ToDo, Contact, PIMList

Field Summary

static int	ATTR_NONE Deprecated. Indicates that no additional attributes are applicable for this field.
static int	BINARY Deprecated. Indicates that the data type is binary.
static int	BOOLEAN Deprecated. Indicates that the data type is a Boolean.
static int	DATE Deprecated. Indicates that the data type is a date.
static int	EXTENDED_ATTRIBUTE_MIN_VALUE Deprecated. Represents the minimum value for an extended attribute constant.
static int	EXTENDED_FIELD_MIN_VALUE Deprecated. Represents the minimum value for an extended field constant.
static int	INT Deprecated. Indicates that the data type is an integer.
static int	STRING Deprecated. Indicates that the data type is a string.
static int	STRING_ARRAY Deprecated. Indicates that the data type is a string array.

Method Summary

void	addBinary(int field, int attributes, byte[] value, int offset, int length) Deprecated. Adds a binary value to a field within the item.
void	addBoolean(int field, int attribute, boolean value) Deprecated. Adds a boolean value to the field.
void	addDate(int field, int attributes, long value) Deprecated. Adds a date to a specified field.
void	addInt(int field, int attributes, int value) Deprecated. Adds the integer value contained in the field.
void	addString(int field, int attributes, String value) Deprecated. Adds a string value to the field.
void	addStringArray(int field, int attributes, String[] value) Deprecated. Adds a string array value to the field.
void	addToCategory(String category) Deprecated. Adds a category to this item.
void	commit() Deprecated. Commits the PIMItem to the list.
int	countValues(int field) Deprecated. Returns a value indicating the number of values currently contained within the field.
int	getAttributes(int field, int index) Deprecated. Returns the attributes associated with a specified data value.
byte[]	getBinary(int field, int index) Deprecated. Returns a byte array containing a binary representation of the data within the given field.
boolean	getBoolean(int field, int index) Deprecated. Returns the boolean value contained in the field.
String[]	getCategories() Deprecated. Returns the names of all categories associated with this item.
long	getDate(int field, int index) Deprecated. Returns the date value contained in the field.
int[]	getFields() Deprecated. Returns an integer array containing all fields for which data is associated.
int	getInt(int field, int index) Deprecated. Returns the integer value contained in the field.
PIMList	getPIMList() Deprecated. Returns the PIMList that contains this item.
String	getString(int field, int index) Deprecated. Returns the string value contained in the field.
String[]	getStringArray(int field, int index) Deprecated. Returns the string array value contained in the field.
boolean	isModified() Deprecated. Returns a boolean that indicates whether or not this PIMItem has been modified since the last commit or retrieval.
int	maxCategories() Deprecated. Returns the maximum number of categories that this item can be assigned to.
void	removeFromCategory(String category) Deprecated. Removes a category from this item.
void	removeValue(int field, int index) Deprecated. Removes a value from the specified field, given the index.
void	setBinary(int field, int index, int attributes, byte[] value, int offset, int length) Deprecated. Sets an existing binary value in a field.
void	setBoolean(int field, int index, int attributes, boolean value) Deprecated. Sets an existing boolean value in a field.
void	setDate(int field, int index, int attributes, long value) Deprecated. Sets an existing date value in a field.
void	setInt(int field, int index, int attributes, int value) Deprecated. Sets an existing integer value in a field.
void	setString(int field, int index, int attributes, String value) Deprecated. Sets an existing string value in a field.
void	setStringArray(int field, int index, int attributes, String[] value) Deprecated. Sets an existing string array value in a field.

Field Detail

BINARY

public static final int BINARY

Deprecated.

Indicates that the data type is binary.

The getBinary(int, int) method is used to return a binary value. The addBinary(int, int, byte[], int, int) us used to add a binary value to a field.

Since:

JDE 3.6.0

BOOLEAN

public static final int BOOLEAN

Deprecated.

Indicates that the data type is a Boolean.

The getBoolean(int, int) method is used to return a Boolean value. The addBoolean(int, int, boolean) method is used to add a Boolean value.

Since:

JDE 3.6.0

DATE

public static final int DATE

Deprecated.

Indicates that the data type is a date.

The getDate(int, int) method is used to return a date value. The addDate(int, int, long) method is used to add a date value.

Since:

JDE 3.6.0

INT

public static final int INT

Deprecated.

Indicates that the data type is an integer.

The getInt(int, int) method is used to return an integer value. The addInt(int, int, int) method is used to add an integer value.

Since:

JDE 3.6.0

STRING

public static final int STRING

Deprecated.

Indicates that the data type is a string.

The getString(int, int) method is used to return a string value. The addString(int, int, java.lang.String) method is used to add a string value.

Since:

JDE 3.6.0

STRING_ARRAY

public static final int STRING_ARRAY

Deprecated.

Indicates that the data type is a string array.

The getStringArray(int, int) method is used to return a string array value. The addStringArray(int, int, java.lang.String[]) method is used to add a string array value.

Since:

JDE 3.6.0

ATTR_NONE

public static final int ATTR_NONE

Deprecated.

Indicates that no additional attributes are applicable for this field.

Since:

JDE 3.6.0

EXTENDED_FIELD_MIN_VALUE

public static final int EXTENDED_FIELD_MIN_VALUE

Deprecated.

Represents the minimum value for an extended field constant.

Since:

JDE 3.6.0

EXTENDED_ATTRIBUTE_MIN_VALUE

public static final int EXTENDED_ATTRIBUTE_MIN_VALUE

Deprecated.

Represents the minimum value for an extended attribute constant.

Since:

JDE 3.6.0

Method Detail

getPIMList

public PIMList getPIMList()

Deprecated.

Returns the PIMList that contains this item.

Returns:

A PIMList object.

Since:

JDE 3.6.0

commit

public void commit()
            throws PIMException

Deprecated.

Commits the PIMItem to the list.

Categories that are specified in the PIMItem that are not supported by the PIMList will be discarded.

Throws:

PIMException - Thrown if an error occurs with the item, or the list could not be accessed.

Since:

JDE 3.6.0

isModified

public boolean isModified()

Deprecated.

Returns a boolean that indicates whether or not this PIMItem has been modified since the last commit or retrieval.

Returns:

A boolean.

Since:

JDE 3.6.0

getFields

public int[] getFields()

Deprecated.

Returns an integer array containing all fields for which data is associated.

This method is useful because it returns only fields with data in them. The user does not need to iterate through empty or unsupported fields.

Returns:

An integer array containing the fields for which data is associated.

Since:

JDE 3.6.0

getBinary

public byte[] getBinary(int field,
                        int index)

Deprecated.

Returns a byte array containing a binary representation of the data within the given field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the binary representation.

index - An integer representing the index of the data within the field.

Returns:

A byte array containing the binary representation ("B" binary encoded string) of the data within this field.

Since:

JDE 4.0.0

addBinary

public void addBinary(int field,
                      int attributes,
                      byte[] value,
                      int offset,
                      int length)

Deprecated.

Adds a binary value to a field within the item.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - The field to add the binary data to.

attributes - An integer specifying any attributes that describe this field.

value - The data, a byte array containing a "B" binary encoded string, to add to the field.

offset - The offset, or initial position of the data, within the array.

length - The length of data in the array.

Since:

JDE 4.0.0

getDate

public long getDate(int field,
                    int index)

Deprecated.

Returns the date value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the date.

index - The index of the data within the field.

Returns:

A long representing the date.

Since:

JDE 4.0.0

addDate

public void addDate(int field,
                    int attributes,
                    long value)

Deprecated.

Adds a date to a specified field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to add the date.

attributes - An integer specifying any attributes that describe this field.

value - The value of the date to add.

Since:

JDE 4.0.0

getInt

public int getInt(int field,
                  int index)

Deprecated.

Returns the integer value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the value.

index - The index of the data within the field.

Returns:

The integer value.

Since:

JDE 4.0.0

addInt

public void addInt(int field,
                   int attributes,
                   int value)

Deprecated.

Adds the integer value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to add the data.

attributes - An integer specifying any attributes that describe this field.

value - The data to add to the field.

Since:

JDE 4.0.0

getString

public String getString(int field,
                        int index)

Deprecated.

Returns the string value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the value.

index - The index of the data within the field.

Returns:

A string. The string will not contain any escape characters which might have been used to input the string. The null value is an acceptable value.

Since:

JDE 4.0.0

addString

public void addString(int field,
                      int attributes,
                      String value)

Deprecated.

Adds a string value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to add the data.

attributes - An integer specifying any attributes that describe this field.

value - The string to add to the field. The string will not contain any escape characters which might have been used to input the string. The null value is an acceptable value.

Since:

JDE 4.0.0

getStringArray

public String[] getStringArray(int field,
                               int index)

Deprecated.

Returns the string array value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the value.

index - The index of the data within the field.

Returns:

A string array.

Since:

JDE 4.0.0

addStringArray

public void addStringArray(int field,
                           int attributes,
                           String[] value)

Deprecated.

Adds a string array value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to add the data.

attributes - An integer specifying any attributes that describe this field.

value - The string array to add to the field.

Since:

JDE 4.0.0

getBoolean

public boolean getBoolean(int field,
                          int index)

Deprecated.

Returns the boolean value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to return the boolean.

index - The index of the data within the field.

Returns:

A boolean.

Since:

JDE 4.0.0

addBoolean

public void addBoolean(int field,
                       int attribute,
                       boolean value)

Deprecated.

Adds a boolean value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:

field - An integer representing the field for which to add the data.

attribute - An integer specifying any attributes that describe this field.

value - The data to add to the field.

Since:

JDE 4.0.0

countValues

public int countValues(int field)

Deprecated.

Returns a value indicating the number of values currently contained within the field.

Parameters:

field - The field to check.

Returns:

An integer representing the number of values contained within the field.

Since:

JDE 4.0.0

removeValue

public void removeValue(int field,
                        int index)

Deprecated.

Removes a value from the specified field, given the index.

This method may invalidate the remaining data within the field, since the data is re-indexed once the value is removed.

Parameters:

field - The field from which to remove the value.

index - The index of the value within the field.

Since:

JDE 4.0.0

getAttributes

public int getAttributes(int field,
                         int index)

Deprecated.

Returns the attributes associated with a specified data value.

Parameters:

field - The field from which to return the attributes.

index - The index of the value within the field.

Returns:

An integer representing the attributes returned.

Since:

JDE 4.0.0

addToCategory

public void addToCategory(String category)
                   throws PIMException

Deprecated.

Adds a category to this item.

Use the getCategories() method to return all valid categories associated with the list that contains this item. If an invalid category is specified, a PIMException is thrown. If the specified category is already associated with this item, the operation will be considered a success.

Parameters:

category - A string representing the name of the category.

Throws:

PIMException - Thrown if the specified category is invalid or if the maximum number of categories has already been exceeded.

Since:

JDE 4.0.0

removeFromCategory

public void removeFromCategory(String category)

Deprecated.

Removes a category from this item.

Use the getCategories() method to return all valid categories associated with the list that contains this item. If an invalid category is specified, a PIMException is thrown. If the specified category is already associated with this item, the operation will be considered a success.

Parameters:

category - A string representing the name of the category.

Throws:

PIMException - Thrown if the specified category is invalid or if the maximum number of categories has already been exceeded.

Since:

JDE 4.0.0

getCategories

public String[] getCategories()

Deprecated.

Returns the names of all categories associated with this item.

If no categories are specified, a zero-length string array is returned.

Returns:

An array of strings.

Since:

JDE 3.6.0

maxCategories

public int maxCategories()

Deprecated.

Returns the maximum number of categories that this item can be assigned to.

Returns:

An integer representing the maximum number of categories.

Since:

JDE 3.6.0

setBinary

public void setBinary(int field,
                      int index,
                      int attributes,
                      byte[] value,
                      int offset,
                      int length)

Deprecated.

Sets an existing binary value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - A byte array containing new value to set.

offset - The offset of the data within the array.

length - The length (the number of bytes to read, starting from the beginning of the array) of the data within the array.

Since:

JDE 4.0.0

setBoolean

public void setBoolean(int field,
                       int index,
                       int attributes,
                       boolean value)

Deprecated.

Sets an existing boolean value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - The new value.

Since:

JDE 4.0.0

setDate

public void setDate(int field,
                    int index,
                    int attributes,
                    long value)

Deprecated.

Sets an existing date value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

In the event of a platform data restrictions, data will be rounded down.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - The new value.

Since:

JDE 4.0.0

setInt

public void setInt(int field,
                   int index,
                   int attributes,
                   int value)

Deprecated.

Sets an existing integer value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - The new value.

Since:

JDE 4.0.0

setString

public void setString(int field,
                      int index,
                      int attributes,
                      String value)

Deprecated.

Sets an existing string value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - The new value.

Since:

JDE 4.0.0

setStringArray

public void setStringArray(int field,
                           int index,
                           int attributes,
                           String[] value)

Deprecated.

Sets an existing string array value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Not all elements in the array are required to be supported by the item. If a String is provided at an array index that is not supported by this item, that value is silently discarded.

Parameters:

field - The field in which the value exists.

index - The index of the value to change.

attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.

value - The new value.

Since:

JDE 4.0.0