General PIM API Design

The basic idea of the API is to store entries such as contacts, events, and to-do elements in an appropriate database. In order to achieve this, the PIM API contains an interface PIMList providing methods to add, delete, and enumerate all the entries contained in the list. The concrete implementations of PIMList contained in the PIM API are ContactLists to store contacts, EventLists to store events, and ToDoLists to store to-do items. The PIM class provides static methods such as openContactList() to access the different list types.

PIMLists contain objects implementing the PIMElement interface. PIMElement encapsulates the common properties of the different PIM elements such as Contacts, Events, and ToDos. The interface provides methods for common functionality such as category access and vFormat import and export, as well as access to the fields of an entry. Access to some specialized fields is provided by the derived interfaces Contact, Event, and ToDo. For illegal PIM operations, a PIMException will be thrown. In the next sections, you will learn the details of the specialized address book, event, and to-do functionality.

In contrast to vCard, vCalendar, and the JavaPhone API, the PDAP PIM API does not support multiple fields with the same name and type combination. Although this restriction causes a slight loss of flexibility, it makes the API much less complex than the JavaPhone API. Fields with a single ID and multiple types are described in more detail in the following section.