javax.microedition.pim
Interface PIMList

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

public interface PIMList

Represnts a list of PIM items.

A PIMList contains PIMItem objects and maintains the list of valid fields for each item.

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

Since:
PDAP 1.0
See Also:
PIMItem, EventList, ToDoList, ContactList

Field Summary
static String UNCATEGORIZED
          Represents all PIM items which do not have an associated category.
 
Method Summary
 void addCategory(String category)
          Adds a category to the PIMList.
 void close()
          Closes this list, releasing it's resources to memory.
 void deleteCategory(String category, boolean deleteUnassignedItems)
          Removes a category from the PIMList.
 String getArrayElementLabel(int stringArrayField, int arrayElement)
          Returns the label associated with an element of a String array field.
 String getAttributeLabel(int attribute)
          Returns the label associated with an attribute.
 String[] getCategories()
          Returns a string array containing the names of all categories that are currently supported by this PIMList.
 int getFieldDataType(int field)
          Returns an integer representing the data type associated with this field.
 String getFieldLabel(int field)
          Returns the label associated with this field.
 String getName()
          Returns the name of the list.
 int[] getSupportedArrayElements(int stringArrayField)
          Returns an array of integers representing all supported elements of a string array for a given field.
 int[] getSupportedAttributes(int field)
          Returns an array containing the integer representations of all supported attributes for the specified field.
 int[] getSupportedFields()
          Returns an array of integers representing all fields that are supported in this list.
 boolean isCategory(String category)
          Returns a boolean indicating whether or not the specified category name is valid for this list.
 boolean isSupportedArrayElement(int stringArrayField, int arrayElement)
          Returns a boolean that indicates whether or not a given array element is supported by the specified field.
 boolean isSupportedAttribute(int field, int attribute)
          Returns a boolean indicating whether or not the specified attribute is supported in a given field within the list.
 boolean isSupportedField(int field)
          Returns a boolean indicating whether or not the specified field is supported.
 Enumeration items()
          Returns an enumeration of all items in the list.
 Enumeration items(PIMItem matching)
          Returns an enumeration of all items that match the fields contained within a specified PIMItem.
 Enumeration items(String matching)
          Returns an enumeration of all items that match the fields contained within a specified string.
 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 PIMList can have.
 int maxValues(int field)
          Returns an integer indicating whether or not a specified field can support multiple values.
 void renameCategory(String currentCategory, String newCategory)
          Renames an existing category.
 int stringArraySize(int stringArrayField)
          Returns the size of a string array for a given field.
 

Field Detail

UNCATEGORIZED

public static final String UNCATEGORIZED
Represents all PIM items which do not have an associated category.

See Also:
renameCategory(java.lang.String, java.lang.String)
Since:
JDE 4.0.0
Method Detail

addCategory

public void addCategory(String category)
                 throws PIMException
Adds a category to the PIMList.

If the specified name already exists in the list, the method call returns as though successful.

Parameters:
category - A string representing the name of a category.
Throws:
PIMException - Thrown if an error occurs with the list or if the list has already been closed.
Since:
JDE 4.0.0

close

public void close()
           throws PIMException
Closes this list, releasing it's resources to memory.

The list can no longer be accessed. Any attempts will result in a PIMExeption.

Throws:
PIMException - Thrown if the list has already been closed or if an error occurs.
Since:
JDE 4.0.0

deleteCategory

public void deleteCategory(String category,
                           boolean deleteUnassignedItems)
                    throws PIMException
Removes a category from the PIMList.

If the specified name does not already exist in the lists, the method call returns as though successful.

Parameters:
category - A string representing the name of an existing category.
deleteUnassignedItems - Determines whether or not to delete items which are left unassigned.
Throws:
PIMException - Thrown if an error occurs with the list or if the list has already been closed.
Since:
JDE 4.0.0

getArrayElementLabel

public String getArrayElementLabel(int stringArrayField,
                                   int arrayElement)
Returns the label associated with an element of a String array field.

The isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
stringArrayfield - An integer representing the String array field containing the element for which to return the label.
arrayElement - An integer representing the element in the String array for which to return the label.
Returns:
A string representing the label of the element in the String array field.
Since:
JDE 4.0.0

getAttributeLabel

public String getAttributeLabel(int attribute)
Returns the label associated with an attribute.

Parameters:
attribute - An integer representing the attribute for which to return the label.
Returns:
A string representing the label of the attribute.
Since:
JDE 4.0.0

getCategories

public String[] getCategories()
                       throws PIMException
Returns a string array containing the names of all categories that are currently supported by this PIMList.

If there are no associated categories, or if the list does not support categories, the array will be zero-length.

Returns:
An array containing the names of the categories associated with this list.
Since:
JDE 4.0.0

getFieldDataType

public int getFieldDataType(int field)
Returns an integer representing the data type associated with this field.

The isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - The field to check against.
Returns:
An integer representing the data type.
Since:
JDE 4.0.0

getFieldLabel

public String getFieldLabel(int field)
Returns the label associated with this field.

The isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the label.
Returns:
A string representing the label of the field.
Since:
JDE 4.0.0

getName

public String getName()
Returns the name of the list.

Returns:
A string representing the name of this list.
Since:
JDE 4.0.0

getSupportedArrayElements

public int[] getSupportedArrayElements(int stringArrayField)
Returns an array of integers representing all supported elements of a string array for a given field.

Parameters:
stringArrayField - The field to check.
Returns:
An array of integers containing the supported elements.
Since:
JDE 4.0.0

getSupportedAttributes

public int[] getSupportedAttributes(int field)
Returns an array containing the integer representations of all supported attributes for the specified field.

Parameters:
field - An integer representing the field to check.
Returns:
An array of integers representing the list of supported attributes.
Since:
JDE 4.0.0

getSupportedFields

public int[] getSupportedFields()
Returns an array of integers representing all fields that are supported in this list.

Returns:
An integer array containing the integer values of all fields that are supported in this list.
Since:
JDE 4.0.0

isCategory

public boolean isCategory(String category)
                   throws PIMException
Returns a boolean indicating whether or not the specified category name is valid for this list.

Parameters:
category - A string representing the name of a category.
Returns:
A boolean that indicates whether or not the specified string represents a valid category name. If true, the category name is valid, if false the category name is invalid.
Since:
JDE 4.0.0

isSupportedArrayElement

public boolean isSupportedArrayElement(int stringArrayField,
                                       int arrayElement)
Returns a boolean that indicates whether or not a given array element is supported by the specified field.

Parameters:
stringArrayField - The field to check.
arrayElement - The element in the array to check.
Returns:
True if the element is supported in the list, false otherwise.
Since:
JDE 4.0.0

isSupportedAttribute

public boolean isSupportedAttribute(int field,
                                    int attribute)
Returns a boolean indicating whether or not the specified attribute is supported in a given field within the list.

Parameters:
field - An integer representing a field in the list.
attribute - The attribute to check.
Returns:
A boolean that indicates whether or not the attribute is supported.
Since:
JDE 4.0.0

isSupportedField

public boolean isSupportedField(int field)
Returns a boolean indicating whether or not the specified field is supported.

Parameters:
field - An integer representing the field.
Returns:
A boolean that indicates whether or not this field is supported. Returns true if the field is supported, false otherwise.
Since:
JDE 4.0.0

items

public Enumeration items()
                  throws PIMException
Returns an enumeration of all items in the list.

Returns:
An enumeration containing the items in the list.
Throws:
PIMException - Thrown if an error occurs with the list, or the list has already been closed.
Since:
JDE 4.0.0

items

public Enumeration items(PIMItem matching)
                  throws PIMException
Returns an enumeration of all items that match the fields contained within a specified PIMItem.

The enumeration will contain items with fields that match those specified within the PIMItem argument, as well as any extra fields contained within the item. Only fields that have data associated with them will be used for matching.

The matching algorithm works as follows:

  • all data types, except Strings, must match values exactly.
  • For fields that contain string data values, each individual word is matched for the length of the sentence. Individual words are defined locale specific and are case insensitive. A match is found if the specified search string is found within a string of a PIMItem's data field at the correct element position. For example, the search string "name" will be found within the field "Contact Name" and "First name", but will not be found within the field "lastname".
Parameters:
matching - The PIMItem used for matching fields.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - Thrown if an error occurs with the list, or if the list has already been closed.
Since:
JDE 4.0.0

items

public Enumeration items(String matching)
                  throws PIMException
Returns an enumeration of all items that match the fields contained within a specified string.

The enumeration will contain items with fields that match those specified within the PIMitem argument, as well as any extra fields contained within the item. Only fields that have data associated with them will be used for matching.

The matching algorithm works as follows:

  • Individual words are defined locale specific and are case insensitive. For fields that contain string data values, a match is found if the specified search string is found anywhere within a string of a PIMItem's data field. For example, the search string "name" will be found within the field "Contact Name" and "First NAME", as well as within the field "lastname".
Parameters:
matching - The string used for matching fields.
Returns:
An enumeration containing any matched PIMItems.
Throws:
PIMException - Thrown if an error occurs with the list, or if the list has already been closed.
Since:
JDE 4.0.0

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

maxCategories

public int maxCategories()
Returns the maximum number of categories that this PIMList can have.

Returns:
An integer representing the maximum number of categories that can be associated with this list. A value of 0 indicates no category support. A value of -1 indicates unlimited category support.
Since:
JDE 4.0.0

maxValues

public int maxValues(int field)
Returns an integer indicating whether or not a specified field can support multiple values.

Parameters:
field - An integer representing the field to check.
Returns:
An integer representing the number of values supported by this field.
Since:
JDE 4.0.0

renameCategory

public void renameCategory(String currentCategory,
                           String newCategory)
                    throws PIMException
Renames an existing category.

All existing items within the current category will be changed to reference the new category. If the new category name matches a pre-existing category name, all references will be moved to the existing category.

Parameters:
currentCategory - The current category name.
newCategory - The new category name.
Throws:
PIMException - Thrown if an error occurs with the list, the category names are not found, or the list is no longer accessible.
Since:
JDE 4.0.0

stringArraySize

public int stringArraySize(int stringArrayField)
Returns the size of a string array for a given field.

Parameters:
stringArrayField - The field to check.
Returns:
The size of a field's string array
Since:
JDE 4.0.0



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