PDAP Public Review Draft

javax.microedition.pim
Interface PIMElement

All Known Subinterfaces:
Contact, Event, ToDo

public interface PIMElement

Represents the common interfaces of an element for a PIM database. A PIM element is a container that references its data through fields. A PIM element is created from a particular PIM list and is associated with that list for the life of the element. The element takes on the field characteristics of the list that is it created or retrieved from; that is, the list dictates what fields that this element contains.

Field are referenced through fields IDs assigned by the implementing class to each piece of data that can be stored in a PIM element. This field ID is used to set the data and to retrieve the data.

The implementing class assigns and expects a data type for the data associated with a field ID. The data type for a field ID can be retrieved through getFieldDataType(int).

Additionally, a human readable label is also assigned to each field. The label can be retrieved through getFieldLabel(int).

PIM elements may be assigned to categories, depending on the implementing PIM list class that the element is associated with. Categories are arbitrary named groupings of elements within a list. The list determines if categories can be assigned, and how many categories can be assigned per element.

PIM elements 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 element.

Data

An element contains three types of data:

Named fields are items that are referenced by the explicit field names defined in this class.

Some named fields also have a further defining type ID associated with them. This allows for the appearance of more than one instance of a field.

Extended fields are fields that does not have a specific field explicitly predefined in the API, but do have field ids assigned by the contact list. These fields are implementation dependent and can vary. Users can find out a field id is is extended field through the method PIMList.isExtendedField(int). Users can also find out the data type for the field (getFieldDataType(int)) and the human readable label for the field (getFieldLabel(int)). Extended fields use the same get and set methods as named fields.

Categories are string items that may correspond to categories values already existing in the PIMElement's associated PIMList.

Since:
PDAP 1.0

Field Summary
static int BINARY
          Data type ID indicating data is binary (in a byte array).
static int DATE
          Data type ID indicating data is a Date.
static int INT
          Data type ID indicating data is an integer.
static int STRING
          Data type ID indicating data is a String.
static int TYPED_STRING
          Data type ID indicating data is a String with a further qualifying integer type.
 
Method Summary
 void addToCategory(java.lang.String category)
          Adds a category to this element.
 void commit()
          This method persists the data in the element to its PIM list.
 void fromSerialFormat(Reader reader)
          Initializes a Element from information contained in a stream of Unicode characters.
 byte[] getBinary(int fieldID)
          Get binary data for a field from the Element.
 java.lang.String[] getCategories()
          Returns all the categories for that the Element belongs to.
 long getDate(int fieldID)
          Get a Date field from the Element.
 int getFieldDataType(int fieldID)
          Returns an int representing the data type of the data associated with the given field ID.
 java.lang.String getFieldLabel(int fieldID)
          Returns a String label associated with the given field ID.
 int[] getFields()
          Returns all field IDs in the element that have data stored for them.
 int getInt(int fieldID)
          Get an integer field from the Element.
 PIMList getPIMList()
          Returns the PIMList associated with this element.
 java.lang.String getString(int fieldID)
          Get a String field from the Element.
 java.lang.String getTypedString(int fieldID, int typeID)
          Get a String field with a specific type in the element.
 boolean isModified()
          This method returns a boolean indicating whether any of this element's fields have been modified since the element was retrieved or last committed.
 int maxCategories()
          Returns the maximum number of categories that this element can be assigned to.
 void removeFromCategory(java.lang.String category)
          Remove a category from this Element.
 void setBinary(int fieldID, byte[] data)
          Set a binary data field for the Element.
 void setDate(int fieldID, long value)
          Set a Date field in the Element.
 void setInt(int fieldID, int value)
          Set an integer field in the Element.
 void setString(int fieldID, java.lang.String value)
          Set a String field in the Element.
 void setTypedString(int fieldID, int typeID, java.lang.String value)
          Set a String field with a specific type ID in the element.
 java.lang.String[] supportedSerialVersions()
          This method returns the versions supported for the data format used on converting this element's data to and from a serial format.
 void toSerialFormat(Writer writer)
          Writes the data from this element as a stream of Unicode characters into the provided Writer object.
 void toSerialFormat(Writer writer, java.lang.String version)
          Writes the data from this element as a stream of Unicode characters into the provided Writer object.
 

Field Detail

BINARY

