javax.microedition.pim
Interface PIMItem

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 PIMList.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 PIMList.isSupportedField(int) 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
PIMItem.removeValue(int, int). 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 re-indexing of the data values. This is similar behavior to the
method Vector.removeElementAt(int).

Field Labels

Each field has a human readable label, usually used for display
purposes. The label can be retrieved through
PIMList.getFieldLabel(int).

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. The RIM extension fields are
defined in the interfaces in the net.rim.blackberry.api.pdap
package.

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 PIMList.getFieldDataType(int), and find out the
field's label through the method PIMList.getFieldLabel(int). The RIM
extension fields are defined in the interfaces in the
net.rim.blackberry.api.pdap package.

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
PIMItem.getAttributes(int, int). Attributes can also have human readable
labels associated with them, retrieved by the method
PIMList.getAttributeLabel(int). 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 PIMList.getAttributeLabel(int). The RIM extension
attributes are defined in the interfaces in the
net.rim.blackberry.api.pdap package.

Categories

Categories are string items assigned to an item to represent the item's
inclusion in a logical grouping. The category strings 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.

addBinary

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
Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

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

value - 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].

offset - the offset into the provided byte array from where to
start reading the binary data.

length - the number of bytes to read from starting from the offset
in the byte array. If the number of bytes available from
the array are less than the length, only the remaining
bytes are provided and the field's resulting binary data
length is value.length - offset.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, the
field does not have a data type of BINARY,
offset is negative, offset
is greater than or equal to the length of the value byte
array, length is zero or negative, or the
value array is length 0.

addBoolean

void addBoolean(int field,
int attributes,
boolean value)

Adds a boolean value to a field in the item. The value is appended as the
last data value in the field's array, similar to
Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

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

value - The data to add to the field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or
the field does not have a data type of
BOOLEAN.

addDate

void addDate(int field,
int attributes,
long value)

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
Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

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 is rounded down to the nearest second.

Parameters:

field - The field to which the value belongs.

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

value - The data to add to the field. The date must be expressed
in the same long value format as Date,
which is milliseconds since the epoch (00:00:00 GMT,
January 1, 1970).

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or
the field does not have a data type of DATE.

addInt

void addInt(int field,
int attributes,
int value)

Adds an integer value to a field in the item. The value is appended as
the last data value in the field's array, similar to
Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

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

value - The data to add to the field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or
the field does not have a data type of INT.

addString

Adds a String value to a field in the item. The value is appended as the
last data value in the field's array, similar to
Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Values given to this method should not be "escaped"; i.e. having special
characters marked in the string by a particular escape character. Any
characters that requiring special handling such as these for importing
and exporting is handled transparently by
PIM.toSerialFormat()
and
PIM.fromSerialFormat.

Parameters:

field - The field to which the value belongs.

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

value - The data to add to the field. The empty String (e.g.
String("")) is a valid data value for string.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or
the field does not have a data type of
STRING.

addStringArray

Adds an array of related string values as a single entity to a field in
the item. The array is appended as the last data value in the field's
array of values, similar to Vector.addElement().
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Not all elements in the array are required to be supported by the item.
If a String is provided at an array index that is not supported by this
item, that value is silently discarded.
PIMList.isSupportedArrayElement(int, int) should be used to
verify the validity of the array element prior to invoking this method.

Parameters:

field - The field to which the value belongs.

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

value - The data to add to the field. At least one index in the
array must contain a String object.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class or
all of the strings in the array are null or the field
does not have a data type of STRING_ARRAY.

addToCategory

Adds a category to this item. It is recommended to use the category names
defined in PIMList.getCategories() from the list associated with
this item. Some devices may not allow categories to be added which are
not in the list returned from PIMList.getCategories(). In this
case a PIMException may be thrown. If the given category is
already associated with this item, the category is not added again and
the method call is considered successful and returns.

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 the item
being assigned to only one category in this case.

PIMException - may be thrown if category is not in the list's category
list and the list prevents that condition from occurring.
Also thrown if categories are not supported in the
implementation. Also thrown if the max categories that
this item can be assigned to is exceeded.

commit

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.
Some devices may not allow categories in the item to be persisted which
are not in the list returned from PIMList.getCategories(). In
this case the categories are dropped silently when this method is invoked
(this allows data imported using
PIM.fromSerialFormat(java.io.InputStream, String) to be
persisted).
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 rounds down the given Date value to
its nearest value supported by the platform.

Throws:

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

getAttributes

Gets the attributes associated with the data value at a given index for
the indicated field. The attributes are returned in an int that
represents an array of attribute bits.

Parameters:

field - The field from which the data is removed.

index - the index of the value associated with the field whose
attributes to return.

Returns:

