javax.microedition.pim
Interface PIMList

All Known Subinterfaces:

ContactList, EventList, ToDoList, BlackBerryContactList, BlackBerryEventList, BlackBerryMemoList, BlackBerryPIMList, BlackBerryToDoList

public interface PIMList

Represents the common functionality of a PIM list. PIMLists contain zero or more PIMItems (represented by the class PIMItem). A PIMList allows retrieval of all or some of the PIMItems contained in the list.

PIMLists maintain categories. Categories are logical groupings for the PIMItems contained in the list. Each PIMList can support zero or more categories. Categories are represented by unique String names.

Each PIMList also defines what fields are included in the items that get stored in the list. While the definition of all possible fields reside in PIMItem, each PIMList dictates which fields are supported for storage and retrieval in the list's items at runtime.

RIM Implementation Notes

The RIM extensions to the PIMList implementations are defined in BlackBerryPIMList. The sub-interfaces of BlackBerryPIMList provide the RIM extensions to each individual PIM list (for example, BlackBerryEventList provides the RIM extensions to EventList).

Any PIMList instance retrieved from PIM.openPIMList() can be successfully cast into a BlackBerryPIMList in order to use these RIM extensions.

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

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

Since:

BlackBerry API 4.0.0, PIM 1.0

Field Summary
static String	UNCATEGORIZED Constant for the PIMList.itemsByCategory(String) method to indicate to search for uncategorized items.

Method Summary
void	addCategory(String category) Adds the provided category to the PIM list.
void	close() Closes the list, releasing any resources for this list.
void	deleteCategory(String category, boolean deleteUnassignedItems) Deletes the indicated category from the PIM list.
String	getArrayElementLabel(int stringArrayField, int arrayElement) Returns a String label associated with the given array element.
String	getAttributeLabel(int attribute) Returns a String label associated with the given attribute.
String[]	getCategories() Returns the categories defined for the PIM list.
int	getFieldDataType(int field) Returns the data type of the data associated with the given field.
String	getFieldLabel(int field) Returns a String label associated with the given field.
String	getName() Provides the name of the list.
int[]	getSupportedArrayElements(int stringArrayField) Returns an integer array containing all of the supported elements of a string array for the given field.
int[]	getSupportedAttributes(int field) Returns an integer array containing all of the supported attributes for the given field.
int[]	getSupportedFields() Gets all fields that are supported in this list.
boolean	isCategory(String category) Returns indication of whether the given category is a valid existing category for this list.
boolean	isSupportedArrayElement(int stringArrayField, int arrayElement) Indicates whether or not the given element in a array is supported for the indicated field in this PIM list.
boolean	isSupportedAttribute(int field, int attribute) Indicates whether or not the given attribute is supported in this PIM list for the indicated field.
boolean	isSupportedField(int field) Indicates whether or not the given field is supported in this PIM list.
Enumeration	items() Returns an Enumeration of all items in the list.
Enumeration	items(String matching) Return an Enumeration of items with String field data that contains the matching string argument.
Enumeration	items(PIMItem matching) Returns an Enumeration of all items in the list that contain fields that match all of those fields specified in the given "matching" item.
Enumeration	itemsByCategory(String category) Returns an enumeration of all items in the PIM list that match the provided category.
int	maxCategories() Returns the maximum number of categories that this list can have.
int	maxValues(int field) Indicates the total number of data values that a particular field supports in this list.
void	renameCategory(String currentCategory, String newCategory) Renames a category from an old name to a new name.
int	stringArraySize(int stringArrayField) Returns the size of the array for the given string array field.

Field Detail

UNCATEGORIZED

static final String UNCATEGORIZED

Constant for the PIMList.itemsByCategory(String) method to indicate to search for uncategorized items. The value of this constant is null.

Since:

BlackBerry API 4.0.0

Method Detail

addCategory

void addCategory(String category)
                 throws PIMException

Adds the provided category to the PIM list. If the given category already exists for the list, the method does not add another category and considers that this method call is successful and returns.

The category names are case sensitive in this API, but not necessarily in the underlying implementation. For example, "Work" and "WORK" map to the same underlying category if the platform's implementation of categories is case-insensitive; adding both separately would result in only one category being created in this case.

A string with no characters ("") may or may not be a valid category on a particular platform. If the string is not a valid category as defined by the platform, a PIMException will be thrown when trying to add it.

Parameters:

category - a String representing the category to add.

Throws:

PIMException - If categories are unsupported, an error occurs, or the list is no longer accessible or closed. Also thrown if the maximum number of categories for this list is exceeded, or if the category name is invalid.

SecurityException - if the application is not given permission to write to the PIM list or the list is opened READ_ONLY.

NullPointerException - if category is null.

See Also:

PIMList.deleteCategory(String, boolean), PIMList.renameCategory(String, String), PIMList.getCategories(), PIMList.isCategory(String), PIMList.maxCategories()

Since:

BlackBerry API 4.0.0

close

void close()
           throws PIMException

Closes the list, releasing any resources for this list. A PIMException is thrown for any subsequent method invocations for the class instance.

Throws:

PIMException - If the list is no longer accessible.

Since:

BlackBerry API 4.0.0

deleteCategory

void deleteCategory(String category,
                    boolean deleteUnassignedItems)
                    throws PIMException

Deletes the indicated category from the PIM list. If the indicated category is not in the PIM list, this method is treated as successfully completing.

The category names are case sensitive in this API, but not necessarily in the underlying implementation. For example, "Work" and "WORK" map to the same underlying category if the platform's implementation of categories is case-insensitive; removing both separately would result in only one category being removed in this case.

Parameters:

category - a String representing the category to delete.

deleteUnassignedItems - if true then delete all items in this list that no longer have any categories assigned to them as a result of this method; if false then no items are deleted as a result of this method.

Throws:

PIMException - If categories are unsupported, an error occurs, or the list is no longer accessible or closed.

SecurityException - if the application is not given permission to write to the PIM list or the list is opened READ_ONLY.

NullPointerException - if category is null.

See Also:

PIMList.addCategory(String), PIMList.renameCategory(String, String), PIMList.getCategories(), PIMList.isCategory(String), PIMList.maxCategories()

Since:

BlackBerry API 4.0.0

getArrayElementLabel

String getArrayElementLabel(int stringArrayField,
                            int arrayElement)

Returns a String label associated with the given array element. Array element labels are provided by the platform and are not changeable by the application.

PIMList.isSupportedArrayElement(int, int) should be used to verify the array elements's validity for this item prior to invoking this method.

Parameters:

stringArrayField - The field which has a STRING_ARRAY data type, as defined by classes implementing the PIMItem interface, whose element's label to return.

arrayElement - The element in the array whose label to return, as defined in the classes implementing the PIMItem interface.

Returns:

String label for the array element. The label is locale specific (see the microedition.locale system property).

Throws:

IllegalArgumentException - if the field or array element is not valid for the implementing class. IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

UnsupportedFieldException - if the field or array element is not supported in the implementing instance of the class.

See Also:

PIMList.getSupportedArrayElements(int), PIMList.isSupportedArrayElement(int, int)

Since:

BlackBerry API 4.0.0

getAttributeLabel

String getAttributeLabel(int attribute)

Returns a String label associated with the given attribute. Attribute labels are provided by the platform and are not changeable by the application.

PIMList.isSupportedAttribute(int, int) should be used to verify the attribute's validity for this item prior to invoking this method.

Parameters:

attribute - The attribute for which the label is being queried.

Returns:

String label for the attribute. The label is locale specific (see the microedition.locale system property).

Throws:

IllegalArgumentException - if the attribute is not valid for the implementing class. IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

UnsupportedFieldException - if the attribute is not supported in the implementing instance of the class.

See Also:

PIMList.isSupportedAttribute(int, int), PIMList.getSupportedAttributes(int)

Since:

BlackBerry API 4.0.0

getCategories

String[] getCategories()
                       throws PIMException

Returns the categories defined for the PIM list. If there are no categories defined for the PIM list or categories are unsupported for the list, then a zero length array is returned.

Returns:

A string array containing the categories defined for the PIM list.

Throws:

PIMException - If an error occurs or the list is no longer accessible or closed.

See Also:

PIMList.addCategory(String), PIMList.deleteCategory(String, boolean), PIMList.renameCategory(String, String), PIMList.isCategory(String), PIMList.maxCategories()

Since:

BlackBerry API 4.0.0

getFieldDataType

int getFieldDataType(int field)

Returns the data type of the data associated with the given field. This method is useful for platform extended fields. PIMList.isSupportedField(int) should be used to verify the field validity for this item prior to invoking this method.

Parameters:

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

Returns:

the data type of the specified field; possible return values include PIMItem.INT, PIMItem.BOOLEAN, PIMItem.STRING, PIMItem.STRING_ARRAY, PIMItem.BINARY, and PIMItem.DATE.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class. IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

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

See Also:

PIMList.isSupportedField(int), PIMList.getSupportedFields(), PIMList.maxValues(int)