public static final int BINARY
Data type ID indicating data is binary (in a byte array). Data associated with BINARY is retrieved via getBinary(int) and set via setBinary(int, byte[]).
Value 0 is assigned to BINARY.

DATE

public static final int DATE
Data type ID indicating data is a Date. Data associated with DATE is retrieved via getDate(int) and set via setDate(int, long).
Value 1 is assigned to DATE.

INT

public static final int INT
Data type ID indicating data is an integer. Data associated with INT is retrieved via getInt(int) and set via setInt(int, int).
Value 2 is assigned to INT.

STRING

public static final int STRING
Data type ID indicating data is a String. Data associated with is retrieved via getString(int) and set via setString(int, java.lang.String).
Value 3 is assigned to STRING.

TYPED_STRING

public static final int TYPED_STRING
Data type ID indicating data is a String with a further qualifying integer type. Data associated with TYPED_STRING is retrieved via getTypedString(int, int) and set via setTypedString(int, int, java.lang.String).
Value 4 is assigned to TYPED_STRING.
Method Detail

getPIMList

public PIMList getPIMList()
Returns the PIMList associated with this element. An element will always have the same list associated with it for its life as an object.

commit

public void commit()
            throws PIMException
This method persists the data in the element to its PIM list. As data is changed in an element 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 element to be persisted which are not in the list returned from PIMList.getCategories(). In this case the categories will be dropped silently when this method is invoked (this allows data imported using fromSerialFormat(java.io.Reader) to be persisted).
Throws:
PIMException - if the commit encounters an error and cannot complete.
SecurityException - if the application has not been granted write access to the PIM list.

isModified

public boolean isModified()
This method returns a boolean indicating whether any of this element's fields have been modified since the element was retrieved or last committed.
Returns:
boolean true if any fields have been modified since the element was laste retrieved or committed, false otherwise.

getFieldDataType

public int getFieldDataType(int fieldID)
                     throws PIMException
Returns an int representing the data type of the data associated with the given field ID. This method is useful for some field IDs that may have different types of data per element.
Parameters:
fieldID - The ID of the field for which the data type is being queried.
Returns:
int representing the type of the data associated with the field.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getFieldLabel

public java.lang.String getFieldLabel(int fieldID)
                               throws PIMException
Returns a String label associated with the given field ID.
Parameters:
fieldID - The ID of the field for which the label is being queried.
Returns:
String label for the field.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the implementing class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getFields

public int[] getFields()
Returns all field IDs in the element that have data stored for them. This allows quick access to all of the data stored in the elemtn without having to iterate through all supported fields and checking if data is stored for the field or not.
Returns:
int array of field IDs that have data stored for them.

getBinary

public byte[] getBinary(int fieldID)
                 throws PIMException
Get binary data for a field from the Element.
Parameters:
fieldID - The ID of the field to get.
Returns:
a byte array representing the value of the field, or null to indicate the field has not been set. 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 ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

setBinary

public void setBinary(int fieldID,
                      byte[] data)
               throws PIMException
Set a binary data field for the Element.
Parameters:
fieldID - The ID of the field to set.
data - The data to set the field to. Setting a field to null has the effect of clearing 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].
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getDate

public long getDate(int fieldID)
             throws PIMException
Get a Date field from the Element.
Parameters:
fieldID - The field ID to get.
Returns:
a Date in long ms format representing the value of the field or null to indicate the field has not been set.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

setDate

public void setDate(int fieldID,
                    long value)
             throws PIMException
Set a Date field in the Element.
Parameters:
fieldID - The field ID to set.
value - The value to set the field to. Setting a field to 0 has the effect of clearing it.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getInt

public int getInt(int fieldID)
           throws PIMException
Get an integer field from the Element.
Parameters:
fieldID - The field ID to get.
Returns:
an int representing the value of the field.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

setInt

public void setInt(int fieldID,
                   int value)
            throws PIMException
Set an integer field in the Element.
Parameters:
fieldID - The field ID to set.
value - The value to set the field to.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getString

public java.lang.String getString(int fieldID)
                           throws PIMException
Get a String field from the Element.
Parameters:
fieldID - The field ID to get.
Returns:
a String representing the value of the field or null to indicate the field has not been set.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

setString

public void setString(int fieldID,
                      java.lang.String value)
               throws PIMException
