PIMItem (PIM Optional Package 1.0 Spec, Final Release)

Overview

Package

Class

Tree

Deprecated

Index

Help

PIM Optional Package 1.0
Final Release

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.microedition.pim
Interface PIMItem

All Known Subinterfaces:: Contact, Event, ToDo

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

Field Data Types

The data values for a field has a data type, such as INT, BINARY, BOOLEAN, DATE, STRING_ARRAY or 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.

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 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 methodPIMList.getFieldLabel(int).

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

BINARY

public static final int BINARY

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

See Also:: Constant Field Values

BOOLEAN

public static final int BOOLEAN

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

See Also:: Constant Field Values

DATE

public 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 java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970). Data associated with DATE is retrieved via getDate(int, int) and added via addDate(int, int, long).

See Also:: Constant Field Values

INT

public static final int INT

Data type indicating data is of int primitive data type. Data associated with

INT

is retrieved via getInt(int, int) and added via addInt(int, int, int).

See Also:: Constant Field Values

STRING

public static final int STRING

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

See Also:: Constant Field Values

STRING_ARRAY

public 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 getStringArray(int, int) and added via addStringArray(int, int, java.lang.String[]).

See Also:: Constant Field Values

ATTR_NONE

public 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

EXTENDED_FIELD_MIN_VALUE

public static final int EXTENDED_FIELD_MIN_VALUE

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

See Also:: Constant Field Values

EXTENDED_ATTRIBUTE_MIN_VALUE

public static final int EXTENDED_ATTRIBUTE_MIN_VALUE

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

See Also:: Constant Field Values

Method Detail

getPIMList

public PIMList getPIMList()

Returns the PIMList associated with this item. An item always have 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.

commit

public void commit()
            throws PIMException

This method 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, java.lang.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.; java.lang.SecurityException - if the application has not been granted write access to the PIM list or the list is opened READ_ONLY.

isModified

public boolean isModified()

This method returns a boolean indicating whether any of this item's fields have been modified since the item was retrieved or last committed.

Returns:: boolean true if any fields have been modified since the item was last retrieved or committed, false otherwise.

getFields

public int[] getFields()

Returns 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:: int array of fields that have data currently stored for them. If no fields contain data, a zero length array is returned.

getBinary

public byte[] getBinary(int field,
                        int index)

Get 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 - The 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:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addBinary

public 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 - int indicating the offset into the provided byte array from where to start reading the binary data.; length - int indicating 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:: java.lang.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.; java.lang.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.

setBinary

public 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 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 - int indicating the offset into the provided byte array from where to start reading the binary data.; length - int indicating 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:: java.lang.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.; java.lang.NullPointerException - if value is null.; UnsupportedFieldException - if the field is not supported in the implementing instance of the class.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

getDate

public long getDate(int field,
                    int index)

Get 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 java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
Throws:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addDate

public 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 java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
Throws:: java.lang.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.

setDate

public 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 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 java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
Throws:: java.lang.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.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

getInt

public 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:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addInt

public 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:: java.lang.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.

setInt

public 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 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 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:: java.lang.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.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

getString

public java.lang.String getString(int field,
                                  int index)

Get 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. A null String (e.g. String("")) is a valid data value for string.
Throws:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addString

public void addString(int field,
                      int attributes,
                      java.lang.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 toSerialFormat and 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. A null String (e.g. String("")) is a valid data value for string.
Throws:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class or the field does not have a data type of STRING.; java.lang.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.

setString

public void setString(int field,
                      int index,
                      int attributes,
                      java.lang.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 addString(int, int, java.lang.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 toSerialFormat and 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. A null String (e.g. String("")) is a valid data value for string.
Throws:: java.lang.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).; java.lang.NullPointerException - if value is null.; UnsupportedFieldException - if the field is not supported in the implementing instance of the class.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

getBoolean

public boolean getBoolean(int field,
                          int index)

Get 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:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addBoolean

public 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:: java.lang.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.

setBoolean

public 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 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:: java.lang.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.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

getStringArray

public java.lang.String[] getStringArray(int field,
                                         int index)

Get 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:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addStringArray

public void addStringArray(int field,
                           int attributes,
                           java.lang.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:: java.lang.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.; java.lang.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.

setStringArray

public void setStringArray(int field,
                           int index,
                           int attributes,
                           java.lang.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 addStringArray(int, int, java.lang.String[]). 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. At least one index in the array must contain a String object.
Throws:: java.lang.NullPointerException - if value is null.; java.lang.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.; java.lang.IndexOutOfBoundsException - if the index is negative or greater than or equal to the number of values currently contained in the field.

countValues

public 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:: int indicating the number of values currently assigned to the field in this item.
Throws:: java.lang.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.

removeValue

public 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.removeElement(Object).

Parameters:: field - The field from which the data is removed.; index - an index to a particular value associated with the field.
Throws:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

getAttributes

public int getAttributes(int field,
                         int index)

Gets the actual attributes associated with the data value at the 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 - an index to a particular value associated with the field.
Returns:: int representing the attributes assigned to the value at the given field and index. The int 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:: java.lang.IllegalArgumentException - if the field is not valid for the implementing class.; java.lang.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.

addToCategory

public void addToCategory(java.lang.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:: java.lang.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.

removeFromCategory

public void removeFromCategory(java.lang.String category)

Remove 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:: java.lang.NullPointerException - if category is null

getCategories

public java.lang.String[] getCategories()

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

Returns:: a string array of all the categories for the item.

maxCategories

public int maxCategories()

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

Returns:: int the number of categories this item can be assigned to. 0 indicates no category support and -1 indicates there is no limit to the number of categories that this item can be assigned to.