javax.microedition.pim
Interface PIMItem

All Known Subinterfaces:

Contact, Event, ToDo, BlackBerryContact, BlackBerryContactGroup, BlackBerryEvent, BlackBerryMemo, BlackBerryPIMItem, BlackBerryToDo

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

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 PIMList.getFieldDataType(int). 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. 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.

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

For more information about this class or about the personal information management (PIM) API, see The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:

BlackBerry API 4.0.0, PIM 1.0

Field Summary
static int	ATTR_NONE Constant indicating that no additional attributes are applicable to a data value for a field.
static int	BINARY Data type indicating data is binary in a byte array.
static int	BOOLEAN Data type indicating data is of boolean primitive data type.
static int	DATE Data type indicating data is a Date in long primitive data type format expressed in the same long value format as Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
static int	EXTENDED_ATTRIBUTE_MIN_VALUE Constant indicating the minimum possible value for an extended attribute constant.
static int	EXTENDED_FIELD_MIN_VALUE Constant indicating the minimum possible value for an extended field constant.
static int	INT Data type indicating data is of int primitive data type.
static int	STRING Data type indicating data is a String object.
static int	STRING_ARRAY Data type indicating data is a array of related fields returned in a string array.

Method Summary
void	addBinary(int field, int attributes, byte[] value, int offset, int length) Adds a binary data value to a field in the item.
void	addBoolean(int field, int attributes, boolean value) Adds a boolean value to a field in the item.
void	addDate(int field, int attributes, long value) Adds a date value to a field in the item.
void	addInt(int field, int attributes, int value) Adds an integer value to a field in the item.
void	addString(int field, int attributes, String value) Adds a String value to a field in the item.
void	addStringArray(int field, int attributes, String[] value) Adds an array of related string values as a single entity to a field in the item.
void	addToCategory(String category) Adds a category to this item.
void	commit() Persists the data in the item to its PIM list.
int	countValues(int field) Returns the number of data values currently set in a particular field.
int	getAttributes(int field, int index) Gets the attributes associated with the data value at a given index for the indicated field.
byte[]	getBinary(int field, int index) Gets a binary data value for a field from the item.
boolean	getBoolean(int field, int index) Gets a boolean value from a field in the item.
String[]	getCategories() Gets all the categories to which this item belongs.
long	getDate(int field, int index) Gets a date value from a field in the item.
int[]	getFields() Gets all fields in the item that have data stored for them.
int	getInt(int field, int index) Get an integer value from a field in the item.
PIMList	getPIMList() Gets the PIMList associated with this item.
String	getString(int field, int index) Gets a String value from a field in the item.
String[]	getStringArray(int field, int index) Gets an array of related values from a field in the item.
boolean	isModified() Returns whether any of this item's fields have been modified since the item was retrieved or last committed.
int	maxCategories() Returns the maximum number of categories to which this item can be assigned.
void	removeFromCategory(String category) Removes a category from this item.
void	removeValue(int field, int index) Removes the value at the given index for the indicated field in this item.
void	setBinary(int field, int index, int attributes, byte[] value, int offset, int length) Sets an existing binary data value in a field to a new value.
void	setBoolean(int field, int index, int attributes, boolean value) Sets an existing boolean data value in a field to a new value.
void	setDate(int field, int index, int attributes, long value) Sets an existing date data value in a field to a new value.
void	setInt(int field, int index, int attributes, int value) Sets an existing int data value in a field to a new value.
void	setString(int field, int index, int attributes, String value) Sets an existing String data value in a field to a new value.
void	setStringArray(int field, int index, int attributes, String[] value) Sets an existing String array data value in a field to a new value.

Field Detail

ATTR_NONE

static final int ATTR_NONE

Constant indicating that no additional attributes are applicable to a data value for a field.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

BINARY

static final int BINARY

Data type indicating data is binary in a byte array. Data associated with BINARY is retrieved via PIMItem.getBinary(int, int), added via PIMItem.addBinary(int, int, byte[], int, int), and set via PIMItem.setBinary(int, int, int, byte[], int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

BOOLEAN

static final int BOOLEAN

Data type indicating data is of boolean primitive data type. Data associated with BOOLEAN is retrieved via PIMItem.getBoolean(int, int), added via PIMItem.addBoolean(int, int, boolean), and set via PIMItem.setBoolean(int, int, int, boolean).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

DATE

static final int DATE

Data type indicating data is a Date in long primitive data type format expressed in the same long value format as Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970). Data associated with DATE is retrieved via PIMItem.getDate(int, int), added via PIMItem.addDate(int, int, long), and set via PIMItem.setDate(int, int, int, long).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

