MailNews:Address Book Interface Redesign

With the interest of someone working on a sql backend for Address Book, various discussions have been held on irc regarding redesign of some of the interfaces (and hence classes in the address book).

The aim of the redesign would be to:

• make it easier to add new address book types
• support all the existing functionality we have already where possible
• separate out the mailing list implementation from nsIAbCard and nsIAbDirectory
• support as much functionality at implementation independent levels where possible
• make it easier for groups/mailing lists/etc to be defined and controlled
• could we make the structure to support recursive groups/mailing lists/etc?

This page is still WIP for even the initial design thoughts. Please use the Talk Page for comments

Current Structure

On Trunk as at 15th January 2008:

• nsIAbManager
  • just about handles creation of new mork based address books. Sort-of handles LDAP books
  • Some utility functions
  • won't handle enable/removal of OSX or Outlook books.
• nsIAbCard
  • Lots of attributes for each of the items on a card, can also represent mailing lists, but doesn't contain the list contains.
• nsIAbDirectory
  • Represents an address book, is mostly implementation-independent but not quite.
  • Can also represent a mailing list, in which case most of the other properties are useless.

Thoughts that need clarification/decisions

• Do we allow different Address Book types at different levels in a recursive structure?
  • Could be complicated with outlook books (one backend-book = multiple outlook books)

nsIAbManager

• Handles addition/deletion of new address books (modifications of properties handled directly on nsIAbDirectory).

interface nsIAbManager : nsISupports
{
  /**
   * Creates a new directory and registers it with the manager.
   *
   * @param  aType         The type of the directory, e.g. "sql", "ldap", etc.
   * @return               An object of the specific directory type whose
   *                       attributes can then be modified/set.
   */
  nsIAbDirectory newDirectory(in AUTF8String aType);

  /**
   * Deletes a directory and unregisters it.
   *
   * @param  aDirectory    The directory to delete.
   */
  void deleteDirectory(in nsIAbDirectory aDirectory);
...
}

Notes/Thoughts:

• Why does createCalendar have URI, why do they feel its necessary to set the URI in calCalendarManager?
• Will the delete directory work - check what nsIAbDirectory implements.

Proposed Structure For the Main Interfaces

• Proposed Interface Inheritance Structure:

            nsIAbItem
                |
    |-------------------------|
nsIAbCard               nsIAbCollection
                              |
                    |--------------------|
                nsIAbGroup         nsIAbDirectory

nsIAbItem

• Base address book item.
• Contains functions/attributes generic to all items.
• All items are derived from this one.

interface nsIAbItem : nsISupports
{
  /**
   * Unique identifier for this item.
   *
   * @ exception NS_ERROR_ILLEGAL_VALUE  The supplied uuid is invalid.
   */
  attribute AUTF8String uuid;
...
}

Notes/Thoughts:

• Need a format (or at least examples) for the uuid.
• Do we need a type attribute (e.g. LDAP/SQL etc) or is this better on nsIAbCollection?

nsIAbCard

• Represents a card.
• No link to database. Modified card must be presented to directory in order for the database to be updated (this means we can easily enforce reducing the amount of database operations).
• Generic attribute get/set.

interface nsIAbCard : nsIAbItem
{
  /**
   * A list of all the properties that this card has as an enumerator, whose
   * members are all nsIProperty objects.
   */
  readonly attribute nsISimpleEnumerator properties;
 
  /**
   * @{
   * Returns a property for the given name.
   *
   * @exception NS_ERROR_FAILURE if the named property does not exist.
   */
  nsIVariant getProperty(in AString name);
  AString getPropertyAsAString(in AString name);
  AUTF8String getPropertyAsAUTF8String(in AString name);
  PRUint32 getPropertyAsUint32(in AString name);
  boolean getPropertyAsBool(in AString name);
  /** @} */

  /**
   * @{
   * Assigns the given to value to the property of the given name.
   *
   * Should the property exist, its value will be overwritten. An
   * implementation may impose additional semantic constraints for certain
   * properties.
   *
   * @exception NS_ERROR_ILLEGAL_VAlUE if the value violates a constraint.
   * @exception NS_ERROR_FAILURE if the value is required.
   */
  void setProperty(in AString name, in nsIVariant value);
  void setPropertyAsAString(in AString name, in AString value);
  void setPropertyAsAUTF8String(in AString name, in AUTF8String value);
  void setPropertyAsUint32(in AString name, in PRUint32 value);
  void setPropertyAsBool(in AString name, in boolean value);
  /** @} */

  /**
   * Deletes the property with the given name.
   *
   * Some properties may not be deleted.
   *
   * @exception NS_ERROR_FAILURE if the value is required by an implementation.
   */
  void deleteProperty(in AString name);
}

Notes/Thoughts:

• Most internal properties stored in a property bag, some "important" properties stored local for fast-access.
• If directories save their own attribute modifications, but cards don't, is
• this acceptable?

nsIAbCollection

• Represents a collection of nsIAbItem.
  • Currently unclear as to if we'll allow nsIAbDirectory items to be included in anything other than the top-level).
• Contains methods for searching its nsIAbItem collection.

interface nsIAbCollection : nsIAbItem
{
  /**
   * Returns an array of the child items.
   */
  readonly attribute nsIArray childItems;

  /**
   * Returns an enumerator that contains all the child items that this
   * collection contains.
   */
  readonly attribute nsISimpleEnumerator childItemsEnumerator;

  /**
   * Returns a new search instance, set up to be able to search the current
   * collection.
   *
   * @exception NS_ERROR_NOT_IMPLEMENTED  Search is not available for this
   *                                      collection.
   */
  readonly attribute nsIAbDirectorySearch searchInstance;

  /**
   * Adds an item to the collection.
   *
   * @param     aItem                     The item to add to the collection.
   * @return                              The item added. This may be different
   *                                      to aItem for implementation-specific
   *                                      items.
   * @exception NS_ERROR_????             The item could not be added to this
   *                                      collection.
   */
  nsIAbItem addItem(in nsIAbItem aItem);

  /**
   * Adds multiple items to the collection.
   *
   * @param     aItems                    The items to add to the collection,
   *                                      these may be exchanged for new items
   *                                      to allow them to be replaced by
   *                                      implementation specific items.
   */
  void addItems(inout nsIMutableArray aItems);

...
}

Notes/Thoughts:

• Does this need any properties?

nsIAbGroup

• Interface for functions/attributes slightly more specific to groups of items.
• Not sure what these are yet.
• A Group could be a Mailing List, Saved Search Folder, Collection of Tags etc.

interface nsIAbGroup : nsIAbCollection
{
...
}

Notes/Thoughts:

nsIAbDirectory

• Interface for functions/attributes slightly more specific to directories.
• Not sure what these are yet.

interface nsIAbDirectory : nsICollection
{
...
}

Notes/Thoughts:

nsIAbDirectorySearch

• Provides an interface to be able to search collections.
• Implementations may be specific to directory types.

interface nsIAbDirectorySearch : nsISupports
{
  /**
   * Starts the search.
   *
   * @param  aSearchParams  The parameters to use for the search.
   */
  void startSearch(in nsIAbBooleanExpression aSearchParams);

  /**
   * Stops/interrupts the search.
   */
  void stopSearch();
...
}

Notes/Thoughts: