PIMItem

Fields

PIMItems reference its data through fields. 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 Contact interface as a field that a contact may support).

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 {@link AbstractPIMList#getSupportedFields} 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, all fields should be checked for support in the item's PIMList using {@link AbstractPIMList#isSupportedField} prior to being used in any retrieval or storage method.

Each field has the following pieces of information available for it:

• Zero or more data values associated with the Field
• Attributes for data values for the Field
• Descriptive label for the Field
• Data Type of the data associated with the Field

Data Values in a Field

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).

Data values within a field are treated as a variable-length array of values, very similar to the behavior of a Vector. As such, the following rules apply for accessing data values for fields:

• Values are added using the appropriate addXXX() method. The value is appended as the last data value in the field's array, similar to Vector.addElement.
• 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 Vector.elementAt().
• Values are removed from a field by using the method {@link AbstractPIMItem#removeValue}. 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 causes compacting of the array and reindexing of the data values. This is similar behavior to the method Vector.removeElement(Object).

Field Labels

Each field has a human readable label, usually used for display purposes. The label can be retrieved through {@link AbstractPIMList#getFieldLabel}.

Field Data Types

The data values for a field has a data type, such as {@link #INT}, {@link #BINARY}, {@link #BOOLEAN}, {@link #DATE}, {@link #STRING_ARRAY} or {@link #STRING}. The data type of the field's data can be retrieved through {@link AbstractPIMList#getFieldDataType}. All data values for a particular field have the same data type.

Standard and Extended Fields

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.

Standard Fields

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).

Extended Fields

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 {@link #EXTENDED_FIELD_MIN_VALUE}, find out the field's allowed data type through the method {@link AbstractPIMList#getFieldDataType}, and find out the field's label through the method {@link AbstractPIMList#getFieldLabel}.

Attributes

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 {@link AbstractPIMItem#getAttributes}. Attributes can also have human readable labels associated with them, retrieved by the method {@link AbstractPIMList#getAttributeLabel}. If no attributes are to be associated with a data value, then {@link #ATTR_NONE} must be used.

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. {@link #ATTR_NONE} is a special attribute that indicates no attributes are set and has a value of 0 that erases all other attributes previously set.

Extended Attributes

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 {@link AbstractPIMList#getAttributeLabel}.

Categories

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.