Managing Personal Information - Using the PIM API for Java ME

import javax.microedition.pim.*;
:

pim = PIM.getInstance(); // retrieve instance of PIM
:

/**
 * Set (updates) the event fields
 * @param event the event to set
 * @param startDate the event's start date/time
 * @param endDate the event's end date/time
 * @param summary the event's summary description
 * @param location the event's location
 * @param note the event's note for further description
 * @param privacyClass the event's privacy class: private, public
 * @param alarm the event's delta time for the event's alarm (i.e. 5 minutes prior)
 * @param uid the event's unique ID
 * @return true if info successfully added, false otherwise
 */
static public boolean setEventInfo(
        Event event,
        long startDate,   // START
        long endDate,     // END
        String summary,   // SUMMARY
        String location,  // LOCATION
        String note,      // NOTE
        int privacyClass, // CLASS
        int alarm) {      // ALARM
    boolean status = false;
    if (event == null) {
        return false;
    }
    // Get the list for the event
    PIMList eventList = event.getPIMList();
    if(eventList == null) {
       return false; // event doesn't belong to a list
    }
    if ((eventList.isSupportedField(Event.START) == true) && 
        (startDate != -1)) {
        event.setDate(Event.START, 0, PIMItem.ATTR_NONE,   startDate);
    }
    if ((eventList.isSupportedField(Event.END) == true) &&
        (endDate != -1)) {
        event.setDate(Event.END, 0, PIMItem.ATTR_NONE, endDate);
    }
    if ((eventList.isSupportedField(Event.SUMMARY) == true) &&
        (summary != null)) {
        event.setString(Event.SUMMARY, 0, PIMItem.ATTR_NONE, summary);
    }
    if ((eventList.isSupportedField(Event.LOCATION) == true) &&
        (location != null)) {
        event.setString(Event.LOCATION, 0, PIMItem.ATTR_NONE, location);
    }
    if ((eventList.isSupportedField(Event.NOTE) == true) &&
        (note != null)) {
        event.setString(Event.NOTE, 0, PIMItem.ATTR_NONE, note);
    }
    if ((eventList.isSupportedField(Event.CLASS) == true) &&
        (privacyClass != -1)) {
        event.setInt(Event.CLASS, 0, PIMItem.ATTR_NONE, privacyClass);
    }
    if ((eventList.isSupportedField(Event.ALARM) == true) &&
        (alarm != -1)) {
        event.setInt(Event.ALARM, 0, PIMItem.ATTR_NONE, alarm);
    }
    return true;
}

/**
 * Generic PIMItem get string field accessor method.
 * @pimItem the PIM item to reference
 * @param id the field id to retrieve
 * @param index the value id to retrieve
 */
static public String getSimpleStringField(
        PIMItem pimItem,
        int id,
        int index) {
    if (pimItem == null) {
        return null;
    }
    // Get the list for the item
    PIMList pimList = pimItem.getPIMList();
    if(pimList == null) {
       return null; // PIM item doesn't belong to a list
    }
    if (pimList.isSupportedField(id) == false) {
        return null;
    }
    return pimItem.getString(id, index);
}

/**
 * Generic PIMItem get compound string field accessor method.
 * @pimItem the PIM item to reference
 * @param id the field id to retrieve
 * @param index the value id to retrieve
 */
static public String getCompoundStringField(
        PIMItem pimItem,
        int id,
        int index) {
    if (pimItem == null) {
        return null;
    }
    // Get the list for the PIM item
    PIMList pimList = pimItem.getPIMList();
    if(pimList == null) {
       return null; // PIM item doesn't belong to a list
    }
    if (pimList.isSupportedField(id) == false) {
        return null; // field not supported
    }
    String[] values = pimItem.getStringArray(id, index);
    return joinStringArray(values);
}

/**
 * Joins a StringArray returning a single String
 * (from the Sun Java Wireless Toolkit PIMDemo example)
 *
 * @param   stringArray     the String array to join
 * @return                  joined String array as a single String
 */
