Adjust Region class with valid regions plus endpoint mappings for terminal api live (#1407)

Co-authored-by: kwokhe <kwokhe.chu@adyen.com>

Author: DjoykeAbyah

README.md

@@ -304,6 +304,12 @@ import com.adyen.model.terminal.*;
 // Step 2: Initialize the client object
 Client client = new Client("Your YOUR_API_KEY", Environment.TEST);
 
+// for LIVE environment use
+// Config config = new Config();
+// config.setEnvironment(Environment.LIVE);
+// config.setTerminalApiRegion(Region.EU);
+// Client client = new Client(config);
+
 // Step 3: Initialize the API object
 TerminalCloudAPI terminalCloudApi = new TerminalCloudAPI(client);
 

pom.xml

@@ -270,5 +270,11 @@
             <version>${swagger-core-version}</version>
             <scope>compile</scope>
         </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <version>5.10.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 </project>

src/main/java/com/adyen/Client.java

@@ -1,6 +1,7 @@
 package com.adyen;
 
 import com.adyen.enums.Environment;
+import com.adyen.enums.Region;
 import com.adyen.httpclient.AdyenHttpClient;
 import com.adyen.httpclient.ClientInterface;
 
@@ -13,6 +14,9 @@ public class Client {
     public static final String LIB_VERSION = "32.1.0";
     public static final String TERMINAL_API_ENDPOINT_TEST = "https://terminal-api-test.adyen.com";
     public static final String TERMINAL_API_ENDPOINT_LIVE = "https://terminal-api-live.adyen.com";
+    public static final String TERMINAL_API_ENDPOINT_US = "https://terminal-api-live-us.adyen.com";
+    public static final String TERMINAL_API_ENDPOINT_AU = "https://terminal-api-live-au.adyen.com";
+    public static final String TERMINAL_API_ENDPOINT_APSE = "https://terminal-api-live-apse.adyen.com";
 
     public Client() {
         this.config = new Config();
@@ -127,16 +131,35 @@ public void setEnvironment(Environment environment) {
      * @param liveEndpointUrlPrefix Provide the unique live url prefix from the "API URLs and Response" menu in the Adyen Customer Area
      */
     public void setEnvironment(Environment environment, String liveEndpointUrlPrefix) {
-        if (liveEndpointUrlPrefix != null) {
-            config.setLiveEndpointUrlPrefix(liveEndpointUrlPrefix);
+        config.setEnvironment(environment);
+        config.setLiveEndpointUrlPrefix(liveEndpointUrlPrefix);
+
+        String endpoint = retrieveCloudEndpoint(config.getTerminalApiRegion(), environment);
+        config.setTerminalApiCloudEndpoint(endpoint);
+    }
+
+    /**
+     * @param region The region for which the endpoint is requested. If null or the region is not found, defaults to default EU endpoint.
+     */
+    public String retrieveCloudEndpoint(Region region, Environment environment) {
+        // Check the environment for TEST and get the endpoint
+        if (environment.equals(Environment.TEST)) {
+            return Client.TERMINAL_API_ENDPOINT_TEST;
         }
-        if (Environment.TEST.equals(environment)) {
-            this.config.setEnvironment(environment);
-            this.config.setTerminalApiCloudEndpoint(TERMINAL_API_ENDPOINT_TEST);
-        } else if (Environment.LIVE.equals(environment)) {
-            this.config.setEnvironment(environment);
-            this.config.setTerminalApiCloudEndpoint(TERMINAL_API_ENDPOINT_LIVE);
+
+        // For LIVE environment, lookup the endpoint using the map
+        if (environment.equals(Environment.LIVE)) {
+            if (region == null) {
+                return Region.TERMINAL_API_ENDPOINTS_MAPPING.get(Region.EU);
+            }
+            if (!Region.TERMINAL_API_ENDPOINTS_MAPPING.containsKey(region)) {
+                throw new IllegalArgumentException("TerminalAPI endpoint for " + region + " is not supported yet");
+            }
+            return Region.TERMINAL_API_ENDPOINTS_MAPPING.getOrDefault(region, TERMINAL_API_ENDPOINT_LIVE);
         }
+
+        // Default to TEST if no environment or region is specified
+        return Client.TERMINAL_API_ENDPOINT_TEST;
     }
 
     @Override

src/main/java/com/adyen/Config.java

@@ -1,6 +1,7 @@
 package com.adyen;
 
 import com.adyen.enums.Environment;
+import com.adyen.enums.Region;
 
 import javax.net.ssl.HostnameVerifier;
 import javax.net.ssl.SSLContext;
@@ -22,6 +23,7 @@ public class Config {
     protected String terminalApiCloudEndpoint;
     protected String terminalApiLocalEndpoint;
     protected String liveEndpointUrlPrefix;
+    protected Region terminalApiRegion;
     protected SSLContext sslContext;
     protected HostnameVerifier hostnameVerifier;
 
@@ -85,6 +87,14 @@ public void setTerminalApiLocalEndpoint(String terminalApiLocalEndpoint) {
         this.terminalApiLocalEndpoint = terminalApiLocalEndpoint;
     }
 
+    public Region getTerminalApiRegion() {
+        return terminalApiRegion;
+    }
+
+    public void setTerminalApiRegion(Region terminalApiRegion) {
+        this.terminalApiRegion = terminalApiRegion;
+    }
+
     public int getConnectionTimeoutMillis() {
         return connectionTimeoutMillis;
     }

src/main/java/com/adyen/enums/Region.java

@@ -1,8 +1,46 @@
 package com.adyen.enums;
 
+import java.util.Map;
+import com.adyen.Client;
+
 public enum Region {
+
+    /**
+     * European Union region
+     */
     EU,
+
+    /**
+     * Australia region
+     */
     AU,
+
+    /**
+     * United States region
+     */
     US,
-    IN
+
+    /**
+     * India region
+     */
+    IN,
+
+    /**
+     * Asia-Pacific, South East region
+     */
+    APSE;
+
+    /**
+     * Maps regions to their respective Terminal API endpoints.
+     */
+    public static final Map<Region, String> TERMINAL_API_ENDPOINTS_MAPPING;
+
+    static {
+        TERMINAL_API_ENDPOINTS_MAPPING = Map.of(
+                Region.EU, Client.TERMINAL_API_ENDPOINT_LIVE,
+                Region.AU, Client.TERMINAL_API_ENDPOINT_AU,
+                Region.US, Client.TERMINAL_API_ENDPOINT_US,
+                Region.APSE, Client.TERMINAL_API_ENDPOINT_APSE
+        );
+    }
 }

src/test/java/com/adyen/ClientTest.java

@@ -1,14 +1,20 @@
 package com.adyen;
 
-import com.adyen.enums.Environment;
-import com.adyen.enums.Region;
-import com.adyen.model.RequestOptions;
+import java.util.HashMap;
+import java.util.stream.Stream;
+
+import javax.net.ssl.SSLContext;
+
 import org.junit.Assert;
 import org.junit.Test;
 import org.mockito.Mock;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
 
-import javax.net.ssl.SSLContext;
-import java.util.HashMap;
+import com.adyen.enums.Environment;
+import com.adyen.enums.Region;
+import com.adyen.model.RequestOptions;
 
 public class ClientTest {
 
@@ -18,16 +24,16 @@ public class ClientTest {
     @Mock
     private String apiKey;
 
+    
     @Test
     public void testConfigTestClient() {
         Config config = new Config();
         config.setEnvironment(Environment.TEST);
         config.setApiKey(apiKey);
         Client client = new Client(config);
-
         Assert.assertEquals(Environment.TEST, client.getConfig().getEnvironment());
     }
-
+    
     @Test
     public void testConfigLiveClient() {
         Config config = new Config();
@@ -38,6 +44,56 @@ public void testConfigLiveClient() {
         Assert.assertEquals(Environment.LIVE, client.getConfig().getEnvironment());
     }
 
+    private static Stream<Arguments> provideCloudTestEndpointTestCases() {
+        return Stream.of(
+            Arguments.of(null, Environment.TEST, "https://terminal-api-test.adyen.com"),
+            Arguments.of(Region.EU, Environment.TEST, "https://terminal-api-test.adyen.com"),
+            Arguments.of(Region.AU, Environment.TEST, "https://terminal-api-test.adyen.com"),
+            Arguments.of(Region.US, Environment.TEST, "https://terminal-api-test.adyen.com"),
+            Arguments.of(Region.APSE, Environment.TEST, "https://terminal-api-test.adyen.com")
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource("provideCloudTestEndpointTestCases")
+    public void testGetCloudEndpointForTestEnvironment(Region region, Environment environment, String expectedEndpoint) {
+        Config testConfig = new Config();
+        testConfig.setEnvironment(Environment.TEST);
+        testConfig.setTerminalApiRegion(region);
+        Client testClient = new Client(testConfig);
+        Assert.assertEquals(expectedEndpoint, testConfig.getTerminalApiCloudEndpoint());
+    }
+
+    private static Stream<Arguments> provideCloudLiveEndpointTestCases() {
+        return Stream.of(
+            Arguments.of(null, Environment.LIVE, "https://terminal-api-live.adyen.com"),
+            Arguments.of(Region.EU, Environment.LIVE, "https://terminal-api-live.adyen.com"),
+            Arguments.of(Region.AU, Environment.LIVE, "https://terminal-api-live-au.adyen.com"),
+            Arguments.of(Region.US, Environment.LIVE, "https://terminal-api-live-us.adyen.com"),
+            Arguments.of(Region.APSE, Environment.LIVE, "https://terminal-api-live-apse.adyen.com")
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource("provideCloudLiveEndpointTestCases")
+    public void testGetCloudEndpointForLiveEnvironment(Region region, Environment environment, String expectedEndpoint) {
+        Config liveConfig = new Config();
+        liveConfig.setEnvironment(Environment.LIVE);
+        liveConfig.setTerminalApiRegion(region);
+        Client liveClient = new Client(liveConfig);
+        Assert.assertEquals(expectedEndpoint, liveConfig.getTerminalApiCloudEndpoint());
+    }
+
+    @Test
+    public void testUnmappedIndiaRegionThrowsException() {
+        Config config = new Config();
+        config.setEnvironment(Environment.LIVE);
+        config.setTerminalApiRegion(Region.IN);
+
+        Assert.assertThrows(IllegalArgumentException.class,
+                () -> new Client(config));
+    }      
+
     @Test
     public void testClientCertificateAuth() {
         Client client = new Client(clientCertificateAuthSSLContext, apiKey);
@@ -54,8 +110,4 @@ public void testRequestOptionsBuilderPattern() {
                 .additionalServiceHeaders(map);
         Assert.assertEquals(requestOptions.getAdditionalServiceHeaders(), map);
     }
-
-    private void assertCommonEndpoints(Config config) {
-        Assert.assertEquals(Client.TERMINAL_API_ENDPOINT_LIVE, config.getTerminalApiCloudEndpoint());
-    }
-}
+}

src/test/java/com/adyen/RegionTest.java

@@ -0,0 +1,55 @@
+package com.adyen;
+
+import com.adyen.enums.Region;
+import java.util.stream.Collectors;
+import org.junit.Test;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+
+public class RegionTest {
+    @Test
+    public void testValidRegions() {
+        List<Region> VALID_REGIONS = List.of(Region.values());
+
+        // Convert Regions.VALID_REGIONS to lowercase strings for comparison
+        List<String> actual = VALID_REGIONS.stream()
+            .map(region -> region.name().toLowerCase())
+            .collect(Collectors.toList());
+
+        // Define the expected list of valid regions
+        List<String> expected = List.of(
+            "eu",
+            "au",
+            "us",
+            "in",
+            "apse"
+        );
+
+        // Assert that the VALID_REGIONS in Region matches the expected list
+        assertEquals(expected, actual);
+    }
+
+    @Test
+    public void testTerminalApiEndpointsMapping() {
+        // Convert TERMINAL_API_ENDPOINTS_MAPPING keys to lowercase strings for comparison
+        Map<String, String> actual = Region.TERMINAL_API_ENDPOINTS_MAPPING.entrySet()
+            .stream()
+            .collect(Collectors.toMap(
+                entry -> entry.getKey().name().toLowerCase(), // Convert key (Region enum) to lowercase
+                Map.Entry::getValue
+        ));
+        
+        // Define the expected map of region to endpoint mappings
+        Map<String, String> expected = Map.of(
+            "eu", "https://terminal-api-live.adyen.com",
+            "au", "https://terminal-api-live-au.adyen.com",
+            "us", "https://terminal-api-live-us.adyen.com",
+            "apse", "https://terminal-api-live-apse.adyen.com"
+        );
+
+        // Assert that the TERMINAL_API_ENDPOINTS_MAPPING in Region matches the expected map
+        assertEquals(expected, actual);
+    }
+}