javax.microedition.pim
Interface PIMItem

All Known Subinterfaces:
BlackBerryContact, BlackBerryContactGroup, BlackBerryEvent, BlackBerryMemo, BlackBerryToDo, Contact, Event, ToDo

public interface PIMItem

Represents a personal information management (PIM) item.

A PIMItem, such as an event, is created, populated, added to a list, then associated with that list for life. PIMItems can be created or PIM information can be imported from pre-existing PIMItems.

A PIMItem contains data fields that represent information about the item itself. For example, the Contact object contains information about a contact entry such as a phone number, street address or job title. While the item may contain many fields, the list object that the item belongs to defines which fields it's objects can contain. If a list encounters a PIMItem object that contains unsupported fields, those fields are discarded.

The PIMList.isSupportedField(int) is invoked to determine if a field (as specified by the integer argument) is supported by a PIMList. Similarly, the PIMList.getSupportedAttributes(int) method is invoked to return an integer array representing all fields supported by the list.

The PIMItem object represents the common interfaces of the Event, Contact and ToDo objects.

Each field has the following information associated with it:

A field can have more than one value associated with it. All values must be of the same data type. An index is used to reference multiple values within a field, beginning with zero and ending with n-1, where n is the total number of values. The index values must be assigned to a value. If a value is removed or added, using the appropriate method, the index is reordered.

Each field has an associated label used for display purposes. The label can be returned by invoking the PIMList.getFieldLabel(int) method.

The supported field data types are INT, BINARY, BOOLEAN, DATE, or STRING.

For more information about this class or about the personal information management (PIM) API, refer to JSR 75: PDA Optional Packages for the J2METM Platform.

Since:
PDAP 1.0
See Also:
Event, ToDo, Contact, PIMList

Field Summary
static int ATTR_NONE
          Indicates that no additional attributes are applicable for this field.
static int BINARY
          Indicates that the data type is binary.
static int BOOLEAN
          Indicates that the data type is a Boolean.
static int DATE
          Indicates that the data type is a date.
static int EXTENDED_ATTRIBUTE_MIN_VALUE
          Represents the minimum value for an extended attribute constant.
static int EXTENDED_FIELD_MIN_VALUE
          Represents the minimum value for an extended field constant.
static int INT
          Indicates that the data type is an integer.
static int STRING
          Indicates that the data type is a string.
static int STRING_ARRAY
          Indicates that the data type is a string array.
 
Method Summary
 void addBinary(int field, int attributes, byte[] value, int offset, int length)
          Adds a binary value to a field within the item.
 void addBoolean(int field, int attribute, boolean value)
          Adds a boolean value to the field.
 void addDate(int field, int attributes, long value)
          Adds a date to a specified field.
 void addInt(int field, int attributes, int value)
          Adds the integer value contained in the field.
 void addString(int field, int attributes, String value)
          Adds a string value to the field.
 void addStringArray(int field, int attributes, String[] value)
          Adds a string array value to the field.
 void addToCategory(String category)
          Adds a category to this item.
 void commit()
          Commits the PIMItem to the list.
 int countValues(int field)
          Returns a value indicating the number of values currently contained within the field.
 int getAttributes(int field, int index)
          Returns the attributes associated with a specified data value.
 byte[] getBinary(int field, int index)
          Returns a byte array containing a binary representation of the data within the given field.
 boolean getBoolean(int field, int index)
          Returns the boolean value contained in the field.
 String[] getCategories()
          Returns the names of all categories associated with this item.
 long getDate(int field, int index)
          Returns the date value contained in the field.
 int[] getFields()
          Returns an integer array containing all fields for which data is associated.
 int getInt(int field, int index)
          Returns the integer value contained in the field.
 PIMList getPIMList()
          Returns the PIMList that contains this item.
 String getString(int field, int index)
          Returns the string value contained in the field.
 String[] getStringArray(int field, int index)
          Returns the string array value contained in the field.
 boolean isModified()
          Returns a boolean that indicates whether or not this PIMItem has been modified since the last commit or retrieval.
 int maxCategories()
          Returns the maximum number of categories that this item can be assigned to.
 void removeFromCategory(String category)
          Removes a category from this item.
 void removeValue(int field, int index)
          Removes a value from the specified field, given the index.
 void setBinary(int field, int index, int attributes, byte[] value, int offset, int length)
          Sets an existing binary value in a field to a new value.
 void setBoolean(int field, int index, int attributes, boolean value)
          Sets an existing boolean value in a field.
 void setDate(int field, int index, int attributes, long value)
          Sets an existing date value in a field.
 void setInt(int field, int index, int attributes, int value)
          Sets an existing integer value in a field.
 void setString(int field, int index, int attributes, String value)
          Sets an existing string value in a field.
 void setStringArray(int field, int index, int attributes, String[] value)
          Sets an existing string array value in a field.
 

