Merge pull request #70 from filestack/feature/FS-3988-improve-config-docs

Improve Config class documentation

Author: scana

build.gradle

@@ -1,9 +1,19 @@
+buildscript {
+    ext.kotlin_version = '1.2.61'
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
 plugins {
     id 'com.github.kt3k.coveralls' version '2.6.3'
     id 'com.jfrog.bintray' version '1.7.3'
 }
 
 apply plugin: 'checkstyle'
+apply plugin: 'kotlin'
 apply plugin: 'jacoco'
 apply plugin: 'java-library'
 apply plugin: 'maven'
@@ -25,6 +35,7 @@ dependencies {
     testImplementation 'junit:junit:4.12' // Testing
     testImplementation 'org.mockito:mockito-core:2.8.47' // Mocking
     testImplementation 'com.squareup.retrofit2:retrofit-mock:2.3.0' // Helpers for Retrofit
+    testImplementation "org.jetbrains.kotlin:kotlin-stdlib-jre7:$kotlin_version"
 
     compile 'com.squareup.okhttp3:okhttp:3.8.0' // Low-level HTTP client
     compile 'com.squareup.retrofit2:retrofit:2.3.0' // High-level HTTP client
@@ -35,7 +46,8 @@ dependencies {
         exclude group: 'com.google.code.findbugs', module: 'jsr305'
     })
 
-    compile 'io.reactivex.rxjava2:rxjava:2.1.2' // Observable pattern for async methods
+    compile 'io.reactivex.rxjava2:rxjava:2.1.2'
+    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version" // Observable pattern for async methods
 }
 
 javadoc {
@@ -150,3 +162,9 @@ jacocoTestReport {
         html.enabled = true
     }
 }
+
+compileTestKotlin {
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+}

src/main/java/com/filestack/Config.java