static private String joinStringArray(String[] stringArray) {
    if (stringArray == null) {
        return null;
    }
    StringBuffer sb = new StringBuffer();
    for (int i = 0; i < stringArray.length; i++) {
        if (stringArray[i] != null && stringArray[i].length() > 0) {
            if (sb.length() > 0) {
                sb.append(", ");
            }
            sb.append(stringArray[i]);
        }
    }
    return sb.toString();
}

/**
 * Generic PIMItem get date (long) field accessor method
 * @event the PIM item to reference
 * @param id the field id to retrieve
 * @param index the value id to retrieve
 */
static public long getDateField(
        PIMItem pimItem,
        int id,
        int index) {
    if (pimItem == null) {
        return -1;
    }
    // Get the list for the PIM item
    PIMList pimList = pimItem.getPIMList();
    if (pimList == null) {
       return -1; // PIM item doesn't belong to a list
    }
    if (pimList.isSupportedField(id) == false) {
        return -1; // field is not supported
    }
    return pimItem.getDate(id, index);
}

/**
 * Generic PIMItem get int field accessor method
 * @event the PIM event item to reference
 * @param id the field id to retrieve
 * @param index the value id to retrieve
 */
static public int getIntField(
        PIMItem pimItem,
        int id,
        int index) {
    if (pimItem == null) {
        return -1; 
    }
    // Get the list for the PIM item
    PIMList pimList = pimItem.getPIMList();
    if (pimList == null) {
       return -1; // PIM item doesn't belong to a list
    }
    if (pimList.isSupportedField(id) == false) {
        return -1; // field not supported
    }
    int value = pimItem.getInt(id, index);
    return value;
}

Event event = ...;
:

// Get the event's UID
String eventUid = getSimpleStringField(event, Event.UID, 0);
if (eventUid == null) {
    // invalid UID...
}

// Get the event's start date/time
long eventStartDate = getDateField(event, Event.START, 0);
if (eventStartDate == -1) {
    // invalid Start Date...
}

// Get the event's summary
String eventSumm = getSimpleStringField(event, Event.SUMMARY, 0);
if (eventSumm == null) {
    // invalid Summary...
}

// Get the event's location
String eventLoc = getSimpleStringField(event, Event.LOCATION, 0);
if (eventLoc == null) {
   // invalid Location...
}

//  Get the event's note (description)
String eventNote = getSimpleStringField(event, Event.NOTE, 0);
if (eventNote == null) {
   // invalid Note...
}

// Get the event's privacy class: public vs. private
int eventClass = getIntField(event, Event.CLASS, 0);
if (eventClass == -1) {
   // invalid Class...
}

// Get the event's alarm reminder delta time
int eventAlarm = getIntField(event, Event.ALARM, 0);
if (eventAlarm == -1) {
   // invalid Alarm...
}

import javax.microedition.pim.*;
:

pim = PIM.getInstance(); // retrieve instance of PIM
:

/**
 * Remove the specified Event
 * @param event the event to remove
 */
static public void removeEvent(Event event) {
    if (event != null) {
        EventList el = (EventList) event.getPIMList();
        try {
            el.removeEvent(event);
        } catch (PIMException pe) {
            // handle PIM exception
        }
    }
}

import javax.microedition.pim.*;
:

pim = PIM.getInstance(); // retrieve instance of PIM
:

// Define the categories
private static final String MOMO_CATEGORY = "MobileMonday";
private static final String MOMO_AUSTIN_CATEGORY = "MobileMonday Austin";
:

// Open the default event list
EventList el = openDefaultEventList(PIM.READ_WRITE);
:

// Add the specified category to the PIM list
try {
    el.addCategory(MOMO_AUSTIN_CATEGORY);
} catch (PIMException pe) {
    // Handle PIM exception
}

// Get all the categories associated with the PIM list
String[] categories = null;
try {
    categories = el.getCategories();
} catch (PIMException pe) {
    // Handle PIM exception
}

