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)

Revised nsIAbManager Interface

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

interface nsIAbManager : nsISupports
{
  /**
   * Returns an enumerator containing all the top-level directories
   * (non-recursive)
   */
  readonly attribute nsISimpleEnumerator directories;

  /**
   * Returns a directory object that is specific to the uuid given.
   *
   * @param  aUuid         The uuid of the directory to get.
   * @return               An object representing the directory of the given
   *                       uuid.
   * @exception NS_ERROR_FAILURE
   *                       The aUuid is invalid.
   */
  nsIAbDirectory getDirectory(in AUTF8String aUuid);
   
  /**
   * Creates a new directory of the specified type but does not register 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 createDirectory(in AUTF8String aType);

  /**
   * Registers a directory with the manager.
   *
   * @param  aDirectory    The directory to register.
   */
  void registerDirectory(in nsIAbDirectory aDirectory);

  /**
   * 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.
• Should we provide a nsISimpleEnumerator version of getDirectories, or is that overkill?
• nsIAbDirFactory and its implementations won't be required.
• Either here or somewhere similar I'd like to be able to register listeners to be notified of directory creation/registration/deleting.

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;

  /**
   * These constants reflect the possible values of the
   * mail.addr_book.lastnamefirst preference. They are used in the generateName
   * function below
   */
  const unsigned long kGenerateDisplayName = 0;
  const unsigned long kGenerateLastFirstOrder = 1;
  const unsigned long kGenerateFirstLastOrder = 2;

  /** 
   * Generate a name from the item for display purposes.
   *
   * If this item is an nsIAbCard, then it will use the aGenerateFormat option
   * to determine the string to return.
   * If this item is not an nsIAbCard, then the aGenerateFormat option may be
   * ignored, and the displayName of the item returned.
   *
   * @param  aGenerateFormat The format to generate as per the kGenerate*
   *                         constants above.
   * @param  aBundle         An optional parameter that is a pointer to a string
   *                         bundle that holds:
   *           chrome://messenger/locale/addressbook/addressBook.properties
   *                         If this bundle is not supplied, then the function
   *                         will obtain the bundle itself. If cached by the
   *                         caller and supplied to this function, then
   *                         performance will be improved over many calls.
   * @return                 A string containing the generated name.
   */
  AString generateName(in long aGenerateFormat,
                       [optional] in nsIStringBundle aBundle);

...
}

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?
• Some sort of displayName attribute? -- Jcranmer 12:44, 17 February 2008 (PST)
  • Fixed --Standard8 10:16, 16 March 2008 (PDT)

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.
• Note: generateBase64EncodedXML, generateXMLPrintData and generateEscapedVCard have been replaced by translateTo()

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);

  /**
   * Translates a card into a specific format
   *
   * @param  aType          The type of item to translate the card into.
   * @return                A string containing the translated card.
   * @exception ????
   */
  AUTF8String translateTo(AUTF8String aType);

  /**
   * Translates a card from the specified format
   */
  void translateFrom(AUTF8String aType, AUTF8String aData);
  
  /** 
   * Generate a phonetic name from the card, using the firstName and lastName
   * values.
   *
   * @param  aLastNameFirst  Set to True to put the last name before the first.
   * @return                 A string containing the generated phonetic name.
   */
  AString generatePhoneticName(in boolean aLastNameFirst);

  /**
   * Generate a formatted email address from the card, that can be used for
   * sending emails.
   *
   * @param  aExpandList     If this card is a list, and this parameter is set
   *                         to true, then the list will be expanded to include
   *                         the emails of the cards within the list.
   * @param  aGroupMailLists If this card (or the items within this card) is a
   *                         list, and this is set to true, then the list will
   *                         be expanded in the RFC 2822 group format
   *                         "displayname : email1 ; email2 ; etc".
   * @param  aHeaderParser   An optional parameter pointing to the
   *                         nsIMsgHeaderParser service. If this is not supplied
   *                         the function will obtain the service itself. If
   *                         cached by the called and supplied to this function,
   *                         then performance will be improved over many calls.
   * @return                 A string containing a comma-separated list of
   *                         formatted addresses.
   */
  AString generateFormattedEmail(in boolean aExpandList,
                                 in boolean aAsGroupMailLists,
                                 [optional] in nsIMsgHeaderParser aHeaderParser);

...
}

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?
• move generatePhoneticName up a level?

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
{
  /**
   * Opens the properties dialog for this collection.
   */
  void openPropertiesDialog();

  /**
   * Returns true if this collection is read-only.
   */
  readonly attribute boolean readOnly;

  /**
   * Returns true if the collection requires specific protocol access over a
   * network connection.
   */
  readonly attribute boolean isRemote;

  /**
   * Returns true if the collection is remote and is accessed over a secure
   * protocol (as in LDAP over SSL).
   */
  readonly attribute boolean isSecure;

  /**
   * Returns an array of the child items.
   */
  void getChildItems(out PRUint32 aCount,
                     [array, size_is(count), retval] out nsIAbItem aChildItems);

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

  /** 
   * Returns the first nsIAbItem that matches the specified property. This will
   * only return the first item found, unlike searching via the searchInstance.
   *
   * @param  aProperty      The property on the item to look up.
   * @param  aValue         The value to which to match on the property.
   * @param  aCaseSensitive Set to true for a case sensitive match.
   * @return                The card if it is found.
   * @exceptions NS_ERROR_NOT_FOUND
   *                        No matching cards have been found.
   */
  nsIAbItem cardForProperty(in ACString aProperty, in AString aValue,
                            in boolean aCaseSensitive);

  /**
   * 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?
  • There are generic pref setters/getters that are wanted. nickName and description may be useful as well, although the former may be satisfied by a displayName on nsIAbItem and the latter on nsIAbGroup instead. -- Jcranmer 12:44, 17 February 2008 (PST)
• Do we need an enumerator version of getChildItems?
• How do we open property dialogs for new nsIAbCollections not created yet?
  • Create an instance via nsIAbManager, then call the function - I've still got to change the manager for this --Standard8 07:05, 25 January 2008 (PST)
• lastModifiedDate?
• What about email case-sensitivity?
• Functions to delete items and modify cards (generic items?) are needed. Maybe copying as well. -- Jcranmer 12:44, 17 February 2008 (PST)
• Again, I'd like an addListener() method of some kind to be notified when cards are added/changed.

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: