net.rim.blackberry.api.pim
Interface PIMList

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

Deprecated. In favour of PIMList.

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

Field Detail

UNCATEGORIZED

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

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

getName

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

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

close

public void close()
           throws PIMException
Deprecated. 
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 3.6.0

items

public Enumeration items()
                  throws PIMException
Deprecated. 
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 3.6.0

items

public Enumeration items(PIMItem matching)
                  throws PIMException
Deprecated. 
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.2

items

public Enumeration items(String matching)
                  throws PIMException
Deprecated. 
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:

  • 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 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.2

getCategories

public String[] getCategories()
Deprecated. 
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 3.6.0

isCategory

public boolean isCategory(String category)
Deprecated. 
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.2

addCategory

public void addCategory(String category)
                 throws PIMException
Deprecated. 
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.2

deleteCategory

public void deleteCategory(String category,
                           boolean deleteUnassignedItems)
                    throws PIMException
Deprecated. 
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.2

maxCategories

public int maxCategories()
Deprecated. 
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 3.6.0

isSupportedField

public boolean isSupportedField(int field)
Deprecated. 
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.2

getSupportedFields

public int[] getSupportedFields()
Deprecated. 
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 3.6.0

getFieldLabel

public String getFieldLabel(int field)
Deprecated. 
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.2

getArrayElementLabel

public String getArrayElementLabel(int stringArrayField,
                                   int arrayElement)
Deprecated. 
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.2

getAttributeLabel

public String getAttributeLabel(int attribute)
Deprecated. 
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.2

getFieldDataType

public int getFieldDataType(int field)
Deprecated. 
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.2

isSupportedAttribute

public boolean isSupportedAttribute(int field,
                                    int attribute)
Deprecated. 
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.2

getSupportedAttributes

public int[] getSupportedAttributes(int field)
Deprecated. 
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.2

maxValues

public int maxValues(int field)
Deprecated. 
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.2

getSupportedArrayElements

public int[] getSupportedArrayElements(int stringArrayField)
Deprecated. 
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.2

isSupportedArrayElement

public boolean isSupportedArrayElement(int stringArrayField,
                                       int arrayElement)
Deprecated. 
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.2

itemsByCategory

public Enumeration itemsByCategory(String category)
                            throws PIMException
Deprecated. 
Returns an enumeration of all items in the list that match the specified category.

  • A PIM item that matches the specified category will be returned within an enumeration.
  • An empty enumeration will be returned if the specified category does not match an existing PIM list category.
  • The specified category "UNCATEGORIZED" will return an enumeration of all uncategorized elements within a PIM list.
  • The specified category string must be matched entirely. That is, a comparison using String.equals() must return true in order to make a match.

Parameters:
category - The category to match.
Returns:
An enumeration of all items that match the specified category.
Throws:
PIMException - Thrown if an error occurs with the list, or if the list is no longer accessisble.
Since:
JDE 4.0.2

renameCategory

public void renameCategory(String currentCategory,
                           String newCategory)
                    throws PIMException
Deprecated. 
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.2

stringArraySize

public int stringArraySize(int stringArrayField)
                    throws IllegalArgumentException
Deprecated. 
Since:
JDE 4.0.2


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