feat: Support different platform regions

samples/CreateSource.java

@@ -1,3 +1,6 @@
+import com.coveo.pushapiclient.Region;
+import com.coveo.pushapiclient.PlatformUrl;
+import com.coveo.pushapiclient.PlatformUrlBuilder;
 import com.coveo.pushapiclient.Source;
 import com.coveo.pushapiclient.SourceVisibility;
 
@@ -6,7 +9,10 @@
 
 public class CreateSource {
     public static void main(String[] args) {
-        Source source = new Source("my_api_key", "my_org_id");
+        PlatformUrl platformUrl = new PlatformUrlBuilder()
+                .withRegion(Region.AU) // If your organization is located in a different region than Region.US
+                .build();
+        Source source = new Source("my_api_key", "my_org_id", platformUrl);
         try {
             HttpResponse<String> response = source.create("the_name_of_my_source", SourceVisibility.SECURED);
             System.out.println(String.format("Source creation status: %s", response.statusCode()));

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

@@ -4,18 +4,18 @@
  * Available environments to use as the host for the PushAPI.
  */
 public enum Environment {
-    PRODUCTION( "https://api.cloud.coveo.com"),
-    HIPAA("https://apihipaa.cloud.coveo.com"),
-    DEVELOPMENT("https://apidev.cloud.coveo.com"),
-    STAGING("https://apiqa.cloud.coveo.com");
+    PRODUCTION( "prod"),
+    HIPAA("hipaa"),
+    DEVELOPMENT("dev"),
+    STAGING("stg");
 
-    private String host;
+    private String value;
 
-    Environment(String host) {
-        this.host = host;
+    Environment(String value) {
+        this.value = value;
     }
 
-    public String getHost() {
-        return this.host;
+    public String getValue() {
+        return this.value;
     }
 }

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

@@ -19,7 +19,7 @@ public class PlatformClient {
     private final String apiKey;
     private final String organizationId;
     private final HttpClient httpClient;
-    private final Environment environment;
+    private final PlatformUrl platformUrl;
 
     /**
      * Construct a PlatformClient
@@ -28,10 +28,21 @@ public class PlatformClient {
      * @param organizationId The Coveo Organization identifier.
      */
     public PlatformClient(String apiKey, String organizationId) {
+        this(apiKey, organizationId, new PlatformUrlBuilder().build());
+    }
+
+    /**
+     * Construct a PlatformClient
+     *
+     * @param apiKey         An apiKey capable of pushing documents and managing sources in a Coveo organization. See [Manage API Keys](https://docs.coveo.com/en/1718).
+     * @param organizationId The Coveo Organization identifier.
+     * @param platformUrl    The PlatformUrl.
+     */
+    public PlatformClient(String apiKey, String organizationId, PlatformUrl platformUrl) {
         this.apiKey = apiKey;
         this.organizationId = organizationId;
         this.httpClient = HttpClient.newHttpClient();
-        this.environment = Environment.PRODUCTION;
+        this.platformUrl = platformUrl;
     }
 
     /**
@@ -45,21 +56,26 @@ public PlatformClient(String apiKey, String organizationId, HttpClient httpClien
         this.apiKey = apiKey;
         this.organizationId = organizationId;
         this.httpClient = httpClient;
-        this.environment = Environment.PRODUCTION;
+        this.platformUrl = new PlatformUrlBuilder().build();
     }
 
+
     /**
-     * Construct a PlatformClient
+     * @deprecated Please now use PlatformUrl to define your Platform environment
+     * @see PlatformUrl Construct a PlatformUrl
      *
      * @param apiKey         An apiKey capable of pushing documents and managing sources in a Coveo organization. See [Manage API Keys](https://docs.coveo.com/en/1718).
      * @param organizationId The Coveo Organization identifier.
      * @param environment    The Environment to be used.
      */
+    @Deprecated
     public PlatformClient(String apiKey, String organizationId, Environment environment) {
         this.apiKey = apiKey;
         this.organizationId = organizationId;
         this.httpClient = HttpClient.newHttpClient();
-        this.environment = environment;
+        this.platformUrl = new PlatformUrlBuilder()
+                .withEnvironment(environment)
+                .build();
     }
 
     /**
@@ -382,11 +398,11 @@ private String getBaseSourceURL() {
     }
 
     private String getBasePlatformURL() {
-        return String.format("https://platform.cloud.coveo.com/rest/organizations/%s", this.organizationId);
+        return String.format("%s/rest/organizations/%s", this.platformUrl.getPlatformUrl(),this.organizationId);
     }
 
     private String getBasePushURL() {
-        return String.format("%s/push/v1/organizations/%s", this.environment.getHost(), this.organizationId);
+        return String.format("%s/push/v1/organizations/%s", this.platformUrl.getApiUrl(), this.organizationId);
     }
 
     private String getBaseProviderURL(String providerId) {

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

@@ -0,0 +1,42 @@
+package com.coveo.pushapiclient;
+
+public class PlatformUrl {
+
+    public static final Environment DEFAULT_ENVIRONMENT = Environment.PRODUCTION;
+    public static final Region DEFAULT_REGION = Region.US;
+
+    private final Environment environment;
+    private final Region region;
+
+    /**
+     * @param environment The environment platform of your organization
+     * @param region      The physical center of your organization
+     *
+     * @see https://docs.coveo.com/en/2976
+     */
+    public PlatformUrl(Environment environment, Region region) {
+        this.environment = environment;
+        this.region = region;
+    }
+
+    public String getPlatformUrl() {
+        return String.format("https://platform%s%s.cloud.coveo.com", this.getUrlEnvironment(), this.getUrlRegion());
+    }
+
+    public String getApiUrl() {
+        return String.format("https://api%s%s.cloud.coveo.com", this.getUrlEnvironment(), this.getUrlRegion());
+    }
+
+    private String getUrlEnvironment() {
+        return this.environment == PlatformUrl.DEFAULT_ENVIRONMENT
+                ? ""
+                : this.environment.getValue();
+    }
+
+    private String getUrlRegion() {
+        return  this.region == PlatformUrl.DEFAULT_REGION
+                ? ""
+                : String.format("-%s", this.region.getValue());
+    }
+
+}

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

@@ -0,0 +1,21 @@
+package com.coveo.pushapiclient;
+
+public class PlatformUrlBuilder {
+
+    private Environment environment = PlatformUrl.DEFAULT_ENVIRONMENT;
+    private Region region = PlatformUrl.DEFAULT_REGION;
+
+    public PlatformUrlBuilder withEnvironment(Environment environment) {
+        this.environment = environment;
+        return this;
+    }
+
+    public PlatformUrlBuilder withRegion(Region region) {
+        this.region = region;
+        return this;
+    }
+
+    public PlatformUrl build() {
+        return new PlatformUrl(this.environment, this.region);
+    }
+}

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

@@ -0,0 +1,20 @@
+package com.coveo.pushapiclient;
+
+/**
+ * Available Platform regions to connect to
+ */
+public enum Region {
+    US("us"),
+    EU("eu"),
+    AU("au");
+
+    private String value;
+
+    Region(String value) {
+        this.value = value;
+    }
+
+    public String getValue() {
+        return this.value;
+    }
+}

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

@@ -9,18 +9,35 @@ public class Source {
     PlatformClient platformClient;
 
     /**
-     * @param apiKey         An apiKey capable of pushing documents and managing sources in a Coveo organization. See [Manage API Keys](https://docs.coveo.com/en/1718).
+     * @param apiKey         An apiKey capable of pushing documents and managing
+     *                       sources in a Coveo organization. See [Manage API
+     *                       Keys](https://docs.coveo.com/en/1718).
      * @param organizationId The Coveo Organization identifier.
      */
     public Source(String apiKey, String organizationId) {
         this.platformClient = new PlatformClient(apiKey, organizationId);
     }
 
     /**
+     * @param apiKey         An apiKey capable of pushing documents and managing
+     *                       sources in a Coveo organization. See [Manage API
+     *                       Keys](https://docs.coveo.com/en/1718).
+     * @param organizationId The Coveo Organization identifier.
+     * @param platformUrl
+     */
+    public Source(String apiKey, String organizationId, PlatformUrl platformUrl) {
+        this.platformClient = new PlatformClient(apiKey, organizationId, platformUrl);
+    }
+
+    /**
+     * @deprecated Please now use PlatformUrl to define your Platform environment
+     * @see PlatformUrl Construct a PlatformUrl
+     *
      * @param apiKey         An apiKey capable of pushing documents and managing sources in a Coveo organization. See [Manage API Keys](https://docs.coveo.com/en/1718).
      * @param organizationId The Coveo Organization identifier.
      * @param environment    The Environment to be used.
      */
+    @Deprecated
     public Source(String apiKey, String organizationId, Environment environment) {
         this.platformClient = new PlatformClient(apiKey, organizationId, environment);
     }

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

@@ -0,0 +1,73 @@
+package com.coveo.pushapiclient;
+
+import org.junit.Before;
+import org.junit.Test;
+
+import static org.junit.Assert.*;
+
+public class PlatformUrlBuilderTest {
+
+    private PlatformUrlBuilder platformUrlBuilder;
+
+    @Before
+    public void setup() {
+        platformUrlBuilder = new PlatformUrlBuilder();
+    }
+
+    @Test
+    public void testWithDefaultValues() {
+        PlatformUrl platformUrl = platformUrlBuilder.build();
+        assertEquals(
+                "Should return default platform URL",
+                "https://platform.cloud.coveo.com",
+                platformUrl.getPlatformUrl());
+
+        assertEquals(
+                "Should return default API URL",
+                "https://api.cloud.coveo.com",
+                platformUrl.getApiUrl());
+    }
+
+    @Test
+    public void testWithNonDefaultRegion() {
+        PlatformUrl platformUrl = platformUrlBuilder.withRegion(Region.EU).build();
+        assertEquals(
+                "Should return Europe platform URL",
+                "https://platform-eu.cloud.coveo.com",
+                platformUrl.getPlatformUrl());
+
+        assertEquals(
+                "Should return Europe API URL",
+                "https://api-eu.cloud.coveo.com",
+                platformUrl.getApiUrl());
+    }
+
+    @Test
+    public void testWithNonDefaultEnvironment() {
+        PlatformUrl platformUrl = platformUrlBuilder.withEnvironment(Environment.STAGING).build();
+        assertEquals(
+                "Should return the staging platform URL",
+                "https://platformstg.cloud.coveo.com",
+                platformUrl.getPlatformUrl());
+
+        assertEquals(
+                "Should return the staging API URL",
+                "https://apistg.cloud.coveo.com",
+                platformUrl.getApiUrl());
+    }
+
+    @Test
+    public void testWithNonDefaultEnvironmentAndRegion() {
+        PlatformUrl platformUrl = platformUrlBuilder
+                .withEnvironment(Environment.DEVELOPMENT)
+                .withRegion(Region.EU)
+                .build();
+        assertEquals(
+                "https://platformdev-eu.cloud.coveo.com",
+                platformUrl.getPlatformUrl());
+
+        assertEquals(
+                "https://apidev-eu.cloud.coveo.com",
+                platformUrl.getApiUrl());
+    }
+}