pimlist.html

J2ME手机编程规范JSR-75文档

 <li>
 Comparisons for matching begins at the start of each separate word in the
 String being examined, continuing for the length of the search string
 value.
 </li><li>
 Word separation is locale dependent (for Latin based languages
 separation is defined as any character other than alphanumeric).
 </li><li>
 Comparisons are case insensitive.
 </li><li>
 A match is positive if the string
 value is contained within the compared against String value starting at
 the word position presently set. 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" but not in the string
 "telephone".
 </li><li>
 If an empty string is provided in the matching item
 (i.e. String("")), the empty string matches all set values for the field.
 </li></ul>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>matchingValue</CODE> - a string value to which all set String field
           values are compared.
<DT><B>Returns:</B><DD>an enumeration of all items that contain at least one field
           that matches the string parameter.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If an error occurs or the list is no longer
           accessible or closed.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>matching</code> is <code>null</code>.
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
           permission to read the PIM list or the list is opened
           WRITE_ONLY.</DL>
</DD>
</DL>
<HR>

<A NAME="itemsByCategory(java.lang.String)"><!-- --></A><H3>
itemsByCategory</H3>
<PRE>
public java.util.Enumeration <B>itemsByCategory</B>(java.lang.String&nbsp;category)
                                      throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
<DL>
<DD>Returns an enumeration of all items in the PIM list that match the
 provided category.
 </P><P>
 Category matching rules:
 <ul>
 <li>A PIM list item that contains the given category will be in the
 returned enumeration.</li>
 <li>A category string that matches none of the categories of the items
 in the PIM list will return an empty enumeration.</li>
 <li>The category string <code>UNCATEGORIZED</code> will return an
 enumeration of all PIM items of the PIM list that have no category
 assignments.</li>
 <li>A null category string is equivalent to the category string
 <code>UNCATEGORIZED</code>.</li>
 <li>An empty category string <code>""</code> is considered a valid string
 parameter for comparison with existing categories, e.g. "" will match
 only a category also named "".</li>
 <li>The full category string is used for comparison, and must return
 true for an <code>String.equals()</code> comparison.</li>
 </ul>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>category</CODE> - A string category to find matching items with.
<DT><B>Returns:</B><DD>An enumeration of all items in the PIM list that match the
          category.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If an error occurs or the list is no longer
          accessible or closed.
<DD><CODE>java.lang.SecurityException</CODE> - If the application is not given permission to
          read the PIM list or the list is opened
          WRITE_ONLY.</DL>
</DD>
</DL>
<HR>

<A NAME="getCategories()"><!-- --></A><H3>
getCategories</H3>
<PRE>
public java.lang.String[] <B>getCategories</B>()</PRE>
<DL>
<DD>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.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>A string array containing the categories defined for the
           PIM list.</DL>
</DD>
</DL>
<HR>

<A NAME="isCategory(java.lang.String)"><!-- --></A><H3>
isCategory</H3>
<PRE>
public boolean <B>isCategory</B>(java.lang.String&nbsp;category)</PRE>
<DL>
<DD>Returns indication of whether the given category is a valid existing
 category for this list.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String representing the category to query for.
<DT><B>Returns:</B><DD>true if the category indicated is a valid existing category for
          this list, false otherwise.
<DT><B>Throws:</B>
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is
          <code>null</code>.</DL>
</DD>
</DL>
<HR>

<A NAME="addCategory(java.lang.String)"><!-- --></A><H3>
addCategory</H3>
<PRE>
public void <B>addCategory</B>(java.lang.String&nbsp;category)
                 throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
<DL>
<DD>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.
 </P><P>
 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.
 </P><P>
 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 will be thrown when trying to add it.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String representing a category to add.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - 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.
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
           permission to write to the PIM list or the list is opened
           READ_ONLY.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is
           <code>null</code>.</DL>
</DD>
</DL>
<HR>

<A NAME="deleteCategory(java.lang.String, boolean)"><!-- --></A><H3>
deleteCategory</H3>
<PRE>
public void <B>deleteCategory</B>(java.lang.String&nbsp;category,
                           boolean&nbsp;deleteUnassignedItems)
                    throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
<DL>
<DD>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.
 <p>
 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.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>category</CODE> - a String category.<DD><CODE>deleteUnassignedItems</CODE> - 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.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If categories are unsupported, an error occurs,
           or the list is no longer accessible or closed.
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
           permission to write to the PIM list or the list is opened
           READ_ONLY.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>category</code> is
           <code>null</code>.</DL>
</DD>
</DL>
<HR>

<A NAME="renameCategory(java.lang.String, java.lang.String)"><!-- --></A><H3>
renameCategory</H3>
<PRE>
public void <B>renameCategory</B>(java.lang.String&nbsp;currentCategory,
                           java.lang.String&nbsp;newCategory)
                    throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
<DL>
<DD>Renames a category from an old name to a new name.  All items associated
 with the old category name will be 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 will be associated with the existing category.
 </P><P>
 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 will be thrown when trying to rename a category to it.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>currentCategory</CODE> - String representing the current category name.<DD><CODE>newCategory</CODE> - String representing the new category name to use.
<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - If categories are unsupported, an error occurs,
          the list is no longer accessible or closed, or the category
          name is invalid.
<DD><CODE>java.lang.SecurityException</CODE> - if the application is not given
          permission to write to the PIM list or the list is opened
          READ_ONLY.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>currentCategory</code> or
          <code>newCategory</code> is <code>null</code>.</DL>
</DD>
</DL>
<HR>

<A NAME="maxCategories()"><!-- --></A><H3>
maxCategories</H3>
<PRE>
public int <B>maxCategories</B>()</PRE>
<DL>
<DD>Returns the maximum number of categories that this list can have.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>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.</DL>
</DD>
</DL>
<HR>

<A NAME="isSupportedField(int)"><!-- --></A><H3>
isSupportedField</H3>
<PRE>
public boolean <B>isSupportedField</B>(int&nbsp;field)</PRE>
<DL>
<DD>Indicates whether or not the given field is supported in this PIM list.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field to check, as defined by in the class
           implementing the PIMItem.
<DT><B>Returns:</B><DD>true if supported in this list, false otherwise.  Invalid fields
           return false.</DL>
</DD>
</DL>
<HR>

<A NAME="getSupportedFields()"><!-- --></A><H3>
getSupportedFields</H3>
<PRE>
public int[] <B>getSupportedFields</B>()</PRE>
<DL>
<DD>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.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>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.</DL>
</DD>
</DL>
<HR>

<A NAME="isSupportedAttribute(int, int)"><!-- --></A><H3>
isSupportedAttribute</H3>
<PRE>