|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.
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 |
public static final int ATTR_NONE
public static final int 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.
public static final int 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.
public static final int 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.
public static final int EXTENDED_ATTRIBUTE_MIN_VALUE
public static final int EXTENDED_FIELD_MIN_VALUE
public static final int INT
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.
public static final int 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.
public static final int 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.
| Method Detail |
public void addBinary(int field,
int attributes,
byte[] value,
int offset,
int length)
PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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 .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.
public void addBoolean(int field,
int attribute,
boolean value)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.
public void addDate(int field,
int attributes,
long value)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.
public void addInt(int field,
int attributes,
int value)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.
public void addString(int field,
int attributes,
String value)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.NullPointerException - Thrown if the value parameter is null.
public void addStringArray(int field,
int attributes,
String[] value)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.public void addToCategory(String category) throws PIMException
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.
category - A string representing the name of the category.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.
public void commit()
throws PIMException
PIMItem to the list.
Categories that are specified in the PIMItem that are not
supported by the PIMList will be discarded.
PIMException - Thrown if an error occurs with the item, or the
list could not be accessed.public int countValues(int field)
field - The field to check.
public int getAttributes(int field,
int index)
field - The field from which to return the attributes.index - The index of the value within the field.
public byte[] getBinary(int field,
int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
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.
public boolean getBoolean(int field,
int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
field - An integer representing the field for which to return the
boolean.index - The index of the data within the field.public String[] getCategories()
If no categories are specified, a zero-length string array is returned.
public long getDate(int field,
int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
field - An integer representing the field for which to return the
date.index - The index of the data within the field.public int[] getFields()
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.
public int getInt(int field,
int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
field - An integer representing the field for which to return the
value.index - The index of the data within the field.public PIMList getPIMList()
PIMList that contains this item.
PIMList object.public String getString(int field, int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
field - An integer representing the field for which to return the
value.index - The index of the data within the field.public String[] getStringArray(int field, int index)
The PIMList.isSupportedField(int) should be used to verify the
validity of the field before invoking this method.
field - An integer representing the field for which to return the
value.index - The index of the data within the field.public boolean isModified()
PIMItem
has been modified since the last commit or retrieval.
public int maxCategories()
public void removeFromCategory(String category)
If the specified category is not associated with this item, the method call is considered successful and returns.
category - A string representing the name of the category to remove.NullPointerException - if category is null.
public void removeValue(int field,
int index)
This method may invalidate the remaining data within the field, since the data is re-indexed once the value is removed.
field - The field from which to remove the value.index - The index of the value within the field.
public void setBinary(int field,
int index,
int attributes,
byte[] value,
int offset,
int length)
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.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 .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.
public void setBoolean(int field,
int index,
int attributes,
boolean value)
The method PIMList.isSupportedField(int) should be invoked before
this method is called in order to ensure that the field exists.
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.
public void setDate(int field,
int index,
int attributes,
long value)
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.
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.
public void setInt(int field,
int index,
int attributes,
int value)
The method PIMList.isSupportedField(int) should be invoked before
this method is called in order to ensure that the field exists.
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.
public void setString(int field,
int index,
int attributes,
String value)
The method PIMList.isSupportedField(int) should be invoked before
this method is called in order to ensure that the field exists.
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.NullPointerException - Thrown if the value parameter is null.
public void setStringArray(int field,
int index,
int attributes,
String[] value)
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.
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.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
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.