Annotations: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
Line 87: Line 87:
     void removePageAnnotations(in nsIURI aURI);
     void removePageAnnotations(in nsIURI aURI);


Issues: do we want to namespace annotation names?
    /**
    * Get the values of several annotations with arbitrary URI/name pairs.
    * There is some latency associated with each annotation query, so it is
    * a good idea to use this function if it is possible for you to batch
    * your requests together.
    *
    * This will return an array with the same number of values you requested.
    * If the requested URI/name pair does not exist, the corresponding result
    * element will be NULL.
    *
    * @param aURIList The list of URIs
    */
    void getMultipleAnnotations([array, size_is(aCount)] in nsIURI aURIList,
      [array, size_is(aCount)] in wstring aNameList, in unsigned long aCount,
      out unsigned long aResultCount,
      [retval, array, size_is(aResultCount)] out wstring aResultList);
 
Issues: do we want to namespace annotation names? Probably we should just say that people should always namespace their names, but do it manually with the names they pick for their annotations. For example "history:thumbnail" or "my_extension:annoying_data".
 
Do we want to support more advanced queries? Examples: Give me all pages with annotation X. Give me all pages where annotation X > Y, etc.
Do we want to support more advanced queries? Examples: Give me all pages with annotation X. Give me all pages where annotation X > Y, etc.



Revision as of 20:23, 3 October 2005

Introduction

Annotations are provided by a browser service that can associate arbitrary information with URLs. The goal is to use them for both history and bookmarks.

Possible uses:

  • Fav icon
  • Page thumbnail
  • Notes
  • Persistent storage for Javascript on the page

Internal design

The design consists of two tables. The first maps URLs to internal IDs.

The second stores all annotations:

  • URL ID
  • Annotation name
  • Value
  • Expiration information
  • Flags (perhaps combined with expiration information)

Expiration

Because some annotations can be large, and the number of pages can also become very large, some sort of annotation expiration scheme is required. Annotations beyond the expiration date will be deleted. The time frame must be variable because some annotations may be large and should expire faster, while others may be small and have minimal overhead for keeping them around. The option of never expiring will also be provided.

This time frame may be measured from annotation creation, but it could potentially be more valuable to measure from from last page access time: "this annotation expires after one month of page disuse".

Flags

Flags could indicate whether an annotation is user-entered (e.g. notes), automatic/service-entered (e.g. favicons, last visit date, etc.), or web page entered (as with IE's userData storage, this would need more aggressive limits). It could also store whether that annotation should be synced remotely or not, and possibly other bits.

Security

If scripts on web pages are allowed to store data, they should only be able to see data that they themselves have written, and not user entered data or service entered data (favicons, etc.). Limiting access to pages on the same path allows some flexibility with different pages from the same service, and should provide minimal opportunity for data leakage.

Quota

Web pages should be restricted in the amount of data that they are allowed to store. We probably want to limit the amount of data per host and possibly also at a finer grained level like pages (as with IE) or paths.

Question: What if a web page wants more storage? Some web services could legitimately need more storage, and provide enough value to the user that they don't care. Should there be a way for the user to specify a web page can add more storage? Here's one possibility: if the page tries to store too much data the write fails and the security bar announces what happened and gives the user the option to increase storage for this page. This would require web pages check for the quota condition, potentially notify the user, and redo the operation if they think it's been fixed.

External interface

Preliminary IDL:

   /**
    * Sets an annotation, overwriting any previous annotation with the same
    * URL/name
    */
   void setAnnotation(in nsIURI aURI, in wstring aName, in nsIVariant aValue,
                      in long aFlags, in long aExpiration);
   /**
    * Retrieves the value of an annotation
    */
   nsIVariant getAnnotation(in nsIURI aURI, in wstring aName);
   /*
    * Retrieves info about the annotation. SetDate is the time that this
    * annotation was last set.
    */
   void getAnnotationInfo(in nsIURI aURI, in wstring aName,
                          out long long aSetDate, out long aFlags,
                          out long aExpiration);
   /**
    * Get the names of all annotations for this URI.
    */
   nsIArray getAnnotations(in nsIURI aURI);
   /**
    * Test for annotation existance.
    */
   boolean hasAnnotation(in nsIURI aURI, in wstring aName);
   /*
    * Removes a specific annotation
    */
   void removeAnnotation(in nsIURI aURI, in wstring aName);
   /**
    * Removes all annotations for the given page.
    * We may want some other similar functions to get annotations with given
    * flags (once we have flags defined).
    */
   void removePageAnnotations(in nsIURI aURI);
   /**
    * Get the values of several annotations with arbitrary URI/name pairs.
    * There is some latency associated with each annotation query, so it is
    * a good idea to use this function if it is possible for you to batch
    * your requests together.
    *
    * This will return an array with the same number of values you requested.
    * If the requested URI/name pair does not exist, the corresponding result
    * element will be NULL.
    *
    * @param aURIList The list of URIs
    */
   void getMultipleAnnotations([array, size_is(aCount)] in nsIURI aURIList,
     [array, size_is(aCount)] in wstring aNameList, in unsigned long aCount,
     out unsigned long aResultCount,
     [retval, array, size_is(aResultCount)] out wstring aResultList);

Issues: do we want to namespace annotation names? Probably we should just say that people should always namespace their names, but do it manually with the names they pick for their annotations. For example "history:thumbnail" or "my_extension:annoying_data".

Do we want to support more advanced queries? Examples: Give me all pages with annotation X. Give me all pages where annotation X > Y, etc.

IE's Implementation

IE has persistency for web pages called 'userData': http://216.239.63.104/search?q=cache:msdn.microsoft.com/workshop/author/behaviors/reference/behaviors/userdata.asp&hl=en&lr=&sa=G&strip=1 This information is persisted in the cache along with the web page it was written on. You can also pick other data stores, including favorites, history, and snapsnot (when saved to local machine).

Using IE's userData

In IE, you need to use DHTML behaviors (http://www.w3.org/TR/becss). Behaviors are not currently supported in Mozilla, but there exists an extension wrapping XBL that supports them: http://dean.edwards.name/moz-behaviors/

In CSS you add "behavior:url('#default#userData')" to the CSS for the elements that you want to persist. This overrides the get/setAttribute functions for that element. You can then call element.save(<store name>) to persist the element under the given tag <store name>.

Security

IE places limits on the visibility of tags to other web pages in the same directory and over the same protocol (to avoid https leakage). There are also limits placed on the size of the data, both for a given web page and for a given domain name.

IE allows an optional expiration date of stored elements. Since these attributes are stored in the cache/history/favorites, they probably disappear when the corresponding store is deleted. There doesn't seem to be any forced expiration, but given the relatively short lifespan of the cache, it probably doesn't matter.

Questions

  • How is persistence shared across different pages in the same directory? Are the names just magically accessable to other pages?
  • Are all tags for the saved object stored, or only the ones you setAttribute on?
  • What happens if I set a given attribute from multiple pages with the same name but different values? Is the correct value distributed to all?