Field Detail

ATTR_NONE

public static final int ATTR_NONE
Indicates that no additional attributes are applicable for this field.
Since:
JDE 4.0.0

BINARY

public static final int BINARY
Indicates that the data type is binary.

The getBinary(int, int) method is used to return a binary value. The addBinary(int, int, byte[], int, int) us used to add a binary value to a field.

Since:
JDE 4.0.0

BOOLEAN

public static final int BOOLEAN
Indicates that the data type is a Boolean.

The getBoolean(int, int) method is used to return a Boolean value. The addBoolean(int, int, boolean) method is used to add a Boolean value.

Since:
JDE 4.0.0

DATE

public static final int DATE
Indicates that the data type is a date.

The getDate(int, int) method is used to return a date value. The addDate(int, int, long) method is used to add a date value.

Since:
JDE 4.0.0

EXTENDED_ATTRIBUTE_MIN_VALUE

public static final int EXTENDED_ATTRIBUTE_MIN_VALUE
Represents the minimum value for an extended attribute constant.
Since:
JDE 4.0.0

EXTENDED_FIELD_MIN_VALUE

public static final int EXTENDED_FIELD_MIN_VALUE
Represents the minimum value for an extended field constant.
Since:
JDE 4.0.0

INT

public static final int INT
Indicates that the data type is an integer.

The getInt(int, int) method is used to return an integer value. The addInt(int, int, int) method is used to add an integer value.

Since:
JDE 4.0.0

STRING

public static final int STRING
Indicates that the data type is a string.

The getString(int, int) method is used to return a string value. The addString(int, int, java.lang.String) method is used to add a string value.

Since:
JDE 4.0.0

STRING_ARRAY

public static final int STRING_ARRAY
Indicates that the data type is a string array.

The getStringArray(int, int) method is used to return a string array value. The addStringArray(int, int, java.lang.String[]) method is used to add a string array value.

Since:
JDE 4.0.0
Method Detail

addBinary

public void addBinary(int field,
                      int attributes,
                      byte[] value,
                      int offset,
                      int length)
Adds a binary value to a field within the item.

PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - The field to add the binary data to.
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:
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.
Since:
JDE 4.0.0

addBoolean

public void addBoolean(int field,
                       int attribute,
                       boolean value)
Adds a boolean value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to add the data.
attribute - An integer specifying any attributes that describe this field.
value - The data to add to the field.
Since:
JDE 4.0.0

addDate

public void addDate(int field,
                    int attributes,
                    long value)
Adds a date to a specified field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to add the date.
attributes - An integer specifying any attributes that describe this field.
value - The value of the date to add.
Since:
JDE 4.0.0

addInt

public void addInt(int field,
                   int attributes,
                   int value)
Adds the integer value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to add the data.
attributes - An integer specifying any attributes that describe this field.
value - The data to add to the field.
Since:
JDE 4.0.0

addString

public void addString(int field,
                      int attributes,
                      String value)
Adds a string value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to add the data.
attributes - An integer specifying any attributes that describe this field.
value - The string to add to the field. The string will not contain any escape characters which might have been used to input the string.
Throws:
NullPointerException - Thrown if the value parameter is null.
Since:
JDE 4.0.0

addStringArray

public void addStringArray(int field,
                           int attributes,
                           String[] value)
Adds a string array value to the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to add the data.
attributes - An integer specifying any attributes that describe this field.
value - The string array to add to the field.
Since:
JDE 4.0.0

addToCategory

public void addToCategory(String category)
                   throws PIMException
Adds a category to this item.

Use the PIMList.getCategories() method to determine all valid categories associated with the list that contains this item. If an invalid category is specified, a PIMException is thrown. If the specified category is already associated with this item, the category is not added again and the method call is considered successful and returns.

Parameters:
category - A string representing the name of the category.
Throws:
NullPointerException - if category is null.
PIMException - if the specified category is invalid, if the maximum number of categories has already been exceeded, or if categories are not supported in the implementation.
Since:
JDE 4.0.0

commit

public void commit()
            throws PIMException
Commits the PIMItem to the list.

Categories that are specified in the PIMItem that are not supported by the PIMList will be discarded.

Throws:
PIMException - Thrown if an error occurs with the item, or the list could not be accessed.
Since:
JDE 4.0.0

countValues

public int countValues(int field)
Returns a value indicating the number of values currently contained within the field.

Parameters:
field - The field to check.
Returns:
An integer representing the number of values contained within the field.
Since:
JDE 4.0.0

getAttributes

public int getAttributes(int field,
                         int index)
Returns the attributes associated with a specified data value.

Parameters:
field - The field from which to return the attributes.
index - The index of the value within the field.
Returns:
An integer representing the attributes returned.
Since:
JDE 4.0.0

getBinary

public byte[] getBinary(int field,
                        int index)
