pimitem.html

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

<DT><B>Returns:</B><DD>the PIMList that this item belongs to.  If the item does
           not belong to any list, <code>null</code> is returned.</DL>
</DD>
</DL>
<HR>

<A NAME="commit()"><!-- --></A><H3>
commit</H3>
<PRE>
public void <B>commit</B>()
            throws <A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></PRE>
<DL>
<DD>This method persists the data in the item to its PIM list.
 As data is changed in an item through other methods in this class,
 the data is not immediately written to the underlying data storage for
 the list.  This method commits that data to the underlying data storage
 for the list.
 <p>
 Some devices may not allow categories in the item to be persisted
 which are not in the list returned from <A HREF="../../../javax/microedition/pim/PIMList.html#getCategories()"><CODE>PIMList.getCategories()</CODE></A>.
 In this case the categories will be dropped silently when this method
 is invoked (this allows data imported using <A HREF="../../../javax/microedition/pim/PIM.html#fromSerialFormat(java.io.InputStream, java.lang.String)"><CODE>PIM.fromSerialFormat(java.io.InputStream, java.lang.String)</CODE></A>
 to be persisted).
 </p><p>
 Also note that some field values may be altered during the commit to fit
 platform restrictions.  A common example of this is Date fields.  If a
 platform does not support storing its Date values with millisecond
 granularity, the platform will round-down the given Date value to its
 nearest value supported by the platform.
 </p>
<P>
<DD><DL>

<DT><B>Throws:</B>
<DD><CODE><A HREF="../../../javax/microedition/pim/PIMException.html">PIMException</A></CODE> - if the commit encounters an error and cannot
           complete.  Also thrown if the item does not belong to any
           list, or the list is closed or inaccessible.
<DD><CODE>java.lang.SecurityException</CODE> - if the application has not been granted
           write access to the PIM list or the list is opened READ_ONLY.</DL>
</DD>
</DL>
<HR>

<A NAME="isModified()"><!-- --></A><H3>
isModified</H3>
<PRE>
public boolean <B>isModified</B>()</PRE>
<DL>
<DD>This method returns a boolean indicating whether any of this item's
 fields have been modified since the item was retrieved or last
 committed.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>boolean true if any fields have been modified since the
           item was last retrieved or committed, false otherwise.</DL>
</DD>
</DL>
<HR>

<A NAME="getFields()"><!-- --></A><H3>
getFields</H3>
<PRE>
public int[] <B>getFields</B>()</PRE>
<DL>
<DD>Returns all fields in the item that have data stored for them.
 This allows quick access to all of the data stored in the item without
 having to iterate through all supported fields and checking if data
 is stored for the field or not.
<P>
<DD><DL>

<DT><B>Returns:</B><DD>int array of fields that have data currently stored for them.
           If no fields contain data, a zero length array is returned.</DL>
</DD>
</DL>
<HR>

<A NAME="getBinary(int, int)"><!-- --></A><H3>
getBinary</H3>
<PRE>
public byte[] <B>getBinary</B>(int&nbsp;field,
                        int&nbsp;index)</PRE>
<DL>
<DD>Get a binary data value for a field from the item.
 <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> should be used to verify the field
 validity for this item prior to invoking this method.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field from which the data is retrieved.<DD><CODE>index</CODE> - an index to a particular value associated with the field.
<DT><B>Returns:</B><DD>a byte array representing a value for the field.
           The value is an inline binary data representation
           in a "B" binary encoded string as defined by [IETF RFC 2047].
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the field is not valid
           for the implementing class.
<DD><CODE>java.lang.IndexOutOfBoundsException</CODE> - if the index is negative or greater
           than or equal to the number of values currently contained in the
           field.
<DD><CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE> - if the field is not supported in
           the implementing instance of the class.</DL>
</DD>
</DL>
<HR>

<A NAME="addBinary(int, int, byte[], int, int)"><!-- --></A><H3>
addBinary</H3>
<PRE>
public void <B>addBinary</B>(int&nbsp;field,
                      int&nbsp;attributes,
                      byte[]&nbsp;value,
                      int&nbsp;offset,
                      int&nbsp;length)</PRE>
<DL>
<DD>Adds a binary data value to a field in the item.  The value is
 appended as the last data value in the field's array, similar to
 <code>Vector.addElement</code>.
 <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> should be used to verify the field
 validity for this item prior to invoking this method.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field to which the value belongs.<DD><CODE>attributes</CODE> - a bit array specifying any optional attributes
           describing this value.  These attributes are a hint to the
           about the value's characteristics and some or all may be ignored
           by this method due to platform restrictions.  Attributes
           that are invalid or not applicable are also ignored.<DD><CODE>value</CODE> - The data to add to the field. The
           data is an inline binary data representation and must be in
           a "B" binary encoded string as defined by [IETF RFC 2047].<DD><CODE>offset</CODE> - int indicating the offset into the provided byte array
           from where to start reading the binary data.<DD><CODE>length</CODE> - int indicating the number of bytes to read from starting
           from the offset in the byte array.
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the field is not valid
           for the implementing class.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>value</code> is <code>null</code>.
<DD><CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE> - if the field is not supported in
           the implementing instance of the class.
