Added documentation, tests.

richardjrossiii · richardjrossiii · commit 8cea8da5dc9e · 2015-12-11T14:29:27.000-08:00
diff --git a/Parse/src/main/java/com/parse/Parse.java b/Parse/src/main/java/com/parse/Parse.java
@@ -24,6 +24,7 @@
 import java.io.UnsupportedEncodingException;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
@@ -36,28 +37,103 @@
  * library.
  */
 public class Parse {
+  /**
+   * Represents an opaque configuration for the {@code Parse} SDK configuration.
+   */
   public static final class Configuration {
+    /**
+     * Allows for simple constructing of a {@code Configuration} object.
+     */
     public static final class Builder {
       private Context context;
       private String applicationId;
       private String clientKey;
       private boolean localDataStoreEnabled;
       private List<ParseNetworkInterceptor> interceptors;
 
+      /**
+       * Initialize a bulider with a given context.
+       *
+       * This context will then be passed through to the rest of the Parse SDK for use during
+       * initialization.
+       *
+       * <p/>
+       * You may define {@code com.parse.APPLICATION_ID} and {@code com.parse.CLIENT_KEY}
+       * {@code meta-data} in your {@code AndroidManifest.xml}:
+       * <pre>
+       * &lt;manifest ...&gt;
+       *
+       * ...
+       *
+       *   &lt;application ...&gt;
+       *     &lt;meta-data
+       *       android:name="com.parse.APPLICATION_ID"
+       *       android:value="@string/parse_app_id" /&gt;
+       *     &lt;meta-data
+       *       android:name="com.parse.CLIENT_KEY"
+       *       android:value="@string/parse_client_key" /&gt;
+       *
+       *       ...
+       *
+       *   &lt;/application&gt;
+       * &lt;/manifest&gt;
+       * </pre>
+       * <p/>
+       *
+       * This will cause the values for {@code applicationId} and {@code clientKey} to be set to
+       * those defined in your manifest.
+       *
+       * @param context The active {@link Context} for your application. Cannot be null.
+       */
       public Builder(Context context) {
         this.context = context;
+
+        // Yes, our public API states we cannot be null. But for unit tests, it's easier just to
+        // support null here.
+        if (context != null) {
+          Context applicationContext = context.getApplicationContext();
+          Bundle metaData = ManifestInfo.getApplicationMetadata(applicationContext);
+          if (metaData != null) {
+            applicationId = metaData.getString(PARSE_APPLICATION_ID);
+            clientKey = metaData.getString(PARSE_CLIENT_KEY);
+          }
+        }
       }
 
+      /**
+       * Set the application id to be used by Parse.
+       *
+       * This method is only required if you intend to use a different {@code applicationId} than
+       * is defined by {@code com.parse.APPLICATION_ID} in your {@code AndroidManifest.xml}.
+       *
+       * @param applicationId The application id to set.
+       * @return The same builder, for easy chaining.
+       */
       public Builder applicationId(String applicationId) {
         this.applicationId = applicationId;
         return this;
       }
 
+      /**
+       * Set the client key to be used by Parse.
+       *
+       * This method is only required if you intend to use a different {@code clientKey} than
+       * is defined by {@code com.parse.CLIENT_KEY} in your {@code AndroidManifest.xml}.
+       *
+       * @param clientKey The client key to set.
+       * @return The same builder, for easy chaining.
+       */
       public Builder clientKey(String clientKey) {
         this.clientKey = clientKey;
         return this;
       }
 
+      /**
+       * Add a {@link ParseNetworkInterceptor}.
+       *
+       * @param interceptor The interceptor to add.
+       * @return The same builder, for easy chaining.
+       */
       public Builder addNetworkInterceptor(ParseNetworkInterceptor interceptor) {
         if (interceptors == null) {
           interceptors = new ArrayList<>();
@@ -66,36 +142,52 @@ public Builder addNetworkInterceptor(ParseNetworkInterceptor interceptor) {
         return this;
       }
 
+      /**
+       * Enable pinning in your application. This must be called before your application can use
+       * pinning.
+       * @return The same builder, for easy chaining.
+       */
       public Builder enableLocalDataStore() {
         localDataStoreEnabled = true;
         return this;
       }
 
       private Builder setNetworkInterceptors(Collection<ParseNetworkInterceptor> interceptors) {
         if (interceptors != null) {
-          interceptors.clear();
-          interceptors.addAll(interceptors);
+          this.interceptors.clear();
+          this.interceptors.addAll(interceptors);
         }
         return this;
       }
 
+      private Builder setLocalDatastoreEnabled(boolean enabled) {
+        localDataStoreEnabled = enabled;
+        return this;
+      }
+
+      /**
+       * Construct this builder into a concrete {@code Configuration} instance.
+       * @return A constructed {@code Configuration} object.
+       */
       public Configuration build() {
         return new Configuration(this);
       }
     }
 
-    private final Context context;
-    private final String applicationId;
-    private final String clientKey;
-    private final boolean localDataStoreEnabled;
-    private final List<ParseNetworkInterceptor> interceptors;
+    /* package for tests */ final Context context;
+    /* package for tests */ final String applicationId;
+    /* package for tests */ final String clientKey;
+    /* package for tests */ final boolean localDataStoreEnabled;
+    /* package for tests */ final List<ParseNetworkInterceptor> interceptors;
 
     private Configuration(Builder builder) {
       this.context = builder.context;
       this.applicationId = builder.applicationId;
       this.clientKey = builder.clientKey;
       this.localDataStoreEnabled = builder.localDataStoreEnabled;
-      this.interceptors = builder.interceptors;
+      this.interceptors = builder.interceptors != null ?
+        Collections.unmodifiableList(new ArrayList<>(builder.interceptors)) :
+        null;
     }
   }
 
@@ -110,8 +202,6 @@ private Configuration(Builder builder) {
   private static boolean isLocalDatastoreEnabled;
   private static OfflineStore offlineStore;
 
-  private static Configuration configuration;
-
   /**
    * Enable pinning in your application. This must be called before your application can use
    * pinning. You must invoke {@code enableLocalDatastore(Context)} before
@@ -199,36 +289,23 @@ public static void enableLocalDatastore(Context context) {
    *          The active {@link Context} for your application.
    */
   public static void initialize(Context context) {
-    Context applicationContext = context.getApplicationContext();
-    String applicationId;
-    String clientKey;
-    Bundle metaData = ManifestInfo.getApplicationMetadata(applicationContext);
-    if (metaData != null) {
-      applicationId = metaData.getString(PARSE_APPLICATION_ID);
-      clientKey = metaData.getString(PARSE_CLIENT_KEY);
-
-      if (applicationId == null) {
-        throw new RuntimeException("ApplicationId not defined. " +
-                "You must provide ApplicationId in AndroidManifest.xml.\n" +
-                "<meta-data\n" +
-                "    android:name=\"com.parse.APPLICATION_ID\"\n" +
-                "    android:value=\"<Your Application Id>\" />");
-      }
-      if (clientKey == null) {
-        throw new RuntimeException("ClientKey not defined. " +
-                "You must provide ClientKey in AndroidManifest.xml.\n" +
-                "<meta-data\n" +
-                "    android:name=\"com.parse.CLIENT_KEY\"\n" +
-                "    android:value=\"<Your Client Key>\" />");
-      }
-    } else {
-      throw new RuntimeException("Can't get Application Metadata");
-    }
-    initialize(new Configuration.Builder(context)
-      .applicationId(applicationId)
-      .clientKey(clientKey)
-      .setNetworkInterceptors(interceptors)
-      .build()
+    Configuration.Builder builder = new Configuration.Builder(context);
+    if (builder.applicationId == null) {
+      throw new RuntimeException("ApplicationId not defined. " +
+        "You must provide ApplicationId in AndroidManifest.xml.\n" +
+        "<meta-data\n" +
+        "    android:name=\"com.parse.APPLICATION_ID\"\n" +
+        "    android:value=\"<Your Application Id>\" />");
+    } if (builder.clientKey == null) {
+      throw new RuntimeException("ClientKey not defined. " +
+        "You must provide ClientKey in AndroidManifest.xml.\n" +
+        "<meta-data\n" +
+        "    android:name=\"com.parse.CLIENT_KEY\"\n" +
+        "    android:value=\"<Your Client Key>\" />");
+    }
+    initialize(builder.setNetworkInterceptors(interceptors)
+        .setLocalDatastoreEnabled(isLocalDatastoreEnabled)
+        .build()
     );
   }
 
@@ -263,26 +340,29 @@ public static void initialize(Context context, String applicationId, String clie
         .applicationId(applicationId)
         .clientKey(clientKey)
         .setNetworkInterceptors(interceptors)
+        .setLocalDatastoreEnabled(isLocalDatastoreEnabled)
         .build()
     );
   }
 
   public static void initialize(Configuration configuration) {
-    Parse.configuration = configuration;
+    // NOTE (richardross): We will need this here, as ParsePlugins uses the return value of
+    // isLocalDataStoreEnabled() to perform additional behavior.
+    isLocalDatastoreEnabled = configuration.localDataStoreEnabled;
 
     ParsePlugins.Android.initialize(configuration.context, configuration.applicationId, configuration.clientKey);
     Context applicationContext = configuration.context.getApplicationContext();
 
     ParseHttpClient.setKeepAlive(true);
     ParseHttpClient.setMaxConnections(20);
     // If we have interceptors in list, we have to initialize all http clients and add interceptors
-    if (interceptors != null) {
-      initializeParseHttpClientsWithParseNetworkInterceptors();
+    if (configuration.interceptors != null) {
+      initializeParseHttpClientsWithParseNetworkInterceptors(configuration.interceptors);
     }
 
     ParseObject.registerParseSubclasses();
 
-    if (isLocalDatastoreEnabled()) {
+    if (configuration.localDataStoreEnabled) {
       offlineStore = new OfflineStore(configuration.context);
     } else {
       ParseKeyValueCache.initialize(configuration.context);
@@ -665,9 +745,8 @@ private Parse() {
   private static List<ParseNetworkInterceptor> interceptors;
 
   // Initialize all necessary http clients and add interceptors to these http clients
-  private static void initializeParseHttpClientsWithParseNetworkInterceptors() {
+  private static void initializeParseHttpClientsWithParseNetworkInterceptors(List<ParseNetworkInterceptor> interceptors) {
     // This means developers have not called addInterceptor method so we should do nothing.
-    List<ParseNetworkInterceptor> interceptors = configuration.interceptors;
     if (interceptors == null) {
       return;
     }
diff --git a/Parse/src/test/java/com/parse/ParseClientConfigurationTest.java b/Parse/src/test/java/com/parse/ParseClientConfigurationTest.java
@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2015-present, Parse, LLC.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+package com.parse;
+
+import com.parse.http.ParseNetworkInterceptor;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+import static org.mockito.Mockito.mock;
+
+public class ParseClientConfigurationTest {
+
+  @Test
+  public void testBuilder() {
+    Parse.Configuration.Builder builder = new Parse.Configuration.Builder(null);
+    builder.applicationId("foo");
+    builder.clientKey("bar");
+    builder.enableLocalDataStore();
+    Parse.Configuration configuration = builder.build();
+
+    assertNull(configuration.context);
+    assertEquals(configuration.applicationId, "foo");
+    assertEquals(configuration.clientKey, "bar");
+    assertEquals(configuration.localDataStoreEnabled, true);
+  }
+
+  @Test
+  public void testNetworkInterceptors() {
+    ParseNetworkInterceptor interceptorA = mock(ParseNetworkInterceptor.class);
+    ParseNetworkInterceptor interceptorB = mock(ParseNetworkInterceptor.class);
+
+    Parse.Configuration.Builder builder = new Parse.Configuration.Builder(null);
+
+    builder.addNetworkInterceptor(interceptorA);
+    Parse.Configuration configurationA = builder.build();
+    builder.addNetworkInterceptor(interceptorB);
+    Parse.Configuration configurationB = builder.build();
+
+    assertFalse(configurationA.interceptors.contains(interceptorB));
+    assertTrue(configurationB.interceptors.contains(interceptorB));
+
+    try {
+      configurationA.interceptors.add(interceptorB);
+      fail();
+    } catch (UnsupportedOperationException ex) {
+      // Expected
+    }
+  }
+}