the attributes assigned to the value at the given field and
index. The value contains attribute values logically OR'd
together in a bit array. Individual attributes can be checked for
in this bit array by using bitwise AND (&) with the attribute
and the array.

getFields

int[] getFields()

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

Returns:

array of fields that have data currently stored for them. If no
fields contain data, a zero length array is returned.

Since:

BlackBerry API 4.0.0

getInt

int getInt(int field,
int index)

Get an integer value from a field in the item.
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

getString

Gets a String value from a field in the item.
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method. The returned string
contains no "escaped" characters that may have been used when importing
the field's data.

Parameters:

field - The field from which the data is retrieved.

index - an index to a particular value associated with the field.

Returns:

a String representing a value of the field. The empty String
(e.g. String("")) is a valid data value for string.

removeFromCategory

Removes a category from this item. If the given category is already
removed from this item, the method call is considered successful and
returns.

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 the item
being removed from only one category in this case.

removeValue

void removeValue(int field,
int index)

Removes the value at the given index for the indicated field in this
item. Note that all indexes in the field's array are guaranteed by the
implementation to contain an assigned value. Therefore, removing fields
from a field's array may cause compacting of the array and reindexing of
the data values. This is similar behavior to the method
Vector.removeElementAt(int).

Parameters:

field - The field from which the data is removed.

index - the index of the value associated with the field to be
removed.

setBinary

Sets an existing binary data value in a field to a new value. The value
located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use PIMItem.addBinary(int, int, byte[], int, int).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

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

value - 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].

offset - the offset into the provided byte array from where to
start reading the binary data.

length - the number of bytes to read starting from the offset in
the byte array. If the number of bytes available from the
array are less than the length, only the remaining bytes
are provided and the field's resulting binary data length
is value.length - offset.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, if
offset is negative, length
is less than or equal to zero, or value is
zero length.

setBoolean

void setBoolean(int field,
int index,
int attributes,
boolean value)

Sets an existing boolean data value in a field to a new value. The value
located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use PIMItem.addBoolean(int, int, boolean).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

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

value - The new value of the data at the field's index.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, or
the field cannot be set to the value provided (e.g. the
value is not valid for that field or this field's value
is read-only).

setDate

void setDate(int field,
int index,
int attributes,
long value)

Sets an existing date data value in a field to a new value. The value
located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use PIMItem.addDate(int, int, long).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Note that the value provided may be rounded-down by an implementation due
to platform restrictions. For example, should a native PIM database only
support date values with granularity in terms of seconds, then the
provided date value is rounded down to the nearest second.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

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

value - The new value of the data at the field's index. The date
must be expressed in the same long value format as
Date, which is milliseconds since the
epoch (00:00:00 GMT, January 1, 1970).

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, or
the field cannot be set to the value provided (e.g. the
value is not valid for that field or this field's value
is read-only).

setInt

void setInt(int field,
int index,
int attributes,
int value)

Sets an existing int data value in a field to a new value. The value
located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use PIMItem.addInt(int, int, int).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

attributes - a bit array specifying any optional attributes describing
this value. These attributes are a hint to the
implementation 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.

value - The new value of the data at the field's index.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, or
the field cannot be set to the value provided (e.g. the
value is not valid for that field or this field's value
is read-only).

setString

Sets an existing String data value in a field to a new value. The value
located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use PIMItem.addString(int, int, String).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Values given to this method should not be "escaped"; i.e. having special
characters marked in the string by a particular escape character. Any
characters that requiring special handling such as these for importing
and exporting is handled transparently by
PIM.toSerialFormat()
and
PIM.fromSerialFormat.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

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

value - The new value of the data at the field's index. The empty
String (e.g. String("")) is a valid data value for string.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class, or
the field cannot be set to the value provided (e.g. the
value is not valid for that field or this field's value
is read-only).

setStringArray

Sets an existing String array data value in a field to a new value. The
value located at the provided index is set, similar to
Vector.setElementAt(). This method cannot be used to add
new values to a field; use
PIMItem.addStringArray(int, int, String[]).
PIMList.isSupportedField(int) should be used to verify the field
validity for this item prior to invoking this method.

Not all elements in the array are required to be supported by the item.
If a String is provided at an array index that is not supported by this
item, that value is silently discarded.
PIMList.isSupportedArrayElement(int, int) should be used to
verify the validity of the array element prior to invoking this method.

Parameters:

field - The field to which the value belongs.

index - an index to a particular value associated with the field.

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

value - The new value of the data at the field's index. At least
one index in the array must contain a non-null String
object.

IllegalArgumentException - if the field is not valid for the implementing class, all
of the strings in the array are null, or the field cannot
be set to the value provided (e.g. the value is not valid
for that field or this field's value is read-only).

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.Java is a trademark of Oracle America Inc. in the US and other countries.Legal