Since:

BlackBerry API 4.0.0

getFieldLabel

String getFieldLabel(int field)

Returns a String label associated with the given field. Field labels are provided by the platform and are not changeable by the application.

PIMList.isSupportedField(int) should be used to verify the field validity for this item prior to invoking this method.

Parameters:

field - The field for which the label is being queried.

Returns:

String label for the field. The label is locale specific (see the microedition.locale system property).

Throws:

IllegalArgumentException - if the field is not valid for the implementing class. IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

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

See Also:

PIMList.getSupportedFields(), PIMList.isSupportedField(int)

Since:

BlackBerry API 4.0.0

getName

String getName()

Provides the name of the list. All PIMLists have a non-null name associated with it.

RIM Implementation Note: In the case where the underlying database that this list accesses is removed this method returns the empty string.

Returns:

a String representation of the list name; never returns null.

See Also:

PIM.listPIMLists(int), PIM.openPIMList(int, int, String)

Since:

BlackBerry API 4.0.0

getSupportedArrayElements

int[] getSupportedArrayElements(int stringArrayField)

Returns an integer array containing all of the supported elements of a string array for the given field. The array elements are provided one element per entry in the returned integer array.

Parameters:

stringArrayField - The field which has a STRING_ARRAY data type, as defined by classes implementing the PIMItem interface, whose list of supported array elements to return.

Returns:

an array containing the supported array elements of the specified string array field, one array element per entry in the array. If there are no supported array elements, a zero-length array is returned.

Throws:

IllegalArgumentException - if field is not a valid STRING_ARRAY field (i.e. not a standard field and not an extended field that has a data type of StringArray). IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

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

See Also:

PIMList.getArrayElementLabel(int, int), PIMList.isSupportedArrayElement(int, int)

Since:

BlackBerry API 4.0.0

getSupportedAttributes

int[] getSupportedAttributes(int field)

Returns an integer array containing all of the supported attributes for the given field. All attributes supported by this list, including both standard and extended, are returned in this array. The attributes are provided one attribute per entry in the returned integer array.

Parameters:

field - the field whose supported attributes list to return.

Returns:

an array containing the list of supported attributes for the specified field, one attribute per entry in the array. If there are no supported attributes for the specified field then a zero-length array is returned.

Throws:

IllegalArgumentException - if field is not a valid field (i.e. not a standard field and not an extended field). IllegalArgumentException takes precedence over UnsupportedFieldException when checking the provided field.

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

See Also:

PIMList.getAttributeLabel(int), PIMList.isSupportedAttribute(int, int)

Since:

BlackBerry API 4.0.0

getSupportedFields

int[] getSupportedFields()

Gets all fields that are supported in this list. All fields supported by this list, including both standard and extended, are returned in this array.

Returns:

an array containing all fields supported by this list. The order of the fields returned is unspecified. If there are no supported fields, a zero-length array is returned.

See Also:

PIMList.getFieldLabel(int), PIMList.isSupportedField(int), PIMList.maxValues(int)

Since:

BlackBerry API 4.0.0

isCategory

boolean isCategory(String category)
                   throws PIMException

Returns indication of whether the given category is a valid existing category for this list.

Parameters:

category - a String representing the category to query.

Returns:

true if the specified category is a valid existing category for this list; false otherwise.

Throws:

PIMException - If an error occurs or the list is no longer accessible or closed.

See Also:

PIMList.addCategory(String), PIMList.deleteCategory(String, boolean), PIMList.renameCategory(String, String), PIMList.getCategories(), PIMList.maxCategories()

Since:

BlackBerry API 4.0.0

isSupportedArrayElement

boolean isSupportedArrayElement(int stringArrayField,
                                int arrayElement)

Indicates whether or not the given element in a array is supported for the indicated field in this PIM list.

Parameters:

stringArrayField - The field which has a STRING_ARRAY data type, as defined by classes implementing the PIMItem interface.

arrayElement - The element in the array to check, as defined in the classes implementing the PIMItem interface.

Returns:

true if the specified array element is supported in the specified string array field, false otherwise. Invalid fields and invalid array elements return false.

See Also:

PIMList.getArrayElementLabel(int, int), PIMList.getSupportedArrayElements(int)

Since:

BlackBerry API 4.0.0

isSupportedAttribute

boolean isSupportedAttribute(int field,
                             int attribute)

Indicates whether or not the given attribute is supported in this PIM list for the indicated field.

Parameters:

field - The field against which the attribute is checked.

attribute - The single attribute to check.

Returns:

true if the specified attribute is supported for values in the specified field, false otherwise. Invalid fields and invalid attributes return false.

See Also:

PIMList.getAttributeLabel(int), PIMList.getSupportedAttributes(int)

Since:

BlackBerry API 4.0.0

isSupportedField

boolean isSupportedField(int field)

Indicates whether or not the given field is supported in this PIM list.

Parameters:

field - The field to check, as defined by in the class implementing the PIMItem.

Returns:

true if the specified field is supported in this list, false otherwise. Invalid fields return false.

See Also:

PIMList.getSupportedFields(), PIMList.getFieldLabel(int), PIMList.getFieldDataType(int), PIMList.maxValues(int)

Since:

BlackBerry API 4.0.0

items

Enumeration items()
                  throws PIMException

Returns an Enumeration of all items in the list. The order is undefined.

Returns:

an Enumeration of all items.

Throws:

PIMException - If an error occurs or the list is no longer accessible or closed.

SecurityException - if the application is not given permission to read the PIM list or the list is opened WRITE_ONLY.

See Also:

PIMList.items(PIMItem), PIMList.items(String), PIMList.itemsByCategory(String)

Since:

BlackBerry API 4.0.0

items

Enumeration items(PIMItem matching)
                  throws PIMException

Returns an Enumeration of all items in the list that contain fields that match all of those fields specified in the given "matching" item. An item that matches may have more data than is specified in the matching item, but must at least match all fields specified in the matching item. Only fields that have values set within the matching item are used for matching comparisons (i.e. fields returned by PIMItem.getFields() for the matching item).

Matching is done with the following rules and may be locale dependent:

• When matching values for a particular field, the indexes associated with a value in a field are not used and are irrelevant. A match is considered positive if the searched-for value appears in a field at any index. For example, a string value of "Bob" at index 0 in a PIMItem field matches "Bob" at index 0, index 1, or any index in that field in another PIMItem.
• When matching values for a particular field, all of the attributes specified in the search-for value must be a subset or complete set of attributes in a compared value in order for the match to be considered positive. For example, if ATTR_HOME were specified with the searched-for value, then values with attributes ATTR_HOME or ATTR_HOME|ATTR_MOBILE (or any other attributes OR'd with ATTR_HOME) would satisfy this attribute matching rule.
• PIMItem.ATTR_NONE is an exception to the above rule such that PIMItem.ATTR_NONE is an unspecified member of every attribute set and therefore matches all attribute sets. For example, if ATTR_NONE were specified with a searched-for value of "Bob", then all "Bob" values regardless of its actual assigned attributes would satisfy this attribute matching rule.
• Implementations have the option of ignoring attribute hints assigned per value in a field. The evaluation of the attribute hints are applied prior to comparison by the implementation. For example, if ATTR_HOME|ATTR_MOBILE were specified with the searched-for value but ATTR_MOBILE was not supported in the particular list being searched, then this method would use ATTR_HOME as the attribute to match for according to the other attribute matching rules. To avoid this situation in which the attribute sets used may different than intended, it is recommended to verify the attribute's validity using PIMList.isSupportedAttribute(int, int) prior to setting the attribute in the searched-for PIMItem.
• For fields that store Strings as values, matching is defined as true if the input String field value is contained anywhere within the field's stored String value. The locale of the device MAY be used as a basis for the matching rules. Comparisons are case insensitive if case is supported in the current locale. For example, if the matching item's NOTE field is set to "pho", a positive match occurs in the strings "Mobile phone" and "THIS IS A PHONE NOTE" as well as the string "telephone". If an empty string is provided in the matching item (i.e. String("")), the empty string matches all set values for the field.
• All the other data types besides Strings must match data values exactly (i.e. equals()).

  Parameters:

  matching - the item whose set fields are used for finding matching items. This item must have been created using this same list.

  Returns:

  an enumeration of all items that contain fields that match all of the fields of the "matching" item parameter.

  Throws:

  PIMException - If an error occurs or the list is no longer accessible or closed.

  IllegalArgumentException - If the item provided did not originate from this list.

  NullPointerException - if matching is null.

  SecurityException - if the application is not given permission to read the PIM list or the list is opened WRITE_ONLY.

  See Also:

  PIMList.items(), PIMList.items(String), PIMList.itemsByCategory(String)

  Since:

  BlackBerry API 4.0.0

items

Enumeration items(String matching)
                  throws PIMException

Return an Enumeration of items with String field data that contains the matching string argument.

NOTE: this method may not be as optimized as PIMList.items(PIMItem) so that method should be used instead of this one if applicable.

Matching is done with the following rules and may be locale dependent:

• The locale of the device MAY be used as a basis for the matching rules. Comparisons are case insensitive if case is supported in the current locale.
• A match is positive if the input String value is contained anywhere within any String field's stored String value. For example, if the search string is "pho", a positive match occurs in the strings "Mobile phone" and "THIS IS A PHONE NOTE" as well as in the string "telephone".
• If the empty string is provided (i.e. String("")), the empty string matches all non-null String values.

  Parameters:

  matching - a string value to which all set String field values are compared.

  Returns:

  an enumeration of all items that contain at least one field that matches the string parameter.

  Throws:

  PIMException - If an error occurs or the list is no longer accessible or closed.

  NullPointerException - if matching is null.

  SecurityException - if the application is not given permission to read the PIM list or the list is opened WRITE_ONLY.

  See Also:

  PIMList.items(), PIMList.items(PIMItem), PIMList.itemsByCategory(String)

  Since:

  BlackBerry API 4.0.0

itemsByCategory

Enumeration itemsByCategory(String category)
                            throws PIMException

Returns an enumeration of all items in the PIM list that match the provided category.

Category matching rules:

• A PIM list item that contains the given category is in the returned enumeration.
• A category string that matches none of the categories of the items in the PIM list returns an empty enumeration.
• Use of the category string PIMList.UNCATEGORIZED returns an enumeration of all PIM items of the PIM list that have no category assignments.
• A null category string is equivalent to the category string UNCATEGORIZED.
• An empty category string "" is considered a valid string parameter for comparison with existing categories, e.g. "" matches only a category also named "".
• The full category string is used for comparison, and must return true for a String.equals() comparison.

Parameters:

category - A string category to find matching items with; may be null.

Returns:

An enumeration of all items in the PIM list that match the specified category.

Throws:

PIMException - If an error occurs or the list is no longer accessible or closed.

SecurityException - If the application is not given permission to read the PIM list or the list is opened WRITE_ONLY.

See Also:

PIMList.items(), PIMList.items(PIMItem), PIMList.items(String)

Since:

BlackBerry API 4.0.0

maxCategories

int maxCategories()

Returns the maximum number of categories that this list can have.

Returns:

the number of categories supported by this list. 0 (zero) indicates no category support and -1 indicates there is no limit the the number of categories that this list can have.

See Also:

PIMList.addCategory(String), PIMList.deleteCategory(String, boolean), PIMList.renameCategory(String, String), PIMList.getCategories(), PIMList.isCategory(String)

Since:

BlackBerry API 4.0.0

maxValues

int maxValues(int field)

Indicates the total number of data values that a particular field supports in this list.

Parameters:

field - the field whose maximum number of supported values to return.

Returns:

the number of values that can be stored in the specified field. Additionally, -1 indicates this field supports having an unlimited number of added values in it, and 0 (zero) indicates the field is not supported by this list.

Throws:

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

See Also:

PIMList.getSupportedFields(), PIMList.isSupportedField(int), PIMList.getFieldDataType(int)

Since:

BlackBerry API 4.0.0

renameCategory

void renameCategory(String currentCategory,
                    String newCategory)
                    throws PIMException

Renames a category from an old name to a new name. All items associated with the old category name are changed to reference the new category name after this method is invoked. If the new category name is already an existing category, then the items associated with the old category name are associated with the existing category.

A string with no characters ("") may or may not be a valid category on a particular platform. If the string is not a category on a platform, a PIMException is thrown when trying to rename a category to it.

Parameters:

currentCategory - a String representing the category to rename.

newCategory - a String representing the new category name to use.

Throws:

PIMException - If categories are unsupported, an error occurs, the list is no longer accessible or closed, or the category name is invalid.

SecurityException - if the application is not given permission to write to the PIM list or the list is opened READ_ONLY.

NullPointerException - if currentCategory or newCategory is null.

See Also:

PIMList.addCategory(String), PIMList.deleteCategory(String, boolean), PIMList.getCategories(), PIMList.isCategory(String), PIMList.maxCategories()

Since:

BlackBerry API 4.0.0

stringArraySize

int stringArraySize(int stringArrayField)

Returns the size of the array for the given string array field. Used for creating arrays for the string array field.

Parameters:

stringArrayField - The field which has a STRING_ARRAY data type, as defined by classes implementing the PIMItem interface, whose array size to return.

Returns:

the size of the array of a single data instance of a string array field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or not a string array field.

See Also:

PIMList.isSupportedField(int), PIMList.getFieldDataType(int)

Since:

BlackBerry API 4.0.0