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 label
0 or more data values
attributes for data values
a data type
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 mulitple 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.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
ATTR_NONE
public static final int ATTR_NONE
Indicates that no additional attributes are applicable for this field.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
EXTENDED_FIELD_MIN_VALUE
public static final int EXTENDED_FIELD_MIN_VALUE
Represents the minimum value for an extended field constant.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
EXTENDED_ATTRIBUTE_MIN_VALUE
public static final int EXTENDED_ATTRIBUTE_MIN_VALUE
Represents the minimum value for an extended attribute constant.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
getBinary
public byte[] getBinary(int field,
int index)
Returns a byte array containing a binary representation of the data
within the given field.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addBinary
public void addBinary(int field,
int attributes,
byte[] value,
int offset,
int length)
attributes - An integer specifying any attributes that describe this
field.
value - The data, a byte array containing a "B" binary encoded
string, to add to the field.
offset - The offset, or initial position of the data, within the
array.
length - The length of data in the array.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addDate
public void addDate(int field,
int attributes,
long value)
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addInt
public void addInt(int field,
int attributes,
int value)
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addString
public void addString(int field,
int attributes,
String value)
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. The null value is an acceptable value.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
getStringArray
public String[] getStringArray(int field,
int index)
Returns the string array value contained in the field.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addStringArray
public void addStringArray(int field,
int attributes,
String[] value)
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
addBoolean
public void addBoolean(int field,
int attribute,
boolean value)
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Use the getCategories() method to return 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
operation will be considered a success.
Parameters:
category - A string representing the name of the category.
Throws:
PIMException - Thrown if the specified category is invalid or if
the maximum number of categories has already been exceeded.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Use the getCategories() method to return 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
operation will be considered a success.
Parameters:
category - A string representing the name of the category.
Throws:
PIMException - Thrown if the specified category is invalid or if
the maximum number of categories has already been exceeded.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
setBinary
public void setBinary(int field,
int index,
int attributes,
byte[] value,
int offset,
int length)
Sets an existing binary 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 - A byte array containing new value to set.
offset - The offset of the data within the array.
length - The length (the number of bytes to read, starting from the
beginning of the array) of the data within the array.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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.
Since:
JDE 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
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 3.6
Category:
Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.
Copyright 1999-2002 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