@@ -14,42 +14,67 @@ public class Config implements Serializable {
   protected final String signature;
   protected final String returnUrl;
 
-  /** Construct basic config. */
+  /**
+   * Constructs configuration for {@link Client} class.
+   * @param apiKey - an API key obtained from the Developer Portal
+   * @param policy - access policy, one can be created with {@link Policy.Builder}
+   */
+  public Config(String apiKey, Policy policy) {
+    this(apiKey, null, policy.getEncodedPolicy(), policy.getSignature());
+  }
+
+  /**
+   * Constructs basic configuration for {@link Client} class without any security policy.
+   * @param apiKey - an API key obtained from the Developer Portal
+  */
   public Config(String apiKey) {
-    this.apiKey = apiKey;
-    this.returnUrl = null;
-    this.policy = null;
-    this.signature = null;
+    this(apiKey, null, null, null);
   }
 
-  /** Construct config for auth.*/
+  /**
+   * Constructs basic configuration for {@link Client} class without any security policy.
+   * @param apiKey - an API key obtained from the Developer Portal
+   * @param returnUrl - returnUrl used for building JSON bodies with {@link com.filestack.internal.CloudServiceUtil}
+   * @deprecated use {@link #Config(String)} instead and manually pass returnUrl to
+   *     {@link com.filestack.internal.CloudServiceUtil#buildBaseJson(Config, String, String)} if necessary
+   */
+  @Deprecated
   public Config(String apiKey, String returnUrl) {
-    this.apiKey = apiKey;
-    this.returnUrl = returnUrl;
-    this.policy = null;
-    this.signature = null;
+    this(apiKey, returnUrl, null, null);
   }
 
-  /** Construct config for security. */
-  public Config(String apiKey, String policy, String signature) {
-    this.apiKey = apiKey;
-    this.returnUrl = null;
-    this.policy = policy;
-    this.signature = signature;
+  /**
+   * Constructs configuration for {@link Client} class.
+   * @param apiKey - an API key obtained from the Developer Portal
+   * @param encodedPolicy - encoded policy, obtain one using {@link Policy#getEncodedPolicy()}
+   * @param signature - policy signature, obtain one using {@link Policy#getSignature()}
+   */
+  public Config(String apiKey, String encodedPolicy, String signature) {
+    this(apiKey, null, encodedPolicy, signature);
   }
 
-  /** Construct config for auth and security. */
-  public Config(String apiKey, String returnUrl, String policy, String signature) {
+  /**
+   * Constructs configuration for {@link Client} class.
+   * @param apiKey - an API key obtained from the Developer Portal
+   * @param encodedPolicy - encoded policy, obtain one using {@link Policy#getEncodedPolicy()}
+   * @param signature - policy signature, obtain one using {@link Policy#getSignature()}
+   * @param returnUrl - returnUrl used for building JSON bodies with {@link com.filestack.internal.CloudServiceUtil}
+   * @deprecated use {@link #Config(String, String, String)} instead and manually pass returnUrl to
+   *     {@link com.filestack.internal.CloudServiceUtil#buildBaseJson(Config, String, String)} if necessary
+   */
+  @Deprecated
+  public Config(String apiKey, String returnUrl, String encodedPolicy, String signature) {
     this.apiKey = apiKey;
     this.returnUrl = returnUrl;
-    this.policy = policy;
+    this.policy = encodedPolicy;
     this.signature = signature;
   }
 
   public String getApiKey() {
     return apiKey;
   }
 
+  @Deprecated
   public String getReturnUrl() {
     return returnUrl;
   }

src/main/java/com/filestack/Policy.java

@@ -12,7 +12,7 @@
  * Determines what access a user is allowed (if account security is enabled). A policy sets access
  * and a signature validates the policy. This class should only be used in server-side code. Do not
  * include your app secret in client-side code.
- * @see <a href="https://www.filestack.com/docs/security">Filestack Security Docs</a>
+ * @see <a href="https://www.filestack.com/docs/security/creating-policies">Filestack Docs - Creating policies</a>
  */
 public class Policy {
   public static final String CALL_PICK = "pick";

src/main/java/com/filestack/internal/CloudServiceUtil.java

@@ -22,10 +22,19 @@ public class CloudServiceUtil {
 
   private static final String VALUE_FLOW_MOBILE = "mobile";
 
+
   /**
    * Create the base JSON object with properties needed for all requests.
+   * @deprecated explicitly pass returnUrl with {@link #buildBaseJson(Config, String, String)} instead.
    */
   public static JsonObject buildBaseJson(Config config, String session) {
+    return buildBaseJson(config, session, config.getReturnUrl());
+  }
+
+  /**
+   * Create the base JSON object with properties needed for all requests.
+   */
+  public static JsonObject buildBaseJson(Config config, String session, String returnUrl) {
 
     JsonObject json = new JsonObject();
     json.addProperty(KEY_API_KEY, config.getApiKey());
@@ -36,8 +45,8 @@ public static JsonObject buildBaseJson(Config config, String session) {
       json.addProperty(KEY_SIGNATURE, config.getSignature());
     }
 
-    if (config.getReturnUrl() != null) {
-      json.addProperty(KEY_APP_URL, config.getReturnUrl());
+    if (returnUrl != null) {
+      json.addProperty(KEY_APP_URL, returnUrl);
     }
 
     if (session != null) {

src/test/java/com/filestack/ConfigTest.kt

@@ -0,0 +1,31 @@
+package com.filestack
+
+import org.junit.Assert
+import org.junit.Assert.*
+import org.junit.Test
+
+class ConfigTest {
+
+    @Test
+    fun `verifies security`() {
+        var config = Config("api_key")
+        assertFalse(config.hasSecurity())
+
+        config = Config("api_key", "return_url", "policy", null)
+        assertFalse(config.hasSecurity())
+
+        config = Config("api_key", "return_url", null, "policy")
+        assertFalse(config.hasSecurity())
+
+        config = Config("api_key", "return_url", "policy", "signature")
+        assertTrue(config.hasSecurity())
+
+        val policy = Policy.Builder()
+                .giveFullAccess()
+                .build("api_key")
+
+        config = Config("api_key", policy)
+        assertTrue(config.hasSecurity())
+    }
+
+}