Returns a byte array containing a binary representation of the data within the given field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the binary representation.
index - An integer representing the index of the data within the field.
Returns:
A byte array containing the binary representation ("B" binary encoded string) of the data within this field.
Since:
JDE 4.0.0

getBoolean

public boolean getBoolean(int field,
                          int index)
Returns the boolean value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the boolean.
index - The index of the data within the field.
Returns:
A boolean.
Since:
JDE 4.0.0

getCategories

public String[] getCategories()
Returns the names of all categories associated with this item.

If no categories are specified, a zero-length string array is returned.

Returns:
An array of strings.
Since:
JDE 4.0.0

getDate

public long getDate(int field,
                    int index)
Returns the date value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the date.
index - The index of the data within the field.
Returns:
A long representing the date.
Since:
JDE 4.0.0

getFields

public int[] getFields()
Returns an integer array containing all fields for which data is associated.

This method is useful because it returns only fields with data in them. The user does not need to iterate through empty or unsupported fields.

Returns:
An integer array containing the fields for which data is associated.
Since:
JDE 4.0.0

getInt

public int getInt(int field,
                  int index)
Returns the integer value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the value.
index - The index of the data within the field.
Returns:
The integer value.
Since:
JDE 4.0.0

getPIMList

public PIMList getPIMList()
Returns the PIMList that contains this item.

Returns:
A PIMList object.
Since:
JDE 4.0.0

getString

public String getString(int field,
                        int index)
Returns the string value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the value.
index - The index of the data within the field.
Returns:
A string. The string will not contain any escape characters which might have been used to input the string. The null value is an acceptable value.
Since:
JDE 4.0.0

getStringArray

public String[] getStringArray(int field,
                               int index)
Returns the string array value contained in the field.

The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method.

Parameters:
field - An integer representing the field for which to return the value.
index - The index of the data within the field.
Returns:
A string array.
Since:
JDE 4.0.0

isModified

public boolean isModified()
Returns a boolean that indicates whether or not this PIMItem has been modified since the last commit or retrieval.

Returns:
A boolean.
Since:
JDE 4.0.0

maxCategories

public int maxCategories()
Returns the maximum number of categories that this item can be assigned to.

Returns:
An integer representing the maximum number of categories.
Since:
JDE 4.0.0

removeFromCategory

public void removeFromCategory(String category)
Removes a category from this item.

If the specified category is not associated with this item, the method call is considered successful and returns.

Parameters:
category - A string representing the name of the category to remove.
Throws:
NullPointerException - if category is null.
Since:
JDE 4.0.0

removeValue

public void removeValue(int field,
                        int index)
Removes a value from the specified field, given the index.

This method may invalidate the remaining data within the field, since the data is re-indexed once the value is removed.

Parameters:
field - The field from which to remove the value.
index - The index of the value within the field.
Since:
JDE 4.0.0

setBinary

public void setBinary(int field,
                      int index,
                      int attributes,
                      byte[] value,
                      int offset,
                      int length)
Sets an existing binary value in a field to a new value. The PIMList.isSupportedField(int) should be used to verify the validity of the field before invoking this method. This method cannot be used to add new values to a field.
Parameters:
field - The field to add the binary data to.
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 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:
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.
Since:
JDE 4.0.0

setBoolean

public void setBoolean(int field,
                       int index,
                       int attributes,
                       boolean value)
Sets an existing boolean value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:
field - The field in which the value exists.
index - The index of the value to change.
attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.
value - The new value.
Since:
JDE 4.0.0

setDate

public void setDate(int field,
                    int index,
                    int attributes,
                    long value)
Sets an existing date value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

In the event of a platform data restrictions, data will be rounded down.

Parameters:
field - The field in which the value exists.
index - The index of the value to change.
attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.
value - The new value.
Since:
JDE 4.0.0

setInt

public void setInt(int field,
                   int index,
                   int attributes,
                   int value)
Sets an existing integer value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:
field - The field in which the value exists.
index - The index of the value to change.
attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.
value - The new value.
Since:
JDE 4.0.0

setString

public void setString(int field,
                      int index,
                      int attributes,
                      String value)
Sets an existing string value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

Parameters:
field - The field in which the value exists.
index - The index of the value to change.
attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.
value - The new value.
Throws:
NullPointerException - Thrown if the value parameter is null.
Since:
JDE 4.0.0

setStringArray

public void setStringArray(int field,
                           int index,
                           int attributes,
                           String[] value)
Sets an existing string array value in a field.

The method PIMList.isSupportedField(int) should be invoked before this method is called in order to ensure that the field exists.

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.

Parameters:
field - The field in which the value exists.
index - The index of the value to change.
attributes - A byte array containing information about this field. Attributes can contain hints about the underlying implementation of the data.
value - The new value.
Since:
JDE 4.0.0



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.