docs: Tidy up Voice API Javadocs & refactoring / deprecations (#568)

* Tidy up Voice API Javadocs

* refactor:CallsFilter extends HalFilterRequest

* Further refactoring & documentation

* 100% Voice coverage again

* Bump JUnit version

* Package-private no-args constructors

CHANGELOG.md

@@ -2,8 +2,15 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-# [8.17.0] - 2025-02-2?
+# [8.17.0] - 2025-02-28
 - Added user/domain name support to `com.vonage.client.voice.ncco.SipEndpoint`
+- Improved Voice API documentation
+- Deprecated primitive wrapper methods in NCCO action builders
+- Deprecated singleton URL / Endpoint array/collection methods in Voice API
+- Refactored `com.vonage.client.voice.CallsFilter` to extend `HalFilterRequest`
+  - Deprecated `java.util.Date`-based methods
+  - `getOrder()` returns a `com.vonage.client.common.SortOrder` instead of `CallOrder`
+- Made constructors for response objects in Voice API package-private
 
 # [8.16.2] - 2025-02-05
 - Added `disconnected_by` enum to `com.vonage.client.voice.EventWebhook`

pom.xml

@@ -86,7 +86,7 @@
     <dependency>
       <groupId>org.junit.jupiter</groupId>
       <artifactId>junit-jupiter-engine</artifactId>
-      <version>5.11.4</version>
+      <version>5.12.0</version>
       <scope>test</scope>
     </dependency>
     <dependency>

src/main/java/com/vonage/client/common/HalFilterRequest.java

@@ -17,6 +17,7 @@
 
 import com.vonage.client.QueryParamsRequest;
 import java.time.Instant;
+import java.time.format.DateTimeFormatter;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
@@ -66,21 +67,26 @@ protected HalFilterRequest(Integer page, Integer pageSize, SortOrder order) {
 	@Override
 	public Map<String, String> makeParams() {
 		Map<String, String> params = new LinkedHashMap<>();
-		if (cursor != null) {
-			params.put("cursor", cursor);
-		}
-		if (page != null) {
-			params.put("page", page.toString());
-		}
-		if (pageSize != null) {
-			params.put("page_size", pageSize.toString());
-		}
-		if (order != null) {
-			params.put("order", order.toString());
-		}
+		conditionalAdd(params, "cursor", cursor);
+		conditionalAdd(params, "page", page);
+		conditionalAdd(params, "page_size", pageSize);
+		conditionalAdd(params, "order", order);
 		return params;
 	}
 
+	protected static void conditionalAdd(Map<String, String> params, String name, Object value) {
+		if (value != null) {
+			String valueStr;
+			if (value instanceof Instant) {
+				valueStr = DateTimeFormatter.ISO_INSTANT.format((Instant) value);
+			}
+			else {
+				valueStr = value.toString();
+			}
+			params.put(name, valueStr);
+		}
+	}
+
 	/**
 	 * Page number to navigate to in the response.
 	 *
@@ -171,7 +177,7 @@ protected B page(int page) {
 		/**
 		 * Number of results per page.
 		 *
-		 * @param pageSize he page size as an int.
+		 * @param pageSize The page size as an int.
 		 *
 		 * @return This builder.
 		 */

src/main/java/com/vonage/client/conversations/AbstractConversationsFilterRequest.java

@@ -29,6 +29,10 @@ protected AbstractConversationsFilterRequest(Builder<
         super(builder);
     }
 
+    protected String formatTimestamp(Instant time) {
+        return time != null ? time.toString().replace('T', ' ').replace("Z", "") : null;
+    }
+
     @Override
     protected Integer validatePageSize(Integer pageSize) {
         if (pageSize != null && (pageSize < 1 || pageSize > 100)) {
@@ -37,12 +41,6 @@ protected Integer validatePageSize(Integer pageSize) {
         return pageSize;
     }
 
-    protected String formatTimestamp(Instant time) {
-        return time.toString()
-                .replace('T', ' ')
-                .replace("Z", "");
-    }
-
     @Override
     public String getCursor() {
         return super.getCursor();
@@ -51,12 +49,8 @@ public String getCursor() {
     @Override
     public Map<String, String> makeParams() {
         Map<String, String> params = super.makeParams();
-        if (startDate != null) {
-            params.put("date_start", formatTimestamp(startDate));
-        }
-        if (endDate != null) {
-            params.put("date_end", formatTimestamp(endDate));
-        }
+        conditionalAdd(params, "date_start", formatTimestamp(startDate));
+        conditionalAdd(params, "date_end", formatTimestamp(endDate));
         return params;
     }
 

src/main/java/com/vonage/client/conversations/ListEventsRequest.java

@@ -36,18 +36,10 @@ public class ListEventsRequest extends AbstractConversationsFilterRequest {
 	@Override
 	public Map<String, String> makeParams() {
 		Map<String, String> params = super.makeParams();
-		if (excludeDeletedEvents != null) {
-            params.put("exclude_deleted_events", excludeDeletedEvents.toString());
-        }
-		if (startId != null) {
-            params.put("start_id", String.valueOf(startId));
-        }
-		if (endId != null) {
-            params.put("end_id", String.valueOf(endId));
-        }
-		if (eventType != null) {
-            params.put("event_type", eventType.toString());
-        }
+		conditionalAdd(params, "exclude_deleted_events", excludeDeletedEvents);
+		conditionalAdd(params, "start_id", startId);
+		conditionalAdd(params, "end_id", endId);
+		conditionalAdd(params, "event_type", eventType);
 		return params;
 	}
 

src/main/java/com/vonage/client/conversations/ListUserConversationsRequest.java

@@ -36,15 +36,9 @@ public final class ListUserConversationsRequest extends AbstractListUserRequest
 	@Override
 	public Map<String, String> makeParams() {
 		Map<String, String> params = super.makeParams();
-		if (state != null) {
-            params.put("state", state.toString());
-        }
-		if (orderBy != null) {
-            params.put("order_by", orderBy.toString());
-        }
-		if (includeCustomData != null) {
-            params.put("include_custom_data", includeCustomData.toString());
-        }
+		conditionalAdd(params, "state", state);
+		conditionalAdd(params, "order_by", orderBy);
+		conditionalAdd(params, "include_custom_data", includeCustomData);
 		return params;
 	}
 

src/main/java/com/vonage/client/meetings/ListRoomsRequest.java

@@ -34,12 +34,8 @@ class ListRoomsRequest extends HalFilterRequest {
 	@Override
 	public Map<String, String> makeParams() {
 		Map<String, String> params = super.makeParams();
-		if (startId != null) {
-			params.put("start_id", String.valueOf(startId));
-		}
-		if (endId != null) {
-			params.put("end_id", String.valueOf(endId));
-		}
+		conditionalAdd(params, "start_id", startId);
+		conditionalAdd(params, "end_id", endId);
 		return params;
 	}
 }

src/main/java/com/vonage/client/voice/AddDtmfListenerRequest.java

@@ -22,10 +22,21 @@
 import java.util.Collection;
 import java.util.Collections;
 
+/**
+ * Request wrapper for {@linkplain VoiceClient#addDtmfListener(String, String)}.
+ *
+ * @since 8.12.0
+ */
 class AddDtmfListenerRequest extends JsonableBaseObject {
     @JsonIgnore final String uuid;
     @JsonProperty("event_url") final Collection<URI> eventUrl;
 
+    /**
+     * Creates a new DTMF listener request.
+     *
+     * @param uuid ID of the call to add the DTMF listener to.
+     * @param eventUrl URL to send the DTMF events to.
+     */
     public AddDtmfListenerRequest(String uuid, URI eventUrl) {
         this.uuid = uuid;
         this.eventUrl = Collections.singletonList(eventUrl);

src/main/java/com/vonage/client/voice/AdvancedMachineDetection.java

@@ -70,6 +70,9 @@ public String toString() {
 	private Mode mode;
 	private Integer beepTimeout;
 
+	/**
+	 * Constructor used reflectively by Jackson for instantiation.
+	 */
 	AdvancedMachineDetection() {}
 
 	AdvancedMachineDetection(Builder builder) {

src/main/java/com/vonage/client/voice/AppEndpoint.java

@@ -26,9 +26,16 @@
 public class AppEndpoint extends JsonableBaseObject implements Endpoint {
     private String user;
 
-    protected AppEndpoint() {
-    }
+    /**
+     * Constructor used reflectively by Jackson for instantiation.
+     */
+    protected AppEndpoint() {}
 
+    /**
+     * Create an AppEndpoint with the given user.
+     *
+     * @param user The username.
+     */
     public AppEndpoint(String user) {
         this.user = user;
     }

src/main/java/com/vonage/client/voice/Call.java

@@ -79,26 +79,74 @@ else if ((fromRandomNumber = builder.fromRandomNumber) != null && fromRandomNumb
 
     Call() {}
 
+    /**
+     * Create a new Call with {@linkplain PhoneEndpoint} as the recipient and caller.
+     *
+     * @param to The recipient phone number.
+     * @param from The caller phone number.
+     * @param answerUrl The URL to fetch the NCCO from.
+     */
     public Call(String to, String from, String answerUrl) {
         this(new PhoneEndpoint(to), new PhoneEndpoint(from), answerUrl);
     }
 
+    /**
+     * Create a new Call with the specified recipient and caller endpoints.
+     *
+     * @param to The recipient endpoint.
+     * @param from The caller endpoint.
+     * @param answerUrl The URL to fetch the NCCO from.
+     */
     public Call(Endpoint to, Endpoint from, String answerUrl) {
         this(new Endpoint[]{to}, from, answerUrl);
     }
 
+    /**
+     * Create a new Call with {@linkplain PhoneEndpoint} as the recipient and caller.
+     *
+     * @param to The recipient phone number.
+     * @param from The caller phone number.
+     * @param ncco The NCCO actions to take.
+     */
     public Call(String to, String from, Collection<? extends Action> ncco) {
         this(new PhoneEndpoint(to), new PhoneEndpoint(from), ncco);
     }
 
+    /**
+     * Create a new Call with the specified recipient and caller endpoints.
+     *
+     * @param to The recipient endpoint.
+     * @param from The caller endpoint.
+     * @param ncco The NCCO actions to take.
+     */
     public Call(Endpoint to, Endpoint from, Collection<? extends Action> ncco) {
         this(new Endpoint[]{to}, from, ncco);
     }
 
+    /**
+     * Create a new Call.
+     *
+     * @param to The recipient endpoint in an array.
+     * @param from The caller endpoint.
+     * @param answerUrl The URL to fetch the NCCO from.
+     *
+     * @deprecated This will be removed in the next major release.
+     */
+    @Deprecated
     public Call(Endpoint[] to, Endpoint from, String answerUrl) {
         this(builder().to(to).from(from).answerUrl(answerUrl));
     }
 
+    /**
+     * Create a new Call.
+     *
+     * @param to The recipient endpoint in an array.
+     * @param from The caller endpoint.
+     * @param ncco The NCCO actions to take.
+     *
+     * @deprecated This will be removed in the next major release.
+     */
+    @Deprecated
     public Call(Endpoint[] to, Endpoint from, Collection<? extends Action> ncco) {
         this(builder().to(to).from(from).ncco(ncco));
     }

src/main/java/com/vonage/client/voice/CallDirection.java

@@ -18,9 +18,23 @@
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonValue;
 
+/**
+ * Represents the direction of a call.
+ */
 public enum CallDirection {
+    /**
+     * Outgoing call.
+     */
     OUTBOUND,
+
+    /**
+     * Incoming call.
+     */
     INBOUND,
+
+    /**
+     * Unknown call direction.
+     */
     UNKNOWN;
 
     @JsonValue
@@ -29,6 +43,13 @@ public String toString() {
         return name().toLowerCase();
     }
 
+    /**
+     * Convert a string to a CallDirection enum.
+     *
+     * @param name The call direction as a string.
+     *
+     * @return The call direction as an enum, or {@link #UNKNOWN} if an invalid value was provided.
+     */
     @JsonCreator
     public static CallDirection fromString(String name) {
         try {

src/main/java/com/vonage/client/voice/CallEvent.java

@@ -27,6 +27,11 @@ public class CallEvent extends JsonableBaseObject {
     private CallStatus status;
     private CallDirection direction;
 
+    /**
+     * Constructor used reflectively by Jackson for instantiation.
+     */
+    CallEvent() {}
+
     /**
      * The unique identifier for this call leg. The UUID is created when your call request is accepted by Vonage.
      * You use the UUID in all requests for individual live calls.
@@ -74,6 +79,7 @@ public CallDirection getDirection() {
      * @param json The JSON string to parse.
      *
      * @return An instance of this class with the fields populated, if present.
+     *
      * @deprecated Use {@link Jsonable#fromJson(String, Class)}.
      */
     @Deprecated