Set a String field in the Element.
Parameters:
fieldID - The field ID to set.
value - The value to set the field to. Setting a field to null has the effect of clearing it.
Throws:
java.lang.IllegalArgumentException - if the field ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

getTypedString

public java.lang.String getTypedString(int fieldID,
                                       int typeID)
                                throws PIMException
Get a String field with a specific type in the element.
Parameters:
fieldID - The field ID to get.
typeID - The specific type for the field to retrieve.
Returns:
a String representing the value of the field/type or null to indicate the field/type has not been set.
Throws:
java.lang.IllegalArgumentException - if the field ID or type ID is not valid for the derived class.
PIMException - if the field ID is not supported in the implementing instance of the class.

setTypedString

public void setTypedString(int fieldID,
                           int typeID,
                           java.lang.String value)
                    throws PIMException
Set a String field with a specific type ID in the element.
Parameters:
fieldID - The field ID to set.
typeID - The type ID for the field.
value - The value to set the field to. Setting a field to null has the effect of clearing it.
Throws:
java.lang.IllegalArgumentException - if the field ID or type ID is not valid for the derived class.
PIMException - if the field ID 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 element. It is recommended to use the category names defined in PIMList.getCategories() from the list associated with this element. 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. The category names are case sensitive in the javax.microedition.pim package.
Parameters:
category - the category to add
Throws:
java.lang.IllegalArgumentException - 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.

removeFromCategory

public void removeFromCategory(java.lang.String category)
Remove a category from this Element. The category names are case sensitive in the javax.microedition.pim package.
Parameters:
category - the category to remove
Throws:
java.lang.IllegalArgumentException - if category is null

getCategories

public java.lang.String[] getCategories()
Returns all the categories for that the Element belongs to. If there are no categories assigned to this Element, a zero length array is returned.
Returns:
a string arrary of all the categories for the Element.

maxCategories

public int maxCategories()
Returns the maximum number of categories that this element can be assigned to. 0 indicates no category support. -1 indicates there is no limit to the number of categories that this element can be assigned to.
Returns:
int the number of categories this element can be assigned to. 0 indicates no category support and -1 indicates there is no limit to the number of categories that this element can be assigned to.

fromSerialFormat

public void fromSerialFormat(Reader reader)
                      throws PIMException
Initializes a Element from information contained in a stream of Unicode characters. The format of the information in the character stream that is expected by this method is defined by the implementing class.
Parameters:
reader - a character stream contained in a java.io.Reader object.
Throws:
PIMException - If the data is incorrect, or does not contain enough information.
java.lang.IllegalArgumentException - if reader is null.

toSerialFormat

public void toSerialFormat(Writer writer)
                    throws PIMException
Writes the data from this element as a stream of Unicode characters into the provided Writer object. The format of the information written to the Writer object is defined by the implementing class. The default version of the data format for the implementation is used. After this method is invoked, the writer will contain the element as a character stream.
Parameters:
writer - the Writer object that this element is written to as a character stream.
Throws:
PIMException - if an error occurs when coverting the Element's data preventing the element's data from completely being written. There is no guarantee that the Writer will be unmodified or contain incomplete information if this exception is thrown.
java.lang.IllegalArgumentException - if writer is null .

toSerialFormat

public void toSerialFormat(Writer writer,
                           java.lang.String version)
                    throws PIMException
Writes the data from this element as a stream of Unicode characters into the provided Writer object. The format of the information written to the Writer object is defined by the implementing class and it supplemented by the version parameter to represent the version of the format the data will be output in. After this method is invoked, the writer will contain the element as a character stream.
Parameters:
writer - the Writer object that this element is written to as a character stream.
version - the requested version of the data format to use
Throws:
PIMException - if an error occurs when coverting the Element's data preventing the element's data from completely being written. There is no guarantee that the Writer will be unmodified or contain incomplete information if this exception is thrown. Also thrown if the provided version is not supported by the implementation.
java.lang.IllegalArgumentException - if writer is null or version is null.

supportedSerialVersions

public java.lang.String[] supportedSerialVersions()
This method returns the versions supported for the data format used on converting this element's data to and from a serial format. The return value is suitable for use in toSerialFormat(java.io.Writer, String).
Returns:
String array of data format versions supported for this element.

PDAP 1.0 Spec, Rev. 0.16