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 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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2

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.2


Copyright 1999-2004 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.