javax.microedition.pim
Interface PIMList

All Known Subinterfaces:
BlackBerryContactList, BlackBerryEventList, BlackBerryMemoList, BlackBerryPIMList, BlackBerryToDoList, ContactList, EventList, ToDoList

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 casted 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:
PIM 1.0

Field Summary
static String UNCATEGORIZED
          Constant for the 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(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 items(String matching)
          Return an Enumeration of items with String field data that contains the matching string argument.
 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

public static final String UNCATEGORIZED
Constant for the itemsByCategory(String) method to indicate to search for uncategorized items. The value of this constant is null.
Since:
JDE 4.0.0
Method Detail

addCategory

public 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.
Since:
JDE 4.0.0
See Also:
deleteCategory(String, boolean), renameCategory(String, String), getCategories(), isCategory(String), maxCategories()

close

public 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. This method may be invoked multiple times; however, all invocations after the first invocation do nothing.
Throws:
PIMException - If the list is no longer accessible.
Since:
JDE 4.0.0

deleteCategory

public 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.
Since:
JDE 4.0.0
See Also:
addCategory(String), renameCategory(String, String), getCategories(), isCategory(String), maxCategories()

getArrayElementLabel

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

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.
Since:
JDE 4.0.0
See Also:
getSupportedArrayElements(int), isSupportedArrayElement(int, int)

getAttributeLabel

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

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.
Since:
JDE 4.0.0
See Also:
isSupportedAttribute(int, int), getSupportedAttributes(int)

getCategories

public 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.
Since:
JDE 4.0.0
See Also:
addCategory(String), deleteCategory(String, boolean), renameCategory(String, String), isCategory(String), maxCategories()

getFieldDataType

public int getFieldDataType(int field)
Returns the data type of the data associated with the given field. This method is useful for platform extended fields. 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.
Since:
JDE 4.0.0
See Also:
isSupportedField(int), getSupportedFields(), maxValues(int)

getFieldLabel

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

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.
Since:
JDE 4.0.0
See Also:
getSupportedFields(), isSupportedField(int)

getName

public 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.
Since:
JDE 4.0.0
See Also:
PIM.listPIMLists(int), PIM.openPIMList(int, int, String)

getSupportedArrayElements

public 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.
Since:
JDE 4.0.0
See Also:
getArrayElementLabel(int, int), isSupportedArrayElement(int, int)

getSupportedAttributes

public 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.
Since:
JDE 4.0.0
See Also:
getAttributeLabel(int), isSupportedAttribute(int, int)

getSupportedFields

public 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.
Since:
JDE 4.0.0
See Also:
getFieldLabel(int), isSupportedField(int), maxValues(int)

isCategory

public 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.
Since:
JDE 4.0.0
See Also:
addCategory(String), deleteCategory(String, boolean), renameCategory(String, String), getCategories(), maxCategories()

isSupportedArrayElement

public 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.
Since:
JDE 4.0.0
See Also:
getArrayElementLabel(int, int), getSupportedArrayElements(int)

isSupportedAttribute

public 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.
Since:
JDE 4.0.0
See Also:
getAttributeLabel(int), getSupportedAttributes(int)

isSupportedField

public 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.
Since:
JDE 4.0.0
See Also:
getSupportedFields(), getFieldLabel(int), getFieldDataType(int), maxValues(int)

items

public 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.
Since:
JDE 4.0.0
See Also:
items(PIMItem), items(String), itemsByCategory(String)

items

public 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 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.
    Since:
    JDE 4.0.0
    See Also:
    items(), items(String), itemsByCategory(String)

items

public 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 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.
    Since:
    JDE 4.0.0
    See Also:
    items(), items(PIMItem), itemsByCategory(String)

itemsByCategory

public 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 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.
    Since:
    JDE 4.0.0
    See Also:
    items(), items(PIMItem), items(String)

maxCategories

public 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.
Since:
JDE 4.0.0
See Also:
addCategory(String), deleteCategory(String, boolean), renameCategory(String, String), getCategories(), isCategory(String)

maxValues

public 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.
Since:
JDE 4.0.0
See Also:
getSupportedFields(), isSupportedField(int), getFieldDataType(int)

renameCategory

public 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.
Since:
JDE 4.0.0
See Also:
addCategory(String), deleteCategory(String, boolean), getCategories(), isCategory(String), maxCategories()

stringArraySize

public 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.
Since:
JDE 4.0.0
See Also:
isSupportedField(int), getFieldDataType(int)



Copyright 1999-2009 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.