EXTENDED_ATTRIBUTE_MIN_VALUE

static final int EXTENDED_ATTRIBUTE_MIN_VALUE

Constant indicating the minimum possible value for an extended attribute constant.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

EXTENDED_FIELD_MIN_VALUE

static final int EXTENDED_FIELD_MIN_VALUE

Constant indicating the minimum possible value for an extended field constant.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

INT

static final int INT

Data type indicating data is of int primitive data type. Data associated with INT is retrieved via PIMItem.getInt(int, int), added via PIMItem.addInt(int, int, int), and set via PIMItem.setInt(int, int, int, int).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

STRING

static final int STRING

Data type indicating data is a String object. Data associated with STRING is retrieved via PIMItem.getString(int, int), added via PIMItem.addString(int, int, String), and set via PIMItem.setString(int, int, int, String).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

STRING_ARRAY

static final int STRING_ARRAY

Data type indicating data is a array of related fields returned in a string array. Data associated with STRING_ARRAY is retrieved via PIMItem.getStringArray(int, int), added via PIMItem.addStringArray(int, int, String[]), and set via PIMItem.setStringArray(int, int, int, String[]).

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

Method Detail

addBinary

void addBinary(int field,
               int attributes,
               byte[] value,
               int offset,
               int length)

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.

NullPointerException - if value is null.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getBinary(int, int), PIMItem.setBinary(int, int, int, byte[], int, int)

Since:

BlackBerry API 4.0.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.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getBoolean(int, int), PIMItem.setBoolean(int, int, int, boolean)

Since:

BlackBerry API 4.0.0

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.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getDate(int, int), PIMItem.setDate(int, int, int, long)

Since:

BlackBerry API 4.0.0

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.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getInt(int, int), PIMItem.setInt(int, int, int, int)

Since:

BlackBerry API 4.0.0

addString

void addString(int field,
               int attributes,
               String value)

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.

NullPointerException - if value is null.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getString(int, int), PIMItem.setString(int, int, int, String)

Since:

BlackBerry API 4.0.0

addStringArray

void addStringArray(int field,
                    int attributes,
                    String[] value)

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.

NullPointerException - if value is null.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

FieldFullException - if the field already contains the maximum number of data values it can hold.

See Also:

PIMItem.getStringArray(int, int), PIMItem.setStringArray(int, int, int, String[])

Since:

BlackBerry API 4.0.0

addToCategory

void addToCategory(String category)
                   throws PIMException

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.

Parameters:

category - the category to add

Throws:

NullPointerException - if category is null.

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.

See Also:

PIMItem.getCategories(), PIMItem.removeFromCategory(String), PIMItem.maxCategories()

Since:

BlackBerry API 4.0.0

commit

void commit()
            throws PIMException

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.

SecurityException - if the application has not been granted write access to the PIM list or the list is opened PIM.READ_ONLY.

Since:

BlackBerry API 4.0.0

countValues

int countValues(int field)

Returns the number of data values currently set in a particular field.

Parameters:

field - The field from which the current count of values is returned.

Returns:

the number of values currently assigned to the field in this item.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

Since:

BlackBerry API 4.0.0

getAttributes

int getAttributes(int field,
                  int index)

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.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

Since:

BlackBerry API 4.0.0

getBinary

byte[] getBinary(int field,
                 int index)

Gets a binary data value for a field from the item. PIMList.isSupportedField(int) should be used to verify the field validity for this item prior to invoking this method.

Parameters:

field - field from which the data is retrieved.

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

Returns:

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

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addBinary(int, int, byte[], int, int), PIMItem.setBinary(int, int, int, byte[], int, int)

Since:

BlackBerry API 4.0.0

getBoolean

boolean getBoolean(int field,
                   int index)

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

Parameters:

field - The field from which the data is retrieved.

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

Returns:

a boolean representing a value of the field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addBoolean(int, int, boolean), PIMItem.setBoolean(int, int, int, boolean)

Since:

BlackBerry API 4.0.0

getCategories

String[] getCategories()

