javax.microedition.pim.PIM
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class PIM
Class for accessing PIM lists on a device and performing PIM wide functions. This class is a collection of static methods for getting the names of the existing PIM lists, opening the lists, and converting raw data streams to and from PIM items for importing and exporting into those lists.
This example assumes that the InputStream contains a valid
vCard 3.0 entry with the following characteristics:
Content-Type: text/directory; charset="UTF-8"; profile="vCard" Content-ID: <id3@host.com> Content-Transfer-Encoding: Quoted-PrintableThe content of the vCard looks like the following:
begin:VCARD source:ldap://cn=3Dbjorn%20Jensen, o=3Duniversity%20of%20Michigan, c=3DUS name:Bjorn Jensen fn:Bj=C3=B8rn Jensen n:Jensen;Bj=F8rn email;type=3Dinternet:bjorn@umich.edu tel;type=3Dwork,voice,msg:+1 313 747-4454 key;type=3Dx509;encoding=3DB:dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK end:VCARD
The following method assumes that the input stream is positioned at the first character of the vCard (i.e. the start of the "begin:" tag). For simplicity in this example, the method also hardcodes the transfer encoding of Quoted Printable and the data in the character set UTF-8.
void importVCard( InputStream is )
{
// Using application defined class QuotedPrintableInputStream ...
QuotedPrintableInputStream qpis = new QuotedPrintableInputStream( is );
try {
PIMItem[] items = PIM.getInstance().fromSerialFormat( qpis, "UTF-8" );
Contact c = (Contact) ( items[ 0 ] );
ContactList cl = (ContactList) PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.READ_WRITE );
cl.importContact( c );
} catch( PIMException pe ) {
} catch( IOException ioe ) {
}
}
This example exports a Contact to the provided output stream. The data format
used is the first data format returned from
PIM.supportedSerialFormats(int). Note that any transfer encoding, such
as applying Quoted Printable, is the responsibility of the application
outside of this method.
void exportVCard( Contact c, OutputStream os )
{
String[] data_formats = PIM.getInstance().supportedSerialFormats(
PIM.CONTACT_LIST );
try {
PIM.getInstance().toSerialFormat( c, os, "UTF-8", data_formats[ 0 ] );
} catch( PIMException pe ) {
} catch( IOException ioe ) {
}
}
The RIM extension functionality for the PIM class is defined
in BlackBerryPIM. Any instance of
PIM that is retrieved from PIM.getInstance() will be an
instance of BlackBerryPIM and can be successfully cast to
BlackBerryPIM, if desired, in order to use the RIM extension
functionality. Also, the RIM extension constants defined in
BlackBerryPIM are recognized by PIM,
so there is normally no need to perform the cast.
The standard calendar and contact list PIM applications on a BlackBerry device support multiple databases. When a device is associated with multiple accounts, such as BlackBerry Enterprise Server accounts and BlackBerry Internet Service accounts, each account has its own database for the calendar and the contact list PIM applications. For example, if a device is associated with both a BlackBerry Enterprise Server account and a BlackBerry Internet Service account, the calendar and contact list applications each have a database for each account.
PIM.listPIMLists(PIM.EVENT_LIST) returns a name for each individual EventList so that
they can be accessed individually. In previous versions of the software, the JSR75 PIM API only
returned a single EventList which provided access to all of the EventLists without distinguishing
between EventLists for different BlackBerry Enterprise Server accounts and BlackBerry Internet Service accounts.
PIM.listPIMLists(PIM.CONTACT_LIST) returns a name for each individual ContactList so that
they can be accessed individually. In previous versions of the software, the JSR75 PIM API only
returned a single ContactList which provided access to all of the ContactLists without
distinguishing between ContactLists for different BlackBerry Enterprise Server accounts and BlackBerry Internet Service accounts.
ToDoLists or BlackBerryMemoLists. The
ToDoList or BlackBerryMemoList returned from PIM.openPIMList() provides access to all of the
lists of that database without distinguishing between different BlackBerry Enterprise Server
accounts and BlackBerry Internet Service accounts.
BlackBerryPIMList.getPIMListUID() and a PIMList can be opened by its UID using
BlackBerryPIM.openPIMList(int, int, long). Support for PIMList UIDs was added in
BlackBerry software version 5.0.0.
ListChangeListener via BlackBerryPIM.addListChangeListener(ListChangeListener).
BlackBerryPIM| Field Summary | ||
|---|---|---|
static int |
CONTACT_LIST
Constant representing a Contact List. |
|
static int |
EVENT_LIST
Constant representing an Event List. |
|
static int |
READ_ONLY
Constant representing opening a list in read only mode. |
|
static int |
READ_WRITE
Constant representing opening a list in read/write mode. |
|
static int |
TODO_LIST
Constant representing a ToDo List. |
|
static int |
WRITE_ONLY
Constant representing opening a list in write only mode. |
|
| Constructor Summary | ||
|---|---|---|
protected |
PIM()
Constructor for subclasses. |
|
| Method Summary | ||
|---|---|---|
abstract PIMItem[] |
fromSerialFormat(InputStream is,
String enc)
Creates and fills one or more PIM items from data provided in the given InputStream object where the data is expressed in a valid
data format supported by this platform. |
|
static PIM |
getInstance()
Factory method to get an instance of the PIM class. |
|
abstract String[] |
listPIMLists(int pimListType)
Returns a list of all PIM List names for the given PIM list type. |
|
abstract PIMList |
openPIMList(int pimListType,
int mode)
Opens the default list for the indicated PIM list type. |
|
abstract PIMList |
openPIMList(int pimListType,
int mode,
String name)
Opens a named PIM List. |
|
abstract String[] |
supportedSerialFormats(int pimListType)
Returns the supported data formats for items used when converting a PIMItem's data to and from data streams. |
|
abstract void |
toSerialFormat(PIMItem item,
OutputStream os,
String enc,
String dataFormat)
Writes the data from the given item to the given OutputStream object as Unicode characters in a format
indicated by the String parameters. |
|
| 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 EVENT_LIST
public static final int READ_ONLY
public static final int READ_WRITE
public static final int TODO_LIST
public static final int WRITE_ONLY
| Constructor Detail |
|---|
protected PIM()
PIM class objects are not
instantiated directly; to access a PIM object,
PIM.getInstance() should be used.
| Method Detail |
|---|
public abstract PIMItem[] fromSerialFormat(InputStream is,
String enc)
throws PIMException,
UnsupportedEncodingException
InputStream object where the data is expressed in a valid
data format supported by this platform. The character stream starting
from the InputStream's current character position must
represent a complete entry as specified by the supported data format or
else a PIMException is thrown. Data representing
unsupported data entries and/or data fields is ignored as long as a valid
entry of a supported entry type is contained in the stream.
This method reads only one complete data entry from the
InputStream, leaving the InputStream
object open and its character position on the character after the end of
the entry, or at a position in the stream where an error is detected if
the data stream is in an invalid or incomplete format. A single valid
data entry in an InputStream results in the creation of
one or more PIMItems (in some data formats more than one
PIMItem may be in a single entry).
The format of the data in the InputStream determines what
type of PIM items are created (see PIM.supportedSerialFormats(int)
to see what data formats are supported by this implementation).
It is the responsibility of the application to perform any transfer
character decoding (such as Content-Transfer-Encoding for MIME or
Transfer-Encoding for HTTP) prior to providing the
InputStream object with the entry data to this method.
In creating PIM items, data from the input stream is taken and mapped to appropriate corresponding PIM item fields. If there is no appropriate corresponding PIM item field for a particular piece of data in the input stream, that data may be either silently discarded by this method or retained in the PIM item as an extended field value (the action taken is implementation specific). If the data from the input stream does not contain values for all of the fields required by the item, the VM may provide default values so that the information can still be received and PIM items can still be created.
Also note that creation of the PIM items does not add the item to any
list; the import method for a list capable of containing the specific PIM
item must be used to add the item to a list. For example, should a
Contact item be created, then the method
ContactList.importContact() should be invoked from an
existing list to import that contact into the target list.
is - an input stream containing PIM information in a well-known
data format supported by this method.enc - the character encoding of the characters in the input
stream; if null, the default character
encoding of UTF-8 is used.
InputStream. In some cases, more than one PIM
item may be created from a complete entry (for example, a single
vCalendar entry may produce two PIM items, both an
Event and a ToDo).
PIMException - If the data is incorrect, does not contain enough
information to form a complete entry, or a stream error
occurs.
NullPointerException - if is is null.
UnsupportedEncodingException - if enc is not a encoding method supported
on this platform.PIM.toSerialFormat(PIMItem, OutputStream, String, String),
PIM.supportedSerialFormats(int)public abstract String[] listPIMLists(int pimListType)
String
array is returned. The first name in the list is the name of the default
List for a type.
RIM Implementation Note: In the PIM instance
returned from PIM.getInstance() when used on BlackBerry smartphones,
this method also recognizes the PIM list types defined in the RIM
extensions to this class,
BlackBerryPIM, such as
MEMO_LIST.
pimListType - the PIM list type whose list names to return; valid values
include PIM.CONTACT_LIST, PIM.EVENT_LIST, and
PIM.TODO_LIST.
SecurityException - if the application is not given permission to read PIM
lists.
IllegalArgumentException - if pimListType is not a valid PIM list
type.
public abstract PIMList openPIMList(int pimListType,
int mode)
throws PIMException
RIM Implementation Note: In the PIM instance
returned from PIM.getInstance() when used on BlackBerry smartphones,
this method also recognizes the PIM list types defined in the RIM
extensions to this class,
BlackBerryPIM, such as
MEMO_LIST.
pimListType - the PIM list type to open; valid values include
PIM.CONTACT_LIST, PIM.EVENT_LIST, and
PIM.TODO_LIST.mode - the mode in which the List is opened; must be one of
PIM.READ_ONLY, PIM.READ_WRITE, or
PIM.WRITE_ONLY.
PIMException - If the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match
the requested mode.
IllegalArgumentException - If an invalid mode is provided as a
parameter or if pimListType is not a valid
PIM list type.PIM.openPIMList(int, int, String),
BlackBerryPIM.openPIMList(int, int, long)
public abstract PIMList openPIMList(int pimListType,
int mode,
String name)
throws PIMException
PIM.listPIMLists(int) can be used to open a list.
RIM Implementation Note: In the PIM instance
returned from PIM.getInstance() when used on BlackBerry smartphones,
this method also recognizes the PIM list types defined in the RIM
extensions to this class,
BlackBerryPIM, such as
MEMO_LIST.
For information about multiple PIMList support, see Multiple PIMList Support.
pimListType - the PIM list type to open; valid values include
PIM.CONTACT_LIST, PIM.EVENT_LIST, and
PIM.TODO_LIST.mode - the mode in which the List is opened; must be one of
PIM.READ_ONLY, PIM.READ_WRITE, or
PIM.WRITE_ONLY.name - the name of the list to open
PIMException - If the list is not available, the operation is
unsupported or an error occurs.
SecurityException - if the application is not given permissions that match
the requested mode.
IllegalArgumentException - If an invalid mode is provided as a
parameter or if pimListType is not a valid
PIM list type.
NullPointerException - If name is null.PIM.openPIMList(int, int),
BlackBerryPIM.openPIMList(int, int, long)public abstract String[] supportedSerialFormats(int pimListType)
PIMItem's data to and from data streams. The return value
is suitable for use as the data format parameter in
PIM.toSerialFormat(PIMItem, OutputStream, String, String). The
naming convention for the strings returned is the common name of the data
format in all capital letters, followed by a slash ("/"), and then
followed by the version number of the data format. For example
"VCARD/2.1" or "VCALENDAR/1.0".
pimListType - the PIM list type whose supported serial formats to
return; valid values include PIM.CONTACT_LIST,
PIM.EVENT_LIST, and PIM.TODO_LIST.
IllegalArgumentException - if pimListType is not a valid PIM list
type.PIM.toSerialFormat(PIMItem, OutputStream, String, String),
PIM.fromSerialFormat(InputStream, String)
public abstract void toSerialFormat(PIMItem item,
OutputStream os,
String enc,
String dataFormat)
throws PIMException,
UnsupportedEncodingException
OutputStream object as Unicode characters in a format
indicated by the String parameters. The character encoding for those
characters written to the OutputStream is in the provided
character encoding. The data format specified must be supported by the
PIM implementation (see PIM.supportedSerialFormats(int)) or else an
IllegalArgumentException is thrown. After this method is
invoked, the OutputStream contains the item as a data
stream in the given data format. The output produced is a single complete
entry and suitable for exchange with other programs supporting that data
format. The OutputStream is left open and any writes to
that stream occurs at the position immediately after the entry just
written.
All data fields contained in the provided PIMItem are
written out to the output stream in the specified format. Fields that do
not have specific corresponding fields in the data format specified are
written as extended fields if the data format supports extended fields.
It is the responsibility of the application to perform any further character encoding needed for transportation of the vCard entry (such as Content-Transfer-Encoding for MIME or Transfer-Encoding for HTTP).
item - the item to export to the OutputStream
object.os - the OutputStream object that the item is
written to as a character stream.enc - the character encoding used to write the
PIMItem to the OutputStream;
if null, the default character encoding of
UTF-8 is used.dataFormat - he requested PIM data format to use (i.e. the well-known
structure of the data prior to character encoding)
PIMException - if an error occurs when converting the item's data or if
a stream error occurs, preventing the data from being
written in a complete and valid form. There is no
guarantee that the OutputStream is
unmodified or contains complete information if this
exception is thrown.
NullPointerException - if one or more of os,
dataFormat or item is null.
UnsupportedEncodingException - if enc is not a encoding method supported
on this platform.
IllegalArgumentException - if dataFormat is not a valid format; that
is, dataFormat is not equal to one of the
strings returned from
PIM.supportedSerialFormats(int) when specified the
PIM list type of item.PIM.fromSerialFormat(InputStream, String),
PIM.supportedSerialFormats(int)public static PIM getInstance()
PIM class.
PIM class.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal