Further refactoring & documentation

CHANGELOG.md

@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - 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`

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/AppEndpoint.java

@@ -29,6 +29,11 @@ public class AppEndpoint extends JsonableBaseObject implements Endpoint {
     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,9 @@ public class CallEvent extends JsonableBaseObject {
     private CallStatus status;
     private CallDirection direction;
 
+    @Deprecated
+    public 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.

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

@@ -24,24 +24,15 @@
  * CallInfo holds the information related to a call. It is obtained using {@link VoiceClient#listCalls()}.
  */
 public class CallInfo extends JsonableBaseObject {
-    Endpoint from, to;
-    String conversationUuid, uuid, network, price, rate;
-    CallDirection direction;
-    Integer duration;
-    Date startTime, endTime;
-    CallStatus status;
+    private Endpoint from, to;
+    private String conversationUuid, uuid, network, price, rate;
+    private CallDirection direction;
+    private Integer duration;
+    private Date startTime, endTime;
+    private CallStatus status;
 
     CallInfo() {}
 
-    CallInfo(String to, String from) {
-        this(new PhoneEndpoint(to), new PhoneEndpoint(from));
-    }
-
-    CallInfo(Endpoint to, Endpoint from) {
-        this.to = to;
-        this.from = from;
-    }
-
     @JsonProperty("to")
     public Endpoint getTo() {
         return to;

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

@@ -26,6 +26,9 @@ public class CallInfoPage extends JsonableBaseObject implements Iterable<CallInf
     private PageLinks links;
     private EmbeddedCalls embedded;
 
+    @Deprecated
+    public CallInfoPage() {}
+
     @JsonProperty("count")
     public int getCount() {
         return count;
@@ -62,7 +65,10 @@ public Iterator<CallInfo> iterator() {
      * @param json The JSON string to parse.
      *
      * @return An instance of this class with the fields populated, if present.
+     *
+     * @deprecated This will be removed in a future release.
      */
+    @Deprecated
     public static CallInfoPage fromJson(String json) {
         return Jsonable.fromJson(json);
     }

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

@@ -30,6 +30,11 @@ public enum CallOrder {
         this.callOrder = callOrder;
     }
 
+    /**
+     * Converts this enum into its string value.
+     *
+     * @return The call order as a string.
+     */
     public String getCallOrder() {
         return callOrder;
     }

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

@@ -262,7 +262,7 @@ public Builder recordIndex(Integer recordIndex) {
          */
         @Deprecated
         public Builder order(CallOrder order) {
-            return order != null ? order(SortOrder.fromString(order.name())) : this;
+            return order != null ? order(SortOrder.fromString(order.getCallOrder())) : this;
         }
 
         /**

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

@@ -26,6 +26,9 @@
 public class DtmfResponse extends JsonableBaseObject {
     private String uuid, message;
 
+    @Deprecated
+    public DtmfResponse() {}
+
     /**
      * Unique identifier for the call leg DTMF was sent to.
      *

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

@@ -25,6 +25,9 @@ public class DtmfResult extends JsonableBaseObject {
     private String digits;
     private boolean timedOut;
 
+    @Deprecated
+    public DtmfResult() {}
+
     /**
      * The button sequence pressed by the user.
      *

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

@@ -21,7 +21,7 @@
 /**
  * Enum representing call modification actions.
  */
-public enum ModifyCallAction {
+enum ModifyCallAction {
     HANGUP, MUTE, UNMUTE, EARMUFF, UNEARMUFF, TRANSFER, UNKNOWN;
 
     @JsonValue

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

@@ -20,15 +20,29 @@
 import com.vonage.client.JsonableBaseObject;
 import java.util.Objects;
 
+/**
+ * Wrapper for call modification requests.
+ */
 class ModifyCallPayload extends JsonableBaseObject {
     @JsonIgnore final String uuid;
     private final ModifyCallAction action;
 
+    /**
+     * Create a new ModifyCallPayload.
+     *
+     * @param action The action to perform as an enum.
+     * @param uuid The call ID to modify.
+     */
     ModifyCallPayload(ModifyCallAction action, String uuid) {
         this.action = Objects.requireNonNull(action, "Action is required.");
         this.uuid = Objects.requireNonNull(uuid, "callId is required.");
     }
 
+    /**
+     * Call modification action.
+     *
+     * @return The action as an enum.
+     */
     @JsonProperty("action")
     public ModifyCallAction getAction() {
         return action;

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

@@ -18,6 +18,12 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.vonage.client.JsonableBaseObject;
 
+/**
+ * Represents the link to a page in the response from the API.
+ *
+ * @deprecated {@link PageLinks} will be replaced with {@link com.vonage.client.common.HalLinks} in the future.
+ */
+@Deprecated
 public class PageLink extends JsonableBaseObject {
     private String href;
 

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

@@ -19,6 +19,8 @@
 import com.vonage.client.JsonableBaseObject;
 
 /**
+ * Represents the {@code _links} section in a paginated response.
+ *
  * @deprecated Will be replaced by {@link com.vonage.client.common.HalLinks} in a future release.
  */
 @Deprecated

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

@@ -24,6 +24,10 @@
  * @since 8.9.0
  */
 public enum SipHeader {
+    /**
+     * Used to submit user-to-user information if supported by the vendor, as per
+     * <a href="https://datatracker.ietf.org/doc/html/rfc7433">RFC 7433</a>.
+     */
     USER_TO_USER;
 
     @JsonValue

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

@@ -24,9 +24,24 @@
  * @since 8.2.0
  */
 public enum SpeechTimeoutReason {
+    /**
+     * Input ended when user stopped speaking.
+     */
     END_ON_SILENCE_TIMEOUT,
+
+    /**
+     * Maximum duration was reached.
+     */
     MAX_DURATION,
+
+    /**
+     * User didn't say anything.
+     */
     START_TIMEOUT,
+
+    /**
+     * Unknown reason.
+     */
     UNKNOWN;
 
     @JsonValue
@@ -35,6 +50,13 @@ public String toString() {
         return name().toLowerCase();
     }
 
+    /**
+     * Convert a string to a SpeechTimeoutReason enum.
+     *
+     * @param name The speech timeout reason as a string.
+     *
+     * @return The speech timeout reason as an enum, or {@link #UNKNOWN} if an invalid value was provided.
+     */
     @JsonCreator
     public static SpeechTimeoutReason fromString(String name) {
         try {

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

@@ -26,6 +26,8 @@
 public class StreamResponse extends JsonableBaseObject {
     private String uuid, message;
 
+    public StreamResponse() {}
+
     /**
      * UUID of the call to which the message was sent.
      *
@@ -52,7 +54,10 @@ public String getMessage() {
      * @param json The JSON string to parse.
      *
      * @return An instance of this class with the fields populated, if present.
+     *
+     * @deprecated This will be removed in a future release.
      */
+    @Deprecated
     public static StreamResponse fromJson(String json) {
         return Jsonable.fromJson(json);
     }