|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object | +--javax.microedition.pim.PIM
Class for accessing the PIM databases on a device.
Contains static methods for performing operations on lists.
For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.
PIMItem,
PIMList| Field Summary | ||
static int |
CONTACT_LIST
Represents the Contact list type. |
|
static int |
EVENT_LIST
Represents the Event list type. |
|
static int |
READ_ONLY
Indicates that the list is open in read-only mode. |
|
static int |
READ_WRITE
Indicates that the list is open in read-write mode. |
|
static int |
TODO_LIST
Represents the ToDo list type. |
|
static int |
WRITE_ONLY
Indicates that the list is open in write-only mode. |
|
| Constructor Summary | ||
protected |
PIM()
PIM objects should be created using the getInstance() method. |
|
| Method Summary | ||
abstract PIMItem[] |
fromSerialFormat(InputStream is,
String enc)
Creates a PIMItem instance given a valid data InputStream. |
|
static PIM |
getInstance()
Returns a PIM instance. |
|
abstract String[] |
listPIMLists(int pimListType)
Returns an array of strings representing the names of all valid PIM lists of the specified type. |
|
abstract PIMList |
openPIMList(int pimListType,
int mode)
Opens the default list of the specified list type. |
|
abstract PIMList |
openPIMList(int pimListType,
int mode,
String name)
Opens the specified PIM list. |
|
abstract String[] |
supportedSerialFormats(int pimListType)
Returns the supported serial formats for a PIMItem object. |
|
abstract void |
toSerialFormat(PIMItem item,
OutputStream os,
String enc,
String dataFormat)
Serializes a PIMItem instance. |
|
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
public static final int CONTACT_LIST
public static final int READ_ONLY
public static final int READ_WRITE
public static final int WRITE_ONLY
| Constructor Detail |
| Method Detail |
public abstract PIMItem[] fromSerialFormat(InputStream is, String enc) throws PIMException, UnsupportedEncodingException
PIMItem instance given a valid data InputStream.
The format of the first characters of the incoming data determine what type of PIM items
are created (see supportedSerialFormats(int) to see what data formats are actually
supported.
The default encoding type is UTF8.
Importing data from serial format
Below, the fromSerialFormat method is invoked to create an
array of PIMItems. The ContactList.importContact()
method is then invoked to add a new Contact to the list.
The following example demonstrates how to convert an existing Contact
into a vCard and then import the vCard into a new Contact.
PIM pim = PIM.getInstance();
String[] dataFormats = pim.supportedSerialFormats(PIM.CONTACT_LIST);
//write contact to vCard
ByteArrayOutputStream ostream = new ByteArrayOutputStream();
pim.toSerialFormat(contact, ostream, "UTF8", dataFormats[0]);
//import contact from vCard
ByteArrayInputStream istream = new ByteArrayInputStream(ostream.toByteArray());
PIMItem[] pi = pim.fromSerialFormat(istream, "UTF8");
ContactList contacts = (ContactList) pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
Contact contact2 = contacts.importContact((Contact)pi[0]);
contacts.close();
Note:PIM data suffers a slight precision loss when converting PIM Date data to serial format since the serialization process does not provide millisecond precision. While this loss of precision will likely not effect the integrity of your Date data, it will cause any comparisons between serialized and unserialized PIM objects to fail.
is - The data inputstream containing the serialized data.enc - The encoding type.PIMException - Thrown if an error occurs with the list.UnsupportedEncodingException - Thrown if the specified
encoding type is unsupported or unknown.public static PIM getInstance()
PIM object.public abstract String[] listPIMLists(int pimListType)
A zero-length array is returned if no lists exist. The first name in the list represents the default list.
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).public abstract PIMList openPIMList(int pimListType, int mode) throws PIMException
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).mode - An integer representing the mode (READ_ONLY, WRITE_ONLY, READ_WRITE)
in which to open the list.PIMList instance.PIMException - Thrown if an error occurs with the list.public abstract PIMList openPIMList(int pimListType, int mode, String name) throws PIMException
For a list of available PIM lists, invoke the listPIMLists(int) method.
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).mode - An integer representing the mode (READ_ONLY, WRITE_ONLY, READ_WRITE)
in which to open the list.name - The name of the contact list to open.PIMList instance.PIMException - Thrown if an error occurs with the list.public abstract String[] supportedSerialFormats(int pimListType)
PIMItem object.
The first element of the return value (an array of strings) can be used as the data format parameter in the
toSerialFormat method.
The default encoding type is UTF8.
pimListType - The type of the PIMList.public abstract void toSerialFormat(PIMItem item, OutputStream os, String enc, String dataFormat) throws PIMException, UnsupportedEncodingException
PIMItem instance.
The format of the encoding must be supported by the API. The format of
the first characters of
the incoming data determine what type of PIM items
are created (see supportedSerialFormats(int) to see what data formats are actually
supported.
The default encoding type is UTF8.
Converting data to serial format
Data can be imported or exported from PIMItems using using standard formats, such as iCal and vCard. The following example demonstrates how to export all the contacts from the handheld Address Book to a supported serial format, using an output stream writer:
PIM pim = PIM.GetInstance();
ContactList cl = (ContactList)pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY);
ByteArrayOutputStream output = new ByteArrayOutputStream();
String[] dataFormats = pim.supportedSerialFormats(PIM.CONTACT_LIST);
Enumeration e = cl.items();
while (e.hasMoreElements()) {
Contact c = (Contact)e.nextElement();
pim.toSerialFormat(c, output, "UTF8", dataFormats[0]);
}
cl.close();
Note:PIM data suffers a slight precision loss when converting PIM Date data to serial format since the serialization process does not provide millisecond precision. While this loss of precision will likely not effect the integrity of your Date data, it will cause any comparisons between serialized and unserialized PIM objects to fail.
item - The PIMItem to be serialized.os - The OutputStream to write the data to.enc - The encoding type.dataFormat - The data format to use.PIMException - Thrown if an error occurs during the encoding.UnsupportedEncodingException - Thrown if the specified
encoding type is unsupported or unknown.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2007 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.