// Remove the specified category from the PIM list
try {
    // Specify false for the argument deleteUnassignedItems, 
    // as we don't want to delete items that no longer have any 
    // categories assigned to them as a result of this method
    el.deleteCategory(MOMO_AUSTIN_CATEGORY, false);
} catch (PIMException pe) {
    // Handle PIM exception
}

// Test if the specified category is associated to the PIM list
try {
    if (el.isCategory(MOMO_AUSTIN_CATEGORY)) {
        // The list has MOMO_AUSTIN_CATEGORY category already defined
    }
} catch (PIMException pe) {
    // Handle PIM exception
}

// Get all the items in the PIM list that are part of the 
// specified category
Enumeration items;
try {
    items = el.itemsByCategory(MOMO_AUSTIN_CATEGORY);
} catch (PIMException pe) {
    // Handle PIM exception
}

// Get the maximum number of categories that can 
//  be added to the PIM list
int maxCategories = el.maxCategories();

// Rename the specified PIM list category
try {
    el.renameCategory(
        MOMO_AUSTIN_CATEGORY, // current value
        MOMO_CATEGORY);       // new value
} catch (PIMException pe) {
    // Handle PIM exception
}

/**
 * Get all the PIM items on the specified list.
 * @param   pimList     the PIM List to retrieve items from
 * @return              Enumeration containing the PIM items
 */
static public Enumeration getAllItems(PIMList pimList) {
    Enumeration allItems = null;
    try {
        allItems = pimList.items();
    } catch (PIMException pe) {
        allItems = null;
    }
    return allItems;
}

/**
 * Get all the PIM items on the specified list that matches 
 * all the fields on the specified matching item.
 * @param   pimList     the PIM List to retrieve items from
 * @return              Enumeration containing the matching PIM items
 */
static public Enumeration getMatchingItems(
        PIMList pimList, PIMItem matchingItem) {
    Enumeration matchingItems = null;
    try {
        matchingItems = pimList.items(matchingItem);
    } catch (PIMException pe) {
        matchingItems = null;
    }
    return matchingItems;
}

:

// Open the Event list
EventList el = ...;

// Create an instance of an event item 
Event matchingItem = el.createEvent();

// Create the matching event, to find items that matches a 
// specific location, and item class. For this only assign values 
// to the location and class fields on the matchingItem.
if (el.isSupportedField(Event.LOCATION) == true) {
    matchingItem.addString(Event.LOCATION, 
                           PIMItem.ATTR_NONE, 
                           "6th Street, Austin");
}
if (el.isSupportedField(Event.CLASS) == true) {
    matchingItem.addInt(Event.CLASS, 
                        PIMItem.ATTR_NONE, 
                        Event.CLASS_PUBLIC);
}

// Now get matching items
Enumeration matchingItems = getMatchingItems(el, matchingItem);

// For illustration purposes, walk through the returned (matched) items
int counter = 0;
while (matchingItems.hasMoreElements()) {
	Event event = (Event) matchingItems.nextElement();
	dumpPimEventItem(event); // dump the event item
	counter++;
}      

/**
 * Get all the PIM items on the specified list that match 
 *  on any of its fields the specified String value.
 * @param pimList the PIM List to retrieve items from
 * @return Enumeration containing the matching PIM items
 */
static public Enumeration getMatchingItemsByStringValue(
        PIMList pimList, String stringValue) {
    Enumeration matchingItems = null;
    try {
        matchingItems = pimList.items(stringValue);
    } catch (PIMException pe) {
        matchingItems = null;
    }
    return matchingItems;
}

:

// Open the Event list
EventList el = ...;

// Create an instance of an event item 
String matchingValue = "MobileMonday Austin";

// Get matching items
Enumeration matchingItems = getMatchingItems(el, matchingValue);

// Walk through the returned/matching items
int counter = 0;
while (matchingItems.hasMoreElements()) {
	Event event = (Event) matchingItems.nextElement();
	dumpPimEventItem(event); // dump the event item
	counter++;
}      

:

// Define the start of vacation date/time range limit
Calendar calStart = Calendar.getInstance();
calStart.set(Calendar.MONTH, Calendar.DECEMBER);
calStart.set(Calendar.DAY_OF_MONTH, 18);
calStart.set(Calendar.YEAR, 2006);
calStart.set(Calendar.HOUR_OF_DAY, 8);
calStart.set(Calendar.MINUTE, 00);
calStart.set(Calendar.SECOND, 00);
calStart.set(Calendar.MILLISECOND, 0);
Date startDate = calStart.getTime();

// Define the end of vacation date/time range limit
Calendar calEnd = Calendar.getInstance();
calEnd.set(Calendar.MONTH, Calendar.DECEMBER);
calEnd.set(Calendar.DAY_OF_MONTH, 24);
calEnd.set(Calendar.YEAR, 2006);
calEnd.set(Calendar.HOUR_OF_DAY, 23);
calEnd.set(Calendar.MINUTE, 00);
calEnd.set(Calendar.SECOND, 00);
calEnd.set(Calendar.MILLISECOND, 0);
Date endDate = calEnd.getTime();

// Now that we have defined the vacation date range above,  
// identify/search for items that conflict with the vacation (i.e. that 
// fall within the specified date range)
Enumeration e = null;
try {
    e = eventList.items(
            EventList.STARTING, // STARTING, ENDING, or  OCCURRING.
            startDate.getTime(),
            endDate.getTime(),
            true); // only return the initial event if recurring
} catch (PIMException pe) {
    // handle PIM exception
} finally {
    return e;
}

:

// Define the start of vacation date/time range limit
Calendar calStart = Calendar.getInstance();
Date startDate = calStart.getTime();
:

// Define the end of vacation date/time range limit
Calendar calEnd = Calendar.getInstance();
Date endDate = calEnd.getTime();
:

// Identify/search for items to be completed that conflict with the 
// vacation (i.e. that fall within the specified date range)
Enumeration e = null;
try {
    e = todoList.items(
            ToDo.COMPLETION_DATE, // ToDo.DUE or ToDo.COMPLETION_DATE
            startDate.getTime(),
            endDate.getTime());
} catch (PIMException pe) {
    // handle PIM exception
} finally {
    return e;
}

:

// Set Start Date/Time
Calendar calStart = Calendar.getInstance();
Date startDate = calStart.getTime();
:

// Set End Date/Time
Calendar calEnd = Calendar.getInstance();
Date endDate = calEnd.getTime();
:

EventList el = ...;
Event event = el.createEvent(); 
PimEventUtils.addEventInfo(
        event,
        startDate.getTime(),    // START
        endDate.getTime(),      // END
        "This is the summary",  // SUMMARY
        "This is the location", // LOCATION
        "This is the note",     // NOTE
        Event.CLASS_PUBLIC,     // CLASS
        0);                     // ALARM

// Define the until date repeat rule
Calendar utilDate = Calendar.getInstance();
utilDate.set(Calendar.MONTH, Calendar.NOVEMBER);
utilDate.set(Calendar.DAY_OF_MONTH, 15);
utilDate.set(Calendar.YEAR, 2007);
utilDate.set(Calendar.AM_PM, Calendar.PM);
utilDate.set(Calendar.HOUR_OF_DAY, 23);
utilDate.set(Calendar.MINUTE, 59);

// Set the recurring event to occur weekly
RepeatRule rr = new RepeatRule();
rr.setInt(RepeatRule.FREQUENCY, RepeatRule.WEEKLY);

// Set the repeat until rule, to end on the specified date/time
rr.setDate(RepeatRule.END, utilDate.getTime().getTime());
event.setRepeat(rr);

try {
    event.commit();
} catch (PIMException pe) {
    // handle PIM exception
}
try {
    el.close();
} catch (PIMException pe) {
    // handle PIM exception
}

/**
 * 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, 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;
}

:

EventList el = ...;
:

// Test if repeat rule END is supported
boolean isSupported = isRepeatRuleFieldSupported(
    el,               // list to test
    RepeatRule.DAILY, // frequency for repeat rule to test
    RepeatRule.END);  // repeat rule to test

if (isSupported) == true) {
    // RepeatRule.END is supported!
}

: