javax.microedition.pim
Interface PIMList

All Known Subinterfaces:

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.

PIMList maintain categories and fields. 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.

Since:

PIM 1.0

Field Summary

static java.lang.String

UNCATEGORIZED Constant for the itemsByCategory(java.lang.String) method to indicate to search for uncategorized items.

Method Summary

void	addCategory(java.lang.String category) Adds the provided category to the PIM list.
void	close() Closes the list, releasing any resources for this list.
void	deleteCategory(java.lang.String category, boolean deleteUnassignedItems) Deletes the indicated category from the PIM list.
java.lang.String	getArrayElementLabel(int stringArrayField, int arrayElement) Returns a String label associated with the given array element.
java.lang.String	getAttributeLabel(int attribute) Returns a String label associated with the given attribute.
java.lang.String[]	getCategories() Returns the categories defined for the PIM list.
int	getFieldDataType(int field) Returns an int representing the data type of the data associated with the given field.
java.lang.String	getFieldLabel(int field) Returns a String label associated with the given field.
java.lang.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(java.lang.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.
java.util.Enumeration	items() Return an Enumeration of all items in the list.
java.util.Enumeration	items(PIMItem matchingItem) Return an Enumeration of all items in the list that contain fields that match all of those fields specified in the given matching item.
java.util.Enumeration	items(java.lang.String matchingValue) Return an Enumeration of all items in the list that contain at least one String field data value that matches the string value provided.
java.util.Enumeration	itemsByCategory(java.lang.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(java.lang.String currentCategory, java.lang.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 java.lang.String UNCATEGORIZED

Constant for the itemsByCategory(java.lang.String) method to indicate to search for uncategorized items. The value null is assigned to the string UNCATEGORIZED.

Method Detail

getName

public java.lang.String getName()

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

Returns:

a String representation of the list name.

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.

Throws:

PIMException - If the list is no longer accessible.

items

public java.util.Enumeration items()
                            throws PIMException

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

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

items

public java.util.Enumeration items(PIMItem matchingItem)
                            throws PIMException

Return 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 is not used and 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 maching 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 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:

matchingItem - 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 contains fields that match all of the fields of the item parameter.

Throws:

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

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

java.lang.NullPointerException - if matching is null.

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

items

public java.util.Enumeration items(java.lang.String matchingValue)
                            throws PIMException

Return an Enumeration of all items in the list that contain at least one String field data value that matches the string value provided. 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). 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 matching item NOTE field is set to "pho", a positive match occurs in the strings "Mobile phone" and "THIS IS A PHONE NOTE" as well as in 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.

Parameters:

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

java.lang.NullPointerException - if matching is null.

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

itemsByCategory

public java.util.Enumeration itemsByCategory(java.lang.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 an String.equals() comparison.

Parameters:

category - A string category to find matching items with.

Returns:

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

Throws:

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

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

getCategories

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

isCategory

public boolean isCategory(java.lang.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 for.

Returns:

true if the category indicated is a valid existing category for this list, false otherwise.

Throws:

java.lang.NullPointerException - if category is null.

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

addCategory

public void addCategory(java.lang.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 is thrown when trying to add it.

Parameters:

category - a String representing a category to add.

Throws:

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

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

java.lang.NullPointerException - if category is null.

deleteCategory

public void deleteCategory(java.lang.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 category.

deleteUnassignedItems - boolean flag where true indicates to delete items that no longer have any categories assigned to them as a result of this method, and where false indicates that 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.

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

java.lang.NullPointerException - if category is null.

renameCategory

public void renameCategory(java.lang.String currentCategory,
                           java.lang.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 - String representing the current category name.

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

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

java.lang.NullPointerException - if currentCategory or newCategory is null.

maxCategories

public int maxCategories()

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

Returns:

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

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 supported in this list, false otherwise. Invalid fields return false.

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

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 supported, false otherwise. Invalid fields and invalid attributes return false.

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 to check

Returns:

an int array of the supported attributes, one attribute per entry in the array. If there are no supported fields, a zero-length array is returned.

Throws:

java.lang.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.

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 supported in this list, false otherwise. Invalid fields and invalid array elements return false.

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 to check

Returns:

an int array representing the supported array elements, one array element per entry in the array. If there are no supported array elements, a zero-length array is returned.

Throws:

java.lang.IllegalArgumentException - if field is not a valid StringArray 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.

getFieldDataType

public int getFieldDataType(int field)

Returns an int representing 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:

int representing the type of the data associated with the field.

Throws:

java.lang.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.

getFieldLabel

public java.lang.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:

java.lang.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.

getAttributeLabel

public java.lang.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:

java.lang.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.

getArrayElementLabel

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

arrayElement - The element in the array, 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:

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

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

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 to check for multiple value support.

Returns:

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

Throws:

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

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 string array field for which its array size is returned.

Returns:

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

Throws:

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