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.
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
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
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
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
AbstractPIMList.getFieldLabel .
Field Data Types
The data values for a field has a data type, such as
PIMItem.INT ,
PIMItem.BINARY ,
PIMItem.BOOLEAN ,
PIMItem.DATE ,
PIMItem.STRING_ARRAY or
PIMItem.STRING . The data type of the field's data can be retrieved
through
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
PIMItem.EXTENDED_FIELD_MIN_VALUE , find out the field's allowed data type
through the method
AbstractPIMList.getFieldDataType , and find out
the field's label through the method
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
AbstractPIMItem.getAttributes .
Attributes can also have human readable labels associated with them,
retrieved by the method
AbstractPIMList.getAttributeLabel .
If no attributes are to be associated with a data value, then
PIMItem.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.
PIMItem.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
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.
since:
PIM 1.0 |