SHOW Signed

net.rim.blackberry.api.pim
Interface PIMList

All Known Subinterfaces:

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 list that match the specified 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.

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)

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

getName

public String getName()

Returns the name of the list.

Returns:

A string representing the name of this list.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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:

• 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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

getCategories

public String[] getCategories()

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

isCategory

public boolean isCategory(String category)

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

itemsByCategory

public Enumeration itemsByCategory(String category)
                            throws PIMException

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.