<DD><CODE><A HREF="../../../javax/microedition/pim/FieldFullException.html">FieldFullException</A></CODE> - if the field already contains the maximum
           number of data values it can hold.</DL>
</DD>
</DL>
<HR>

<A NAME="setBinary(int, int, int, byte[], int, int)"><!-- --></A><H3>
setBinary</H3>
<PRE>
public void <B>setBinary</B>(int&nbsp;field,
                      int&nbsp;index,
                      int&nbsp;attributes,
                      byte[]&nbsp;value,
                      int&nbsp;offset,
                      int&nbsp;length)</PRE>
<DL>
<DD>Sets an existing binary data value in a field to a new value.  The value
 located at the provided index is set, similar to
 <code>Vector.setElementAt</code>.  This method cannot be used to add new
 values to a field; use <A HREF="../../../javax/microedition/pim/PIMItem.html#addBinary(int, int, byte[], int, int)"><CODE>addBinary(int, int, byte[], int, int)</CODE></A>.
 <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> should be used to verify the field
 validity for this item prior to invoking this method.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field to which the value belongs.<DD><CODE>index</CODE> - an index to a particular value associated with the field.<DD><CODE>attributes</CODE> - a bit array specifying any optional attributes
           describing this value.  These attributes are a hint to the
           about the value's characteristics and some or all may be ignored
           by this method due to platform restrictions.  Attributes
           that are invalid or not applicable are also ignored.<DD><CODE>value</CODE> - The new value of the data at the field's index. The
           data is an inline binary data representation and must be in
           a "B" binary encoded string as defined by [IETF RFC 2047].<DD><CODE>offset</CODE> - int indicating the offset into the provided byte array
           from where to start reading the binary data.<DD><CODE>length</CODE> - int indicating the number of bytes to read from starting
           from the offset in the byte array.
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the field is not valid
           for the implementing class.
<DD><CODE>java.lang.NullPointerException</CODE> - if <code>value</code> is <code>null</code>.
<DD><CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE> - if the field is not supported in
           the implementing instance of the class.
<DD><CODE>java.lang.IndexOutOfBoundsException</CODE> - if the index is negative or greater
           than or equal to the number of values currently contained in the
           field.</DL>
</DD>
</DL>
<HR>

<A NAME="getDate(int, int)"><!-- --></A><H3>
getDate</H3>
<PRE>
public long <B>getDate</B>(int&nbsp;field,
                    int&nbsp;index)</PRE>
<DL>
<DD>Get a date value from a field in the item.
 <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> should be used to verify the field
 validity for this item prior to invoking this method.
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field from which the data will be retrieved.<DD><CODE>index</CODE> - an index to a particular value associated with the field.
<DT><B>Returns:</B><DD>a date representing a value of the field, returned in the same
           long format as java.util.Date, which is
           milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the field is not valid
           for the implementing class.
<DD><CODE>java.lang.IndexOutOfBoundsException</CODE> - if the index is negative or greater
           than or equal to the number of values currently contained in the
           field.
<DD><CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE> - if the field is not supported in
           the implementing instance of the class.</DL>
</DD>
</DL>
<HR>

<A NAME="addDate(int, int, long)"><!-- --></A><H3>
addDate</H3>
<PRE>
public void <B>addDate</B>(int&nbsp;field,
                    int&nbsp;attributes,
                    long&nbsp;value)</PRE>
<DL>
<DD>Adds a date value to a field in the item. The value is
 appended as the last data value in the field's array, similar to
 <code>Vector.addElement</code>.
 <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> should be used to verify the field
 validity for this item prior to invoking this method.
 </P><P>
 Note that the value provided may be rounded-down by an implementation due
 to platform restrictions.  For example, should a native PIM database on
 support date values with granularity in terms of seconds, then the
 provided date value will be rounded down to the nearest second.
 </p>
<P>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>field</CODE> - The field to which the value belongs.<DD><CODE>attributes</CODE> - a bit array specifying any optional attributes
           describing this value.  These attributes are a hint to the
           about the value's characteristics and some or all may be ignored
           by this method due to platform restrictions.  Attributes
           that are invalid or not applicable are also ignored.<DD><CODE>value</CODE> - The data to add to the field. The date must be expressed
           in the same long value format as java.util.Date, which is
           milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
<DT><B>Throws:</B>
<DD><CODE>java.lang.IllegalArgumentException</CODE> - if the field is not valid
           for the implementing class.
<DD><CODE><A HREF="../../../javax/microedition/pim/UnsupportedFieldException.html">UnsupportedFieldException</A></CODE> - if the field is not supported in
           the implementing instance of the class.
<DD><CODE><A HREF="../../../javax/microedition/pim/FieldFullException.html">FieldFullException</A></CODE> - if the field already contains the maximum
           number of data values it can hold.</DL>
</DD>
</DL>
<HR>

<A NAME="setDate(int, int, int, long)"><!-- --></A><H3>
setDate</H3>
<PRE>
public void <B>setDate</B>(int&nbsp;field,
                    int&nbsp;index,
                    int&nbsp;attributes,
                    long&nbsp;value)</PRE>
<DL>
<DD>Sets an existing date data value in a field to a new value.  The value
 located at the provided index is set, similar to
 <code>Vector.setElementAt</code>. This method cannot be used to add new