Gets all the categories to which this item belongs. If there are no categories assigned to this item, a zero length array is returned.

Returns:

a string array of all the categories for this item.

See Also:

PIMItem.addToCategory(String), PIMItem.removeFromCategory(String), PIMItem.maxCategories()

Since:

BlackBerry API 4.0.0

getDate

long getDate(int field,
             int index)

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

Parameters:

field - The field from which the data is retrieved.

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

Returns:

a date representing a value of the field, returned in the same long 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.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addDate(int, int, long), PIMItem.setDate(int, int, int, long)

Since:

BlackBerry API 4.0.0

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.

Parameters:

field - The field from which the data is retrieved.

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

Returns:

an int representing a value of the field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addInt(int, int, int), PIMItem.setInt(int, int, int, int)

Since:

BlackBerry API 4.0.0

getPIMList

PIMList getPIMList()

Gets the PIMList associated with this item. An item always has the same list associated with it for its life as an object once a list is associated with the item.

Returns:

the PIMList that this item belongs to. If the item does not belong to any list, null is returned.

Since:

BlackBerry API 4.0.0

getString

String getString(int field,
                 int index)

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.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addString(int, int, String), PIMItem.setString(int, int, int, String)

Since:

BlackBerry API 4.0.0

getStringArray

String[] getStringArray(int field,
                        int index)

Gets an array of related values 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.

Not all elements in the array are required to be supported by the item. If an array index is not supported by this item, null is the value for the String at the array index.

Parameters:

field - The field from which the data is retrieved.

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

Returns:

a String array representing a group of related values from the field.

Throws:

IllegalArgumentException - if the field is not valid for the implementing class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

See Also:

PIMItem.addStringArray(int, int, String[]), PIMItem.setStringArray(int, int, int, String[])

Since:

BlackBerry API 4.0.0

isModified

boolean isModified()

Returns whether any of this item's fields have been modified since the item was retrieved or last committed.

Returns:

true if any of this item's fields have been modified since the item was retrieved or last committed; false otherwise.

Since:

BlackBerry API 4.0.0

maxCategories

int maxCategories()

Returns the maximum number of categories to which this item can be assigned.

Returns:

the number of categories to which this item can be assigned. 0 (zero) indicates no category support and -1 indicates there is no limit to the number of categories to which this item can be assigned.

See Also:

PIMItem.addToCategory(String), PIMItem.getCategories(), PIMItem.removeFromCategory(String)

Since:

BlackBerry API 4.0.0

removeFromCategory

void removeFromCategory(String category)

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.

Parameters:

category - the category to remove

Throws:

NullPointerException - if category is null

See Also:

PIMItem.addToCategory(String), PIMItem.getCategories(), PIMItem.maxCategories()

Since:

BlackBerry API 4.0.0

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.

Throws:

IllegalArgumentException - if field is not valid for the implementing class.

IndexOutOfBoundsException - if index is negative or greater than or equal to the number of values currently contained in the field.

UnsupportedFieldException - if field is not a supported field in the implementing instance of the class.

Since:

BlackBerry API 4.0.0

setBinary

void setBinary(int field,
               int index,
               int attributes,
               byte[] value,
               int offset,
               int length)

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.

NullPointerException - if value is null.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addBinary(int, int, byte[], int, int), PIMItem.getBinary(int, int)

Since:

BlackBerry API 4.0.0

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

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addBoolean(int, int, boolean), PIMItem.getBoolean(int, int)

Since:

BlackBerry API 4.0.0

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

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addDate(int, int, long), PIMItem.getDate(int, int)

Since:

BlackBerry API 4.0.0

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

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addInt(int, int, int), PIMItem.getInt(int, int)

Since:

BlackBerry API 4.0.0

setString

void setString(int field,
               int index,
               int attributes,
               String value)

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

NullPointerException - if value is null.

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addString(int, int, String), PIMItem.getString(int, int)

Since:

BlackBerry API 4.0.0

setStringArray

void setStringArray(int field,
                    int index,
                    int attributes,
                    String[] value)

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.

Throws:

NullPointerException - if value is null.

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

UnsupportedFieldException - if the field is not supported in the implementing instance of the class.

IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

See Also:

PIMItem.addStringArray(int, int, String[]), PIMItem.getStringArray(int, int)

Since:

BlackBerry API 4.0.0