docs: improve retry configuration documentation (#104)

* Update README and JSDocs

* Fix default value UT

* Improve samples

* More sample fixes

* Whoops

Author: dmbrooke

README.md

@@ -72,12 +72,12 @@ import java.net.http.HttpResponse;
 
 public class PushOneDocument {
     public static void main(String[] args) {
-        Source source = new Source("my_api_key", "my_org_id");
+        Source pushSource = new PushSource("my_api_key", "my_org_id");
         DocumentBuilder documentBuilder = new DocumentBuilder("https://my.document.uri", "My document title")
                 .withData("these words will be searchable");
 
         try {
-            HttpResponse<String> response = source.addOrUpdateDocument("my_source_id", documentBuilder);
+            HttpResponse<String> response = pushSource.addOrUpdateDocument("my_source_id", documentBuilder);
             System.out.println(String.format("Source creation status: %s", response.statusCode()));
             System.out.println(String.format("Source creation response: %s", response.body()));
         } catch (IOException e) {
@@ -90,6 +90,36 @@ public class PushOneDocument {
 
 ```
 
+### Exponential backoff retry configuration
+
+By default, the SDK leverages an exponential backoff retry mechanism. Exponential backoff allows for the SDK to make multiple attempts to resolve throttled requests, increasing the amount of time to wait for each subsequent attempt. Outgoing requests will retry when a `429` status code is returned from the platform.
+
+The exponential backoff parameters are as follows:
+
+- `retryAfter` - The amount of time, in milliseconds, to wait between throttled request attempts.
+
+  Optional, will default to 5,000.
+
+- `maxRetries` - The maximum number of times to retry throttled requests.
+
+  Optional, will default to 10.
+
+- `timeMultiple` - The multiple by which to increase the wait time between each throttled request attempt.
+
+  Optional, will default to 2.
+
+You may configure the exponential backoff that will be applied to all outgoing requests. To do so, specify use the `BackoffOptionsBuilder` class to create a `BackoffOptions` object when creating either a `PushService`, `PushSource`, or `StreamService` object:
+
+```java
+PushSource pushSource = new PushSource("my_api_key", "my_org_id", new BackoffOptionsBuilder().withMaxRetries(5).withRetryAfter(10000).build());
+
+PushService pushService = new PushService(myPushEnabledSource, new BackoffOptionsBuilder().withMaxRetries(10).build());
+
+StreamService streamService = new StreamService(myStreamEnabledSource, new BackoffOptionsBuilder().withRetryAfter(2000).withTimeMultiple(3).build());
+```
+
+By default, requests will retry a maximum of 10 times, waiting 5 seconds after the first attempt, with a time multiple of 2 (which will equate to a maximum execution time of roughly 1.5 hours).
+
 ## Logging
 
 If you want to push multiple documents to your Coveo organization and use a service for that (e.g. `PushService`, `StreamService`), you may find it useful to configure a **logger** to catch error and warning messages.

samples/DeleteOneDocument.java

@@ -5,7 +5,8 @@
 
 public class DeleteOneDocument {
     public static void main(String[] args) {
-        PushSource source = new PushSource("my_api_key", "my_org_id");
+        URL sourceUrl = new URL("https://api.cloud.coveo.com/push/v1/organizations/org_id/sources/source_id");
+        PushSource source = new PushSource("my_api_key", sourceUrl);
         String documentId = "https://my.document.uri";
         Boolean deleteChildren = true;
 

samples/PushOneDocument.java

@@ -1,18 +1,20 @@
 import com.coveo.pushapiclient.BackoffOptionsBuilder;
 import com.coveo.pushapiclient.DocumentBuilder;
 import com.coveo.pushapiclient.PushSource;
+import com.coveo.pushapiclient.PlatformUrlBuilder;
 
 import java.io.IOException;
 import java.net.http.HttpResponse;
 
 public class PushOneDocument {
     public static void main(String[] args) {
-        PushSource source = new PushSource("my_api_key", "my_org_id", new BackoffOptionsBuilder().withMaxRetries(5).withRetryAfter(10000).build());
+        PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id");
+
         DocumentBuilder documentBuilder = new DocumentBuilder("https://my.document.uri", "My document title")
                 .withData("these words will be searchable");
 
         try {
-            HttpResponse<String> response = source.addOrUpdateDocument("my_source_id", documentBuilder);
+            HttpResponse<String> response = source.addOrUpdateDocument(documentBuilder);
             System.out.println(String.format("Push document status: %s", response.statusCode()));
             System.out.println(String.format("Push document response: %s", response.body()));
         } catch (IOException e) {

samples/PushOneDocumentWithMetadata.java

@@ -1,6 +1,7 @@
 import com.coveo.pushapiclient.BackoffOptions;
 import com.coveo.pushapiclient.BackoffOptionsBuilder;
 import com.coveo.pushapiclient.DocumentBuilder;
+import com.coveo.pushapiclient.PlatformUrlBuilder;
 import com.coveo.pushapiclient.PushSource;
 
 import java.io.IOException;
@@ -9,7 +10,7 @@
 
 public class PushOneDocumentWithMetadata {
     public static void main(String[] args) {
-        PushSource source = new PushSource("my_api_key", "my_org_id", new BackoffOptionsBuilder().withTimeMultiple(1).build());
+        PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id", new PlatformUrlBuilder().build(), new BackoffOptionsBuilder().withTimeMultiple(1).build());
         DocumentBuilder documentBuilder = new DocumentBuilder("https://my.document.uri", "My document title")
                 .withData("these words will be searchable")
                 .withAuthor("bob")
@@ -22,7 +23,7 @@ public static void main(String[] args) {
                 }});
 
         try {
-            HttpResponse<String> response = source.addOrUpdateDocument("my_source_id", documentBuilder);
+            HttpResponse<String> response = source.addOrUpdateDocument(documentBuilder);
             System.out.println(String.format("Push document status: %s", response.statusCode()));
             System.out.println(String.format("Push document response: %s", response.body()));
         } catch (IOException e) {

samples/PushOneDocumentWithPermissions.java

@@ -17,7 +17,7 @@ public static void main(String[] args) {
                 .withDeniedPermissions(deniedUsers);
 
         try {
-            HttpResponse<String> response = source.addOrUpdateDocument("my_source_id", documentBuilder);
+            HttpResponse<String> response = source.addOrUpdateDocument(documentBuilder);
             System.out.println(String.format("Push document status: %s", response.statusCode()));
             System.out.println(String.format("Push document response: %s", response.body()));
         } catch (IOException e) {

src/main/java/com/coveo/pushapiclient/BackoffOptions.java

@@ -5,6 +5,13 @@ public class BackoffOptions {
   private final int maxRetries;
   private final int timeMultiple;
 
+  /**
+   * @param retryAfter The amount of time, in milliseconds, to wait between throttled request
+   *     attempts.
+   * @param maxRetries The maximum number of times to retry throttled requests.
+   * @param timeMultiple The multiple by which to increase the wait time between each throttled
+   *     request attempt.
+   */
   public BackoffOptions(int retryAfter, int maxRetries, int timeMultiple) {
     this.retryAfter = retryAfter;
     this.maxRetries = maxRetries;

src/main/java/com/coveo/pushapiclient/BackoffOptionsBuilder.java

@@ -2,7 +2,7 @@
 
 public class BackoffOptionsBuilder {
   public static final int DEFAULT_RETRY_AFTER = 5000;
-  public static final int DEFAULT_MAX_RETRIES = 50;
+  public static final int DEFAULT_MAX_RETRIES = 10;
   public static final int DEFAULT_TIME_MULTIPLE = 2;
 
   private int retryAfter = DEFAULT_RETRY_AFTER;

src/test/java/com/coveo/pushapiclient/BackoffOptionsBuilderTest.java

@@ -18,7 +18,7 @@ public void setup() {
   public void testWithDefaultValues() {
     BackoffOptions backoffOptions = backoffOptionsBuilder.build();
     assertEquals("Should return default retry after time", 5000, backoffOptions.getRetryAfter());
-    assertEquals("Should return default max retries", 50, backoffOptions.getMaxRetries());
+    assertEquals("Should return default max retries", 10, backoffOptions.getMaxRetries());
     assertEquals("Should return default time multiple", 2, backoffOptions.getTimeMultiple());
   }