Bug 323231 - Expose new XRE Profile APIs to Java embedders. r=jhpedemonte/bsmedberg

Original committer: pedemont%us.ibm.com
Original revision: 1.3
Original date: 2006/06/09 13:40:08

extensions/java/xpcom/interfaces/org/mozilla/xpcom/IGRE.java

@@ -75,6 +75,53 @@ public interface IGRE {
    */
   void termEmbedding() throws XPCOMException;
 
+  /**
+   * Lock a profile directory using platform-specific semantics.
+   *
+   * @param aDirectory  The profile directory to lock.
+   * @param aLockObject An opaque lock object. The directory will remain locked
+   *                    as long as the XPCOM reference is held.
+   */
+  nsISupports lockProfileDirectory(File aDirectory)
+    throws XPCOMException;
+
+  /**
+   * Fire notifications to inform the toolkit about a new profile. This
+   * method should be called after <code>initEmbedding</code> if the 
+   * embedder wishes to run with a profile. 
+   * <p>
+   * Normally the embedder should call <code>lockProfileDirectory</code>
+   * to lock the directory before calling this method.
+   * <p>
+   * NOTE: There are two possibilities for selecting a profile:
+   * <ul>
+   * <li>
+   *    Select the profile before calling <code>initEmbedding</code> 
+   *    The aAppDirProvider object passed to XRE_InitEmbedding 
+   *    should provide the NS_APP_USER_PROFILE_50_DIR key, and 
+   *    may also provide the following keys:
+   *      <ul>
+   *        <li>NS_APP_USER_PROFILE_LOCAL_50_DIR
+   *        <li>NS_APP_PROFILE_DIR_STARTUP
+   *        <li>NS_APP_PROFILE_LOCAL_DIR_STARTUP
+   *      </ul>
+   *    In this scenario <code>notifyProfile</code> should be called
+   *    immediately after <code>initEmbedding</code>. Component 
+   *    registration information will be stored in the profile and
+   *    JS components may be stored in the fastload cache.
+   * </li>
+   * <li>
+   * 	Select a profile some time after calling <code>initEmbedding</code>.
+   *    In this case the embedder must install a directory service 
+   *    provider which provides NS_APP_USER_PROFILE_50_DIR and optionally
+   *    NS_APP_USER_PROFILE_LOCAL_50_DIR. Component registration information
+   *    will be stored in the application directory and JS components will not
+   *    fastload.
+   * </li>
+   * </ul>
+   */
+  void notifyProfile();
+
 }