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.
@@ -74,6 +77,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

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

@@ -21,82 +21,139 @@
 import java.util.Date;
 
 /**
- * CallInfo holds the information related to a call. It is obtained using {@link VoiceClient#listCalls()}.
+ * 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;
-    }
-
+    /**
+     * Call destination.
+     *
+     * @return The call recipient endpoint.
+     */
     @JsonProperty("to")
     public Endpoint getTo() {
         return to;
     }
 
+    /**
+     * Call source.
+     *
+     * @return The caller endpoint.
+     */
     @JsonProperty("from")
     public Endpoint getFrom() {
         return from;
     }
 
+    /**
+     * ID of the call.
+     *
+     * @return The call ID as a string.
+     */
     @JsonProperty("uuid")
     public String getUuid() {
         return uuid;
     }
 
+    /**
+     * ID of the conversation.
+     *
+     * @return The conversation ID as a string.
+     */
     @JsonProperty("conversation_uuid")
     public String getConversationUuid() {
         return conversationUuid;
     }
 
+    /**
+     * Time elapsed for the call to take place in seconds.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The call duration in seconds as an integer, or {@code null} if unknown.
+     */
     @JsonProperty("duration")
     public Integer getDuration() {
         return duration;
     }
 
+    /**
+     * Start time of the call.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The start time of the call as a {@link Date} object, or {@code null} if unknown.
+     */
+    @JsonProperty("start_time")
+    public Date getStartTime() {
+        return this.startTime;
+    }
+
+    /**
+     * End time of the call.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The end time of the call as a {@link Date} object, or {@code null} if unknown.
+     */
     @JsonProperty("end_time")
     public Date getEndTime() {
         return endTime;
     }
 
+    /**
+     * Total price charged for this call.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The call total cost as a string, or {@code null} if unknown.
+     */
     @JsonProperty("price")
     public String getPrice() {
         return price;
     }
 
+    /**
+     * Price per minute for this call.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The per-minute call rate as a string, or {@code null} if unknown.
+     */
     @JsonProperty("rate")
     public String getRate() {
         return rate;
     }
 
-    @JsonProperty("start_time")
-    public Date getStartTime() {
-        return this.startTime;
-    }
-
+    /**
+     * Status of the call.
+     *
+     * @return The call status as an enum.
+     */
     @JsonProperty("status")
     public CallStatus getStatus() {
         return status;
     }
 
+    /**
+     * Direction of the call: either inbound or outbound.
+     *
+     * @return The call direction as an enum.
+     */
     @JsonProperty("direction")
     public CallDirection getDirection() {
         return direction;
     }
 
+    /**
+     * The Mobile Country Code Mobile Network Code (MCCMNC) for the carrier network used to make this call.
+     * This is only present if {@linkplain #getStatus()} is {@linkplain CallStatus#COMPLETED}.
+     *
+     * @return The MCCMNC as a string, or {@code null} if unknown.
+     */
     @JsonProperty("network")
     public String getNetwork() {
         return network;
@@ -118,7 +175,10 @@ public String toString() {
      * @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)}. This will be removed in a future release.
      */
+    @Deprecated
     public static CallInfo fromJson(String json) {
         return Jsonable.fromJson(json);
     }