|
Mobile handsets such as cellphones typically have an address book to keep track of people we like to stay in touch with, a calendar to keep track of important events, and a to-do list to keep track of items we don't want to forget. This type of personal information is one of the most important functions found in a handset, just second to voice. You can use the PIM API for Java ME to enable your mobile Java applications to read and write to/from the locally stored personal information databases. You can even write synchronizers to keep your handset PIM data in-sync with remote PIM data stores. This article, part 2 of this series on using the PIM API for Java ME, introduces porting considerations when using the PIM API for Java ME.
Contents
Testing for the Presence of the PIM API
You can test if the PIM API for J2ME optional package is supported on the handset, by calling the method System.getProperty(String property), passing as argument the String value "microedition.pim.version". The method call will return (a non-null String) the version of the API such as "1.0" if the optional package is present, and null if the API is not present. The following code snippet shows how to do this:
/**
* Test if the PIM API is supported.
* @return true if the PIM API is supported, false otherwise
*/
static public boolean isPimApiSupported() {
boolean isSupported = true;
String pimApiVersion =
System.getProperty("microedition.pim.version");
if (pimApiVersion == null) {
isSupported = false;
}
return isSupported;
}
:
// Test if PIM API is supported
if (isPimApiSupported() == true)
System.out.println("PIM API IS supported");
else
System.out.println("PIM API is NOT supported");
|
Testing for Supported PIM Databases
Not all PIM database types (ContactList, EventList, ToDoList) might be supported on a given handset PIM implementation; note that the PIM API specification only mandates support for one of the types. Call the method PIM.openList(int listType, mode) to test if a specific list type is supported. The following code snippet shows how to test if the calendar events database is supported:
/**
* Helper method to test if calendar events database types are supported.
*
* @return true if calendar/events databases are supported, and false
* if event databases are not supported or if permission to use use the
* PIM API is denied.
*/
static public boolean isEventListSupported() {
boolean retVal;
EventList el = null;
try {
// Try to open the event list; this will tell us if it is supported
el = (EventList) pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
retVal = true;
} catch (SecurityException e) {
retVal = false; // Unknown since access to API was denied
} catch (PIMException e) {
retVal = false;
} finally {
if (el != null) {
try {
// Close the event list since we only opened it to
// see if it is supported.
el.close();
} catch (PIMException ignore) {
// ignore
}
}
}
return retVal;
}
|
If the specified list type is not supported, the call to PIM.openList() will throw a PIMException. If the MIDlet doesn't have permission to use the PIM API, a SecurityException is thrown, meaning that we can't determine if the list type is supported since access to the API was denied. Note that typically all three types of databases will be found on a handset, and that multiple lists may exists for each list type, for example, some Nokia handsets support various Event lists, for meetings, reminders, calls, memos and birthdays.
Testing for Supported Fields
Not all PIM implementations support all the fields or attributes defined in the PIM API specification. Before using a field or an attribute, you should test if it is supported, otherwise you will get an UnsupportedFieldException or an IllegalArgumentException:
- To test if a particular simple field is supported call the method
PIMList.isSupportedField(int fieldID)
- To test if a particular
STRING_ARRAY field is supported call the method PIMList.isSupportedArrayElement(int stringArrayFieldID, int arrayElement)
- To test if a particular attribute for a particular field is supported call the method
PIMList.isSupportedAttribute(int fieldID, int attributeID)
- To get (and subsequently) test if a particular
RepeatRule field is supported for a specific recurring frequency call the method EventList.getSupportedRepeatRuleFields(int frequency)
The following code snippet shows how to test if the Event.ALARM field is supported:
if (eventList.isSupportedField(Event.ALARM) == true) {
// Event.ALARM field is supported; it is safe to use it
:
}
|
The rest of the isSupportedXXX methods listed above follow the same pattern as the above code example. Recall that field and attribute IDs are all specific to PIM items and are defined in their respective Contact, Events and ToDo PIM item sub-interfaces.
The following code snippets show how to test if a RepeatRule field is supported for the specified frequency:
/**
* Tests if the specified RepeatRule field is supported
* @param el the EventList to test
* @param frequency the RepeatRule frequency: DAILY, WEEKLY, MONTHLY, YEARLY
* @param field the RepeatRule field to test
* @return true if the field is valid for the specified frequency, false if otherwise
*/
public boolean isRepeatRuleFieldSupported(EventList el, int frequency, int field) {
boolean isSupported = false;
int[] supportedFields = el.getSupportedRepeatRuleFields(frequency);
for (int i = 0; i < supportedFields.length; i++) {
if (supportedFields[i] == field) {
isSupported = true;
break;
}
}
return isSupported;
}
|
The following code snippet shows how to use the above helper method to test if the repeat rule field RepeatRule.END is supported for repeat rule frequency RepeatRule.DAILY:
:
EventList el = ...;
:
boolean isSupported = isRepeatRuleFieldSupported(el, RepeatRule.DAILY, RepeatRule.END);
if (isSupported) == true) {
// RepeatRule.END is supported!
}
:
|
Many thanks to Kevin Lym, Vasily Isaenko, and Alexander Glasman for all their feedback and helping improve this article.
C. Enrique Ortiz is a mobile technologist, software architect and developer, and a writer and blogger. He has been author or co-author of many publications, and is an active participant in the Java mobility community and in various Java ME Expert Groups. Enrique holds a B.S. in Computer Science from the University of Puerto Rico and has more than 17 years of software engineering, product development, and management experience.
|
|
Print-friendly Version
