Bug 1077097 - Update Bookmarks.jsm to be coherent with History.jsm r=mano
authorMarco Bonardo <mbonardo@mozilla.com>
Tue, 07 Oct 2014 16:30:34 +0200
changeset 209398 116b905fd60500e1a7bb829651ac02e460009e60
parent 209397 88664bb1a031cd2667526f75227855c003630bd9
child 209399 d5ce88ef74a5d5aab53e3d47dfb719cb34e95dc8
push id1
push userroot
push dateMon, 20 Oct 2014 17:29:22 +0000
reviewersmano
bugs1077097
milestone35.0a1
Bug 1077097 - Update Bookmarks.jsm to be coherent with History.jsm r=mano
toolkit/components/places/Bookmarks.jsm
--- a/toolkit/components/places/Bookmarks.jsm
+++ b/toolkit/components/places/Bookmarks.jsm
@@ -2,65 +2,67 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
  * You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 "use strict";
 
 /**
  * This module provides an asynchronous API for managing bookmarks.
  *
- * Bookmarks are organized in a tree structure, and can be bookmarked URIs,
- * folders or separators.  Multiple bookmarks for the same URI are allowed.
+ * Bookmarks are organized in a tree structure, and can be bookmarked URLs,
+ * folders or separators.  Multiple bookmarks for the same URL are allowed.
  *
  * Note that if you are handling bookmarks operations in the UI, you should
  * not use this API directly, but rather use PlacesTransactions.jsm, so that
  * any operation is undo/redo-able.
  *
  * Each bookmarked item is represented by an object having the following
  * properties:
  *
  *  - guid (string)
  *      The globally unique identifier of the item.
  *  - parentGuid (string)
  *      The globally unique identifier of the folder containing the item.
  *      This will be an empty string for the Places root folder.
  *  - index (number)
  *      The 0-based position of the item in the parent folder.
- *  - dateAdded (number, microseconds from the epoch)
- *      The time at which the item was added.  This is a PRTime (microseconds).
- *  - lastModified (number, microseconds from the epoch)
- *      The time at which the item was last modified. This is a PRTime (microseconds).
+ *  - dateAdded (Date)
+ *      The time at which the item was added.
+ *  - lastModified (Date)
+ *      The time at which the item was last modified.
  *  - type (number)
  *      The item's type, either TYPE_BOOKMARK, TYPE_FOLDER or TYPE_SEPARATOR.
  *
  *  The following properties are only valid for bookmarks or folders.
  *
  *  - title (string)
  *      The item's title, if any.  Empty titles and null titles are considered
  *      the same and the property is unset on retrieval in such a case.
+ *      Title cannot be longer than TITLE_LENGTH_MAX, or it will be truncated.
  *
  *  The following properties are only valid for bookmarks:
  *
- *  - uri (nsIURI)
- *      The item's URI.
+ *  - url (URL, href or nsIURI)
+ *      The item's URL.  Note that while input objects can contains either
+ *      an URL object, an href string, or an nsIURI, output objects will always
+ *      contain an URL object.
+ *      URL cannot be longer than URL_LENGTH_MAX, methods will throw if a
+ *      longer value is provided
  *  - keyword (string)
  *      The associated keyword, if any.
  *
  * Each successful operation notifies through the nsINavBookmarksObserver
  * interface.  To listen to such notifications you must register using
  * nsINavBookmarksService addObserver and removeObserver methods.
  * Note that bookmark addition or order changes won't notify onItemMoved for
  * items that have their indexes changed.
  * Similarly, lastModified changes not done explicitly (like changing another
  * property) won't fire an onItemChanged notification for the lastModified
  * property.
  * @see nsINavBookmarkObserver
- *
- * @note livemarks are implemented as empty folders.
- *       @see mozIAsyncLivemarks.idl
  */
 
 this.EXPORTED_SYMBOLS = [ "Bookmarks" ];
 
 const { classes: Cc, interfaces: Ci, results: Cr, utils: Cu } = Components;
 
 Cu.import("resource://gre/modules/XPCOMUtils.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Services",
@@ -69,175 +71,189 @@ XPCOMUtils.defineLazyModuleGetter(this, 
                                   "resource://gre/modules/NetUtil.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Promise",
                                   "resource://gre/modules/Promise.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Task",
                                   "resource://gre/modules/Task.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Sqlite",
                                   "resource://gre/modules/Sqlite.jsm");
 
-const URI_LENGTH_MAX = 65536;
+const URL_LENGTH_MAX = 65536;
 const TITLE_LENGTH_MAX = 4096;
 
 let Bookmarks = Object.freeze({
   /**
    * Item's type constants.
    * These should stay consistent with nsINavBookmarksService.idl
    */
   TYPE_BOOKMARK: 1,
   TYPE_FOLDER: 2,
   TYPE_SEPARATOR: 3,
 
   /**
+   * Default index used to append a bookmarked item at the end of a container. 
+   * This should stay consistent with nsINavBookmarksService.idl
+   */
+  DEFAULT_INDEX: -1,
+
+  /**
    * Creates or updates a bookmarked item.
    *
    * If the given guid is found the corresponding item is updated, otherwise,
    * if no guid is provided, a bookmark is created and a new guid is assigned
    * to it.
    *
    * In the creation case, a minimum set of properties must be provided:
    *  - type
    *  - parentGuid
-   *  - URI, only for bookmarks
+   *  - url, only for bookmarks
    * If an index is not specified, it defaults to appending.
    * It's also possible to pass a non-existent guid to force creation of an
    * item with the given guid, but unless you have a very sound reason, such as
    * an undo manager implementation or synchronization, you should not do that.
    *
    * In the update case, you should only set the properties which should be
    * changed, undefined properties won't be taken into account for the update.
    * Moreover, the item's type and the guid are ignored, since they are
    * immutable after creation.  Note that if the passed in values are not
    * coherent with the known values, this rejects.
    * Passing null or an empty string as keyword clears any keyword
    * associated with this bookmark.
    *
    * Note that any known property that doesn't apply to the specific item type
-   * causes rejection.
+   * throws an exception.
    *
    * @param info
    *        object representing a bookmarked item, as defined above.
+   * @param onResult [optional]
+   *        Callback invoked for each created or updated bookmark.  It gets
+   *        the bookmark object as argument.
    *
    * @return {Promise} resolved when the update is complete.
-   * @resolves to the input object, updated with relevant information.
-   * @rejects JavaScript exception.
-   *
-   * @note title is truncated to TITLE_LENGTH_MAX and URI is rejected if
-   *       greater than URI_LENGTH_MAX.
+   * @resolves to a boolean indicating whether any new bookmark has been created.
+   * @rejects JavaScript exception if it's not possible to update or create the
+   *          requested bookmark.
+   * @throws if input is invalid.
    */
   // XXX WIP XXX Will replace functionality from these methods:
   // long long insertBookmark(in long long aParentId, in nsIURI aURI, in long aIndex, in AUTF8String aTitle, [optional] in ACString aGUID);
   // long long createFolder(in long long aParentFolder, in AUTF8String name, in long index, [optional] in ACString aGUID);
   // void moveItem(in long long aItemId, in long long aNewParentId, in long aIndex);
   // long long insertSeparator(in long long aParentId, in long aIndex, [optional] in ACString aGUID);
   // void setItemTitle(in long long aItemId, in AUTF8String aTitle);
   // void setItemDateAdded(in long long aItemId, in PRTime aDateAdded);
   // void setItemLastModified(in long long aItemId, in PRTime aLastModified);
   // void changeBookmarkURI(in long long aItemId, in nsIURI aNewURI);
   // void setKeywordForBookmark(in long long aItemId, in AString aKeyword);
-  update: Task.async(function* (info) {
+  update: function (info, onResult=null) {
     throw new Error("Not yet implemented");
-  }),
+  },
 
   /**
    * Removes a bookmarked item.
    *
    * Input can either be a guid or an object with one of the following
    * properties set:
    *  - guid: if set, only the corresponding item is removed.
    *  - parentGuid: if it's set and is a folder, any children of that folder is
    *                removed, but not the folder itself.
-   *  - URI: if set, any bookmark for that URI is removed.
-   * If multiple of these properties are set, the method rejects.
+   *  - url: if set, any bookmark for that URL is removed.
+   * If multiple of these properties are set, the method throws.
    *
    * Any other property is ignored, known properties may be overwritten.
    *
    * @param guidOrInfo
    *        The globally unique identifier of the item to remove, or an
    *        object representing it, as defined above.
+   * @param onResult [optional]
+   *        Callback invoked for each removed bookmark.  It gets the bookmark
+   *        object as argument.
    *
    * @return {Promise} resolved when the removal is complete.
-   * @resolves to the removed object or an array of them.
-   * @rejects JavaScript exception.
+   * @resolves to a boolean indicating whether any object has been removed.
+   * @rejects JavaScript exception if the provided guid or parentGuid don't
+   *          match any existing bookmark.
+   * @throws if input is invalid.
    */
   // XXX WIP XXX Will replace functionality from these methods:
   // removeItem(in long long aItemId);
   // removeFolderChildren(in long long aItemId);
-  remove: Task.async(function* (guidOrInfo) {
+  remove: function (guidOrInfo, onResult=null) {
     throw new Error("Not yet implemented");
-  }),
+  },
 
   /**
    * Fetches information about a bookmarked item.
    *
    * Input can be either a guid or an object with one, and only one, of these
    * filtering properties set:
    *  - guid
    *      retrieves the item with the specified guid
    *  - parentGuid and index
    *      retrieves the item by its position
-   *  - URI
-   *      retrieves all items having the given URI.
+   *  - url
+   *      retrieves an array of items having the given URL.
    *  - keyword
-   *      retrieves all items having the given keyword.
+   *      retrieves an array of items having the given keyword.
    *
    * Any other property is ignored.  Known properties may be overwritten.
    *
    * @param guidOrInfo
    *        The globally unique identifier of the item to fetch, or an
    *        object representing it, as defined above.
    *
    * @return {Promise} resolved when the fetch is complete.
    * @resolves to an object representing the found item, as described above, or
    *           an array of such objects.  if no item is found, the returned
    *           promise is resolved to null.
    * @rejects JavaScript exception.
+   * @throws if input is invalid.
    */
   // XXX WIP XXX Will replace functionality from these methods:
   // long long getIdForItemAt(in long long aParentId, in long aIndex);
   // AUTF8String getItemTitle(in long long aItemId);
   // PRTime getItemDateAdded(in long long aItemId);
   // PRTime getItemLastModified(in long long aItemId);
   // nsIURI getBookmarkURI(in long long aItemId);
   // long getItemIndex(in long long aItemId);
   // unsigned short getItemType(in long long aItemId);
   // boolean isBookmarked(in nsIURI aURI);
   // long long getFolderIdForItem(in long long aItemId);
   // void getBookmarkIdsForURI(in nsIURI aURI, [optional] out unsigned long count, [array, retval, size_is(count)] out long long bookmarks);
   // AString getKeywordForURI(in nsIURI aURI);
   // AString getKeywordForBookmark(in long long aItemId);
   // nsIURI getURIForKeyword(in AString keyword);
-  fetch: Task.async(function* (guidOrInfo) {
+  fetch: function (guidOrInfo) {
     throw new Error("Not yet implemented");
-  }),
+  },
 
   /**
    * Retrieves an object representation of a bookmarked item, along with all of
    * its descendants, if any.
    *
-   * Each node in the tree is an object that extends
-   * the item representation described above with some additional properties:
+   * Each node in the tree is an object that extends the item representation
+   * described above with some additional properties:
    *
    *  - [deprecated] id (number)
    *      the item's id.  Defined only if aOptions.includeItemIds is set.
    *  - annos (array)
    *      the item's annotations.  This is not set if there are no annotations
    *      set for the item.
    *
    * The root object of the tree also has the following properties set:
    *  - itemsCount (number, not enumerable)
    *      the number of items, including the root item itself, which are
    *      represented in the resolved object.
    *
-   * Bookmarked URIs may also have the following properties:
+   * Bookmarked URLs may also have the following properties:
    *  - tags (string)
    *      csv string of the bookmark's tags, if any.
    *  - charset (string)
    *      the last known charset of the bookmark, if any.
-   *  - iconuri (string)
+   *  - iconurl (URL)
    *      the bookmark's favicon URL, if any.
    *
    * Folders may also have the following properties:
    *  - children (array)
    *      the folder's children information, each of them having the same set of
    *      properties as above.
    *
    * @param [optional] guid
@@ -261,35 +277,37 @@ let Bookmarks = Object.freeze({
    *           Use it if you must. It'll be removed once the switch to guids is
    *           complete.
    *
    * @return {Promise} resolved when the fetch is complete.
    * @resolves to an object that represents either a single item or a
    *           bookmarks tree.  if guid points to a non-existent item, the
    *           returned promise is resolved to null.
    * @rejects JavaScript exception.
+   * @throws if input is invalid.
    */
   // XXX WIP XXX: will replace functionality for these methods:
   // PlacesUtils.promiseBookmarksTree()
-  fetchTree: Task.async(function* (guid = "", options = {}) {
+  fetchTree: function (guid = "", options = {}) {
     throw new Error("Not yet implemented");
-  }),
+  },
 
   /**
    * Reorders contents of a folder based on a provided array of GUIDs.
    *
    * @param parentGuid
    *        The globally unique identifier of the folder whose contents should
    *        be reordered.
    * @param orderedChildrenGuids
    *        Ordered array of the children's GUIDs.  If this list contains
    *        non-existing entries they will be ignored.  If the list is
    *        incomplete, missing entries will be appended.
    *
    * @return {Promise} resolved when reordering is complete.
    * @rejects JavaScript exception.
+   * @throws if input is invalid.
    */
   // XXX WIP XXX Will replace functionality from these methods:
   // void setItemIndex(in long long aItemId, in long aNewIndex);
-  reorder: Task.async(function* (parentGuid, orderedChildrenGuids) {
+  reorder: function (parentGuid, orderedChildrenGuids) {
     throw new Error("Not yet implemented");
-  })
+  }
 });