breaking: Remove verify2.Locale enum (#499)

Author: SMadani

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Bumped Jackson version to 2.16.0
 - Use String instead of UUID in `VoiceClient` call modification methods
 - Added public `verifyRequestSignature` method to `RequestSigning`
+- Replaced custom `Locale` enum in Verify v2 with `java.util.Locale`
 
 # [8.0.0-rc2] - 2023-11-07
 - Removed packages:

src/main/java/com/vonage/client/verify2/Locale.java

@@ -15,13 +15,11 @@
  */
 package com.vonage.client.verify2;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
-import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
-import com.fasterxml.jackson.annotation.JsonInclude;
-import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.*;
 import com.vonage.client.Jsonable;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Locale;
 import java.util.Objects;
 import java.util.regex.Pattern;
 
@@ -41,7 +39,7 @@
 public class VerificationRequest implements Jsonable {
 	static final Pattern CODE_REGEX = Pattern.compile("[a-zA-Z0-9]{4,10}");
 
-	protected final Locale locale;
+	@JsonProperty("locale") protected final Locale locale;
 	protected final Integer channelTimeout, codeLength;
 	protected final Boolean fraudCheck;
 	protected final String brand, code, clientRef;
@@ -98,13 +96,18 @@ public String getBrand() {
 	/**
 	 * Language for the request in ISO_639-1 format.
 	 *
-	 * @return The language as an enum, or {@code null} if not set (the default).
+	 * @return The locale, or {@code null} if not set (the default).
 	 */
-	@JsonProperty("locale")
+	@JsonIgnore
 	public Locale getLocale() {
 		return locale;
 	}
 
+	@JsonGetter("locale")
+	protected String getLocaleAsString() {
+		return locale == null ? null : locale.toString().replace("_", "-").toLowerCase();
+	}
+
 	/**
 	 * Specifies the wait time in seconds between attempts to delivery the verification code.
 	 *
@@ -292,17 +295,40 @@ public Builder channelTimeout(int timeout) {
 
 		/**
 		 * (OPTIONAL)
-		 * Languages that are available to use.
+		 * Set the language that this request will be delivered in. Refer to
+		 * <a href=https://developer.vonage.com/en/verify/guides/verify-v2-languages>the documentation</a>
+		 * for a list of supported locales.
 		 *
-		 * @param locale The language locale as an enum.
+		 * @param locale The language locale.
 		 *
 		 * @return This builder.
+		 *
+		 * @since 8.0.0
 		 */
 		public Builder locale(Locale locale) {
+			if (locale == null || locale.toString().isEmpty()) {
+				throw new IllegalArgumentException("Invalid locale");
+			}
 			this.locale = locale;
 			return this;
 		}
 
+		/**
+		 * (OPTIONAL)
+		 * Set the language that this request will be delivered in.
+		 *
+		 * @param locale The language locale as a string. This should be a
+		 * <a href=https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes>ISO 639-1 code</a>.
+		 *
+		 * @return This builder.
+		 *
+		 * @since 8.0.0
+		 * @see #locale(Locale)
+		 */
+		public Builder locale(String locale) {
+			return locale(Locale.forLanguageTag(locale));
+		}
+
 		/**
 		 * (OPTIONAL)
 		 * If this reference is set when the request is sent, it will be included in the callbacks.

src/main/java/com/vonage/client/verify2/VerificationRequest.java

@@ -22,10 +22,11 @@
 import static org.junit.jupiter.api.Assertions.*;
 import java.util.Arrays;
 import java.util.Collections;
+import java.util.Locale;
 
 public class VerificationRequestTest {
 	static final boolean SANDBOX = true;
-	static final Locale LOCALE = Locale.PORTUGUESE_PORTUGAL;
+	static final Locale LOCALE = Locale.forLanguageTag("pt-pt");
 	static final int CODE_LENGTH = 8, CHANNEL_TIMEOUT = 120;
 	static final String
 			BRAND = "Vonage",
@@ -309,6 +310,14 @@ public void testSilentAuthMustBeFirstWorkflow() {
 		assertThrows(IllegalStateException.class, builder::build);
 	}
 
+	@Test
+	public void testInvalidLocale() throws Exception {
+		VerificationRequest.Builder builder = getBuilderRequiredParamsSingleWorkflow(Channel.SMS);
+		assertThrows(IllegalArgumentException.class, () -> builder.locale("--++").build());
+		assertThrows(IllegalArgumentException.class, () -> builder.locale("en_GB").build());
+		assertNotNull(builder.locale("ab-cd").build().getLocale());
+	}
+
 	@Test
 	public void triggerJsonProcessingException() {
 		class SelfRefrencing extends VerificationRequest {

src/test/java/com/vonage/client/verify2/VerificationRequestTest.java

@@ -61,7 +61,7 @@ VerificationRequest newVerificationRequestWithAllParamsAndWorkflows() {
 				.brand("Nexmo").fraudCheck(false)
 				.code("ab2c3de5").codeLength(8)
 				.channelTimeout(500)
-				.locale(Locale.GERMAN_GERMANY)
+				.locale("de-de")
 				.clientRef("callback-ref0x1")
 				.workflows(workflows).build();
 	}
@@ -106,14 +106,14 @@ protected String expectedEndpointUri(VerificationRequest request) {
 			@Override
 			protected VerificationRequest sampleRequest() {
 				return VerificationRequest.builder()
-						.clientRef("my-personal-reference").locale(Locale.ENGLISH_UK)
+						.clientRef("my-personal-reference").locale("ar-XA")
 						.addWorkflow(new SmsWorkflow("447700900001", "FA+9qCX9VSu"))
 						.brand("ACME, Inc").codeLength(6).channelTimeout(320).build();
 			}
 
 			@Override
 			protected String sampleRequestBodyString() {
-				return "{\"locale\":\"en-gb\",\"channel_timeout\":320,\"code_length\":6," +
+				return "{\"locale\":\"ar-xa\",\"channel_timeout\":320,\"code_length\":6," +
 						"\"brand\":\"ACME, Inc\",\"client_ref\":\"my-personal-reference\",\"workflow\":" +
 						"[{\"channel\":\"sms\",\"to\":\"447700900001\",\"app_hash\":\"FA+9qCX9VSu\"}]}";
 			}