PDAP Public Review Draft

javax.microedition.pim
Interface PIMList

All Known Subinterfaces:
ContactList, EventList, ToDoList

public interface PIMList

Represents the common functionality of a PIM list.

Since:
PDAP 1.0

Method Summary
 void addCategory(java.lang.String category)
          Adds the provided category to the PIM database.
 void close()
          Closes the list, releasing any resources for this list.
 void deleteCategory(java.lang.String category)
          Deletes the indicated category from the PIM database.
 Enumeration elements()
          Return an Enumeration of all elements in the list.
 Enumeration elements(PIMElement matching)
          Return an Enumeration of all elements in the list which match all of the fields specified in the element parameter.
 java.lang.String[] getCategories()
          Returns the categories defined for the PIM database.
 int[] getSupportedFields()
          Returns an int array containing all field IDs supported by this list.
 int[] getSupportedTypes(int fieldID)
          Returns an integer array containing the supported type ids for the given field ID.
 boolean isExtendedField(int fieldID)
          Indicates whether or not the given fieldID is an extended field or not.
 boolean isSupportedField(int fieldID)
          Indicates whether or not the given fieldID is supported in this PIM list.
 int maxCategories()
          Returns the maximum number of categories that this list can have.
 

Method Detail

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.

elements

public Enumeration elements()
                     throws PIMException
Return an Enumeration of all elements in the list. The order is undefined.
Returns:
an Enumeration of all elements.
Throws:
PIMException - If an error occurs or the list is no longer accessible or closed.

elements

public Enumeration elements(PIMElement matching)
                     throws PIMException
Return an Enumeration of all elements in the list which match all of the fields specified in the element parameter.
Matching is done with following rules and can be locale dependent: For fields that store Strings as values, matching is free from beginning of words and case insensitive. Word separation is defined as any character other than alphanumeric.
Example: If the matching element NOTE field is set to "pho", a positive match occurs, for example, in "Mobile phone" but not "telephone".
All the other data types match data values exactly (i.e. equals()).
Parameters:
matching - the Element to match
Returns:
an Enumeration of all Elements which match the fields of the element parameter.
Throws:
PIMException - If an error occurs or the list is no longer accessible or closed.
java.lang.IllegalArgumentException - If the Element is an illegal subclass for the appropriate list.

getCategories

public java.lang.String[] getCategories()
                                 throws PIMException
Returns the categories defined for the PIM database. If there are no categories defined for the PIM database, then a zero length array is returned.
Returns:
A string array containing the categories defined by the native PIM database.
Throws:
PIMException - If categories are unsupported,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 database. The category names in the javax.microedition.pim package are case sensitive.
Parameters:
a - String representing a category.
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.

deleteCategory

public void deleteCategory(java.lang.String category)
                    throws PIMException
Deletes the indicated category from the PIM database. If the indicated category is not in the PIM database, this method is treated as successfully completing. The category names are case sensitive in the javax.microedition.pim package. Elements within the deleted category are also deleted from the list.
Parameters:
a - String category.
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.

maxCategories

public int maxCategories()
                  throws PIMException
Returns the maximum number of categories that this list can have. 0 indicates no category support. -1 indicates there is no limit to the 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.
Throws:
PIMException - if the list is no longer accessible or closed.

isSupportedField

public boolean isSupportedField(int fieldID)
                         throws PIMException
Indicates whether or not the given fieldID is supported in this PIM list.
Parameters:
fieldID - The fieldID to check, as defined by the PIMElement subclasses.
Returns:
true if supported, false otherwise.
Throws:
java.lang.IllegalArgumentException - if fieldID is an invalid ID for this list.
PIMException - if the list is closed or is no longer accessible.

isExtendedField

public boolean isExtendedField(int fieldID)
                        throws PIMException
Indicates whether or not the given fieldID is an extended field or not. Extended fields are fields that are supported by the underlying list, but do not used a standard field ID defined in the PIM API. Extended fields are list implementation dependent and can vary across lists.
Parameters:
fieldID - The fieldID to check, as defined by the PIMElement subclasses.
Returns:
true if an extended field, false otherwise.
Throws:
java.lang.IllegalArgumentException - if fieldID is an invalid ID for this list.
PIMException - if the list is closed or is no longer accessible.

getSupportedFields

public int[] getSupportedFields()
                         throws PIMException
Returns an int array containing all field IDs supported by this list.
Throws:
PIMException - if the list is closed or is no longer accessible.

getSupportedTypes

public int[] getSupportedTypes(int fieldID)
                        throws PIMException
Returns an integer array containing the supported type ids for the given field ID. Some field IDs may have types associated with them to distinguish between different types of the same field. If there are no types to return, a zero length array is returned.
Parameters:
fieldID - the fieldID to check
Throws:
java.lang.IllegalArgumentException - if fieldID is is not one of the the valid field IDs for the implementing class.
PIMException - if the list is closed or is no longer accessible.

PDAP 1.0 Spec, Rev. 0.16