📄 pimitem.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN""http://www.w3.org/TR/REC-html40/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<!-- Generated by javadoc on Mon Feb 10 18:18:40 PST 2003 -->
<TITLE>
PIMItem (PIM Optional Package 1.0 Spec, Proposed Final Draft)
</TITLE>
<META NAME="keywords" CONTENT="javax.microedition.pim.PIMItem,PIMItem interface">
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../stylesheet.css" TITLE="Style">
</HEAD>
<SCRIPT>
function asd()
{
parent.document.title="PIMItem (PIM Optional Package 1.0 Spec, Proposed Final Draft)";
}
</SCRIPT>
<BODY BGCOLOR="white" onload="asd();">
<!-- ========== START OF NAVBAR ========== -->
<A NAME="navbar_top"><!-- --></A><TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0">
<TR>
<TD COLSPAN=3 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A><TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A> </TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> <FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A> </TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A> </TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
PIM Optional Package 1.0<br>Proposed Final Draft</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../javax/microedition/pim/EventList.html"><B>PREV CLASS</B></A>
<A HREF="../../../javax/microedition/pim/PIMList.html"><B>NEXT CLASS</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../index.html" TARGET="_top"><B>FRAMES</B></A>
<A HREF="PIMItem.html" TARGET="_top"><B>NO FRAMES</B></A>
<SCRIPT> <!-- if(window==top) { document.writeln('<A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A>'); } //--></SCRIPT><NOSCRIPT><A HREF="../../../allclasses-noframe.html" TARGET=""><B>All Classes</B></A></NOSCRIPT></FONT></TD>
</TR>
<TR>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
SUMMARY: NESTED | <A HREF="#field_summary">FIELD</A> | CONSTR | <A HREF="#method_summary">METHOD</A></FONT></TD>
<TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
DETAIL: <A HREF="#field_detail">FIELD</A> | CONSTR | <A HREF="#method_detail">METHOD</A></FONT></TD>
</TR>
</TABLE>
<!-- =========== END OF NAVBAR =========== -->
<HR>
<!-- ======== START OF CLASS DATA ======== -->
<H2>
<FONT SIZE="-1">
javax.microedition.pim</FONT>
<BR>
Interface PIMItem</H2>
<DL>
<DT><B>All Known Subinterfaces:</B> <DD><A HREF="../../../javax/microedition/pim/Contact.html">Contact</A>, <A HREF="../../../javax/microedition/pim/Event.html">Event</A>, <A HREF="../../../javax/microedition/pim/ToDo.html">ToDo</A></DD>
</DL>
<HR>
<DL>
<DT>public interface <B>PIMItem</B></DL>
<P>
Represents the common interfaces of an item for a PIM list. A PIM item represents a collection of data for a single PIM entry. A PIM item is created from a particular PIM list and is associated with that list for the life of the item. PIM items can have its data imported and exported using standard byte based formats. Each implementing class defines what formats can be imported and exported for that item. </p> <H3>Fields</H3> <P>PIMItems reference its data through <i>fields</i>. A field is a grouping of data values that all have similar characteristics. An example of a field is TEL, which indicates data values for that particular field are telephone numbers. Classes implementing the PIMItem interface defines the possible fields that for that specific class (e.g TEL is defined in the <code>Contact</code> interface as a field that a contact may support). </P><P> PIM implementations are not required to support all of the possible fields defined in the classes implementing the PIMItem interface. This is because no native PIM databases contain all of the fields defined in this API. The PIMList that a PIMItem belongs to determines what fields a PIMItem can support and store (all PIMItems in a particular PIMList support the same set of fields). The <A HREF="../../../javax/microedition/pim/PIMList.html#getSupportedFields()"><CODE>PIMList.getSupportedFields()</CODE></A> method from a particular PIMItem's PIMList is used to find out what fields are supported within this item. Since not all possible fields are actually supported in a particular PIMItem, <B>all fields should be checked for support in the item's PIMList using <A HREF="../../../javax/microedition/pim/PIMList.html#isSupportedField(int)"><CODE>PIMList.isSupportedField(int)</CODE></A> prior to being used in any retrieval or storage method.</B> </p><p> Each field has the following pieces of information available for it: <UL> <LI>Zero or more <i>data values</I> associated with the Field <LI><i>Attributes</I> for data values for the Field <LI>Descriptive <i>label</I> for the Field <LI><I>Data Type</i> of the data associated with the Field </UL> <h5>Data Values in a Field</h5> <p>A single field can have zero or more data values associated with it at any instance. All values within a field have the same data type as dictated by the field (for example, all Contact.TEL field data values must be of STRING type). The data type of a field determines the add/get/set methods to use for accessing the data values (for example, if a field requires STRING data types, then addString, getString, and setString methods are used to access the data). </p><P> Data values within a field are treated as a variable-length array of values, very similar to the behavior of a <code>Vector</code>. As such, the following rules apply for accessing data values for fields:<br> <ul> <li>Values are added using the appropriate addXXX() method. The value is appended as the last data value in the field's array, similar to <code>Vector.addElement</code>.</li> <li>Values are retrieved one at a time using the appropriate getXXX() method with an index. The index is an array index into the field's array of data values. Values are assigned a sequential index beginning from 0 for the first value in a field up to n-1, where n is the total number of values currently assigned to the field. This behavior is similar to the method <code>Vector.elementAt()</code>.</li> <li>Values are removed from a field by using the method <A HREF="../../../javax/microedition/pim/PIMItem.html#removeValue(int, int)"><CODE>removeValue(int, int)</CODE></A>. All indexes in the field's array are guaranteed by the implementation to contain an assigned value. Therefore, removing fields from the middle of a field's array will cause compacting of the array and reindexing of the data values. This is similar behavior to the method <code>Vector.removeElement(Object)</code>.</li> </ul> <h5>Field Labels</h5> <p>Each field has a human readable <i>label</i>, usually used for display purposes. The label can be retrieved through <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldLabel(int)"><CODE>PIMList.getFieldLabel(int)</CODE></A>. </p> <h5>Field Data Types</h5> <p>The data values for a field has a <i>data type</i>, such as <A HREF="../../../javax/microedition/pim/PIMItem.html#INT"><CODE>INT</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#BINARY"><CODE>BINARY</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#BOOLEAN"><CODE>BOOLEAN</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#DATE"><CODE>DATE</CODE></A>, <A HREF="../../../javax/microedition/pim/PIMItem.html#STRING_ARRAY"><CODE>STRING_ARRAY</CODE></A> or <A HREF="../../../javax/microedition/pim/PIMItem.html#STRING"><CODE>STRING</CODE></A>. The data type of the field's data can be retrieved through <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldDataType(int)"><CODE>PIMList.getFieldDataType(int)</CODE></A>. All data values for a particular field have the same data type. </p> <h4>Standard and Extended Fields</h4> <p>Fields can be classified into two logical divisions: standard fields and extended fields. This division of fields generally determines the portability of the fields across implementations. Standard fields are specifically defined within the javax.microedition.pim package and may be available on almost all PIM implementations. Extended fields are platform specific fields defined by an individual implementation and are therefore generally not portable across different devices. Extended fields are generally defined in vendor specific classes derived from this class. </p> <h5>Standard Fields</h5> <P>Standard fields are fields that have IDs explicitly defined as part of the PIM APIs in the javax.microedition.pim package. These fields are the common fields among PIM lists and are more likely to be portable across PIM implementations (but not guaranteed since not all platforms support the same fields in a PIMItem). </P> <h5>Extended Fields</h5> <p>Extended fields are fields that do not have a specific field explicitly defined in the javax.microedition.pim package, but are defined in vendor-specific classes in a separate vendor package. These fields may or may not be exposed publicly in vendor specific classes. Vendors are allowed to extend the field set for any of the PIM items in this manner to address any platform specific fields they wish to support. Users can find out if a field is an extended field by comparing its value against <A HREF="../../../javax/microedition/pim/PIMItem.html#EXTENDED_FIELD_MIN_VALUE"><CODE>EXTENDED_FIELD_MIN_VALUE</CODE></A>, find out the field's allowed data type through the method <A HREF="../../../javax/microedition/pim/PIMList.html#getFieldDataType(int)"><CODE>PIMList.getFieldDataType(int)</CODE></A>, and find out the field's label through the method<A HREF="../../../javax/microedition/pim/PIMList.html#getFieldLabel(int)"><CODE>PIMList.getFieldLabel(int)</CODE></A>. </p> <h4>Attributes</h4> <p>Optional attributes can be provided to further describe individual data values for a field. Attributes are specified when adding data values to a field. These attributes are hints to the underlying implementation providing more information about the data value than just a field can provide. Since they are hints, they may or may not be ignored by the implementation when adding the data values. The actual attributes used and associated with the data values after adding can be retrieved by the method <A HREF="../../../javax/microedition/pim/PIMItem.html#getAttributes(int, int)"><CODE>getAttributes(int, int)</CODE></A>. Attributes can also have human readable labels associated with them, retrieved by the method <A HREF="../../../javax/microedition/pim/PIMList.html#getAttributeLabel(int)"><CODE>PIMList.getAttributeLabel(int)</CODE></A>. If no attributes are to be associated with a data value, then <A HREF="../../../javax/microedition/pim/PIMItem.html#ATTR_NONE"><CODE>ATTR_NONE</CODE></A> must be used. </p><p> Attributes are handled in the API using a single bit to indicate a specific attribute and using int values as bit arrays to indicate a set of attributes. int values can be checked to see if they contain a specific attribute by using bitwise AND (&) with the attribute and the int value. <A HREF="../../../javax/microedition/pim/PIMItem.html#ATTR_NONE"><CODE>ATTR_NONE</CODE></A> is a special attribute that indicates no attributes are set and has a value of 0 that erases all other attributes previously set. </P> <h5>Extended Attributes</h5> <p>Optional attributes may also be extended by vendors and their PIM API implementations. These extended attributes also may or may not be exposed publicly in vendor specific classes. The label for these attributes can be retrieved through <A HREF="../../../javax/microedition/pim/PIMList.html#getAttributeLabel(int)"><CODE>PIMList.getAttributeLabel(int)</CODE></A>. </p> <h3>Categories</h3> <p>Categories are string items assigned to an item to represent the item's inclusion in a logical grouping. The category string correspond to category values already existing in the PIMItem's associated PIMList. Category support per list is optional, depending on the implementing PIMList class that the item is associated with. The item's list determines if categories can be assigned, and how many categories can be assigned per item. </p>
<P>
<P>
<DL>
<DT><B>Since:</B></DT> <DD>PIM 1.0</DD></DL>
<HR>
<P>
<!-- ======== NESTED CLASS SUMMARY ======== -->
<!-- =========== FIELD SUMMARY =========== -->
<A NAME="field_summary"><!-- --></A><TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Field Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/pim/PIMItem.html#ATTR_NONE">ATTR_NONE</A></B></CODE>
<BR>
Constant indicating that no additional attributes are applicable to a data value for a field.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/pim/PIMItem.html#BINARY">BINARY</A></B></CODE>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -