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:


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:


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:


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





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.