Bug 709329 - 401 node reassignment. r=rnewman

mobile/android/base/sync/synchronizer/Synchronizer.java

@@ -1,39 +1,6 @@
-/* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
- *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Android Sync Client.
- *
- * The Initial Developer of the Original Code is
- * the Mozilla Foundation.
- * Portions created by the Initial Developer are Copyright (C) 2011
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *   Richard Newman <rnewman@mozilla.com>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
- *
- * ***** END LICENSE BLOCK ***** */
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * 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/. */
 
 package org.mozilla.gecko.sync.synchronizer;
 
@@ -45,20 +12,26 @@ import android.content.Context;
 import android.util.Log;
 
 /**
- * This, sunshine, is where the magic happens.
+ * I perform a sync.
  *
- * I hope for all our sakes that it's bug-free.
+ * Initialize me by calling `load` with a SynchronizerConfiguration.
  *
- * @author rnewman
+ * Start synchronizing by calling `synchronize` with a SynchronizerDelegate. I
+ * provide coarse-grained feedback by calling my delegate's callback methods.
  *
+ * I always call exactly one of my delegate's `onSynchronized` or
+ * `onSynchronizeFailed` callback methods. In addition, I call
+ * `onSynchronizeAborted` before `onSynchronizeFailed` when I encounter a fetch,
+ * store, or session error while synchronizing.
+ *
+ * After synchronizing, call `save` to get back a SynchronizerConfiguration with
+ * updated bundle information.
  */
 public class Synchronizer {
 
   /**
-   * Wrap a SynchronizerDelegate in a SynchronizerSessionDelegate.
-   * Also handle communication of bundled data.
-   *
-   * @author rnewman
+   * I translate the fine-grained feedback of a SynchronizerSessionDelegate into
+   * the coarse-grained feedback of a SynchronizerDelegate.
    */
   public class SynchronizerDelegateSessionDelegate implements
       SynchronizerSessionDelegate {
@@ -126,6 +99,9 @@ public class Synchronizer {
   public RepositorySessionBundle bundleA;
   public RepositorySessionBundle bundleB;
 
+  /**
+   * Start synchronizing, calling delegate's callback methods.
+   */
   public void synchronize(Context context, SynchronizerDelegate delegate) {
     SynchronizerDelegateSessionDelegate sessionDelegate = new SynchronizerDelegateSessionDelegate(delegate);
     SynchronizerSession session = new SynchronizerSession(this, sessionDelegate);
@@ -137,7 +113,13 @@ public class Synchronizer {
     return new SynchronizerConfiguration(syncID, bundleA, bundleB);
   }
 
-  // Not thread-safe.
+  /**
+   * Set my repository session bundles from a SynchronizerConfiguration.
+   *
+   * This method is not thread-safe.
+   *
+   * @param config
+   */
   public void load(SynchronizerConfiguration config) {
     bundleA = config.remoteBundle;
     bundleB = config.localBundle;