WIP: Improve Numbers documentation

CHANGELOG.md

@@ -6,6 +6,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Added `targetApiKey` for buy & cancel number endpoints
 - Added Builder for `UpdateNumberRequest` and deprecated setters
 - Added `app_id` property to `UpdateNumberRequest` (replaces `messagesCallbackValue`)
+- Deprecated setters in Numbers API
 
 # [8.9.4] - 2024-07-25
 - Fixed UUID validation in `ConversationAction.Builder#canHear` and `canSpeak`

src/main/java/com/vonage/client/numbers/AvailableNumber.java

@@ -15,8 +15,11 @@
  */
 package com.vonage.client.numbers;
 
+/**
+ * Represents a number that is available to buy.
+ */
 public class AvailableNumber extends JsonableNumber {
-    private Double cost;
+    private String cost;
 
     /**
      * Constructor.
@@ -26,32 +29,17 @@ public class AvailableNumber extends JsonableNumber {
     @Deprecated
     public AvailableNumber() {}
 
+    /**
+     * The monthly rental cost for this number, in Euros.
+     *
+     * @return The rental cost as a string.
+     */
     public String getCost() {
-        return cost != null ? cost.toString() : null;
-    }
-
-    @Deprecated
-    public void setCountry(String country) {
-        this.country = country;
-    }
-
-    @Deprecated
-    public void setMsisdn(String msisdn) {
-        this.msisdn = msisdn;
+        return cost;
     }
 
     @Deprecated
     public void setCost(String cost) {
         this.cost = cost;
     }
-
-    @Deprecated
-    public void setType(String type) {
-        this.type = type;
-    }
-
-    @Deprecated
-    public void setFeatures(String[] features) {
-        this.features = Feature.setFromString(features);
-    }
 }

src/main/java/com/vonage/client/numbers/BaseNumberRequest.java

@@ -20,6 +20,11 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * Base class for number management queries.
+ *
+ * @since 8.10.0
+ */
 abstract class BaseNumberRequest implements QueryParamsRequest {
     private final String country, msisdn;
 

src/main/java/com/vonage/client/numbers/BuyCancelNumberRequest.java

@@ -17,6 +17,12 @@
 
 import java.util.Map;
 
+/**
+ * Base class for {@linkplain NumbersClient#buyNumber(String, String, String)} and
+ * {@linkplain NumbersClient#cancelNumber(String, String, String)} method request parameters.
+ *
+ * @since 8.10.0
+ */
 class BuyCancelNumberRequest extends BaseNumberRequest {
     private final String targetApiKey;
 

src/main/java/com/vonage/client/numbers/JsonableNumber.java

@@ -45,10 +45,20 @@ public String getMsisdn() {
         return msisdn;
     }
 
+    /**
+     * Type of number as a string. In a future release, this will be an enum.
+     *
+     * @return The type of number as a string.
+     */
     public String getType() {
         return type != null ? type.toString() : null;
     }
 
+    /**
+     * Capabilities of the number as an array of strings. In a future release, these will be enums.
+     *
+     * @return The number's capabilities as a string array.
+     */
     public String[] getFeatures() {
         return Feature.getToString(features);
     }

src/main/java/com/vonage/client/numbers/ListNumbersFilter.java

@@ -18,17 +18,35 @@
 import com.vonage.client.QueryParamsRequest;
 import java.util.LinkedHashMap;
 import java.util.Map;
+import java.util.Objects;
 
+/**
+ * Filter criteria used in {@link NumbersClient#listNumbers(ListNumbersFilter)}.
+ */
 public class ListNumbersFilter implements QueryParamsRequest {
     private Integer index, size;
     private String pattern;
     private SearchPattern searchPattern;
     private Type type;
 
+    private ListNumbersFilter(Builder builder) {
+        if ((index = builder.index) != null && index < 1) {
+            throw new IllegalArgumentException("'index' must be positive.");
+        }
+        if ((size = builder.size) != null && (size < 1 || size > 100)) {
+            throw new IllegalArgumentException("'size' must be between 1 and 100.");
+        }
+        pattern = builder.pattern;
+        searchPattern = builder.searchPattern;
+        type = builder.type;
+    }
+
+    @Deprecated
     public ListNumbersFilter() {
         this(null, null, null, null);
     }
 
+    @Deprecated
     public ListNumbersFilter(
             Integer index,
             Integer size,
@@ -74,7 +92,7 @@ public void setSearchPattern(SearchPattern searchPattern) {
 
     @Override
     public Map<String, String> makeParams() {
-        LinkedHashMap<String, String> params = new LinkedHashMap<>(4);
+        LinkedHashMap<String, String> params = new LinkedHashMap<>(8);
         if (index != null) {
             params.put("index", index.toString());
         }
@@ -90,7 +108,82 @@ public Map<String, String> makeParams() {
         return params;
     }
 
-    public static class Builder {
+    /**
+     * Entrypoint for constructing an instance of this class.
+     *
+     * @return A new Builder.
+     * @since 8.10.0
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder for setting the parameters of ListNumbersFilter.
+     *
+     * @since 8.10.0
+     */
+    public static final class Builder {
+        private Integer index, size;
+        private String pattern;
+        private SearchPattern searchPattern;
+        private Type type;
 
+        private Builder() {}
+
+        /**
+         * TODO description
+         *
+         * @param index The TODO.
+         * @return This builder.
+         */
+        public Builder index(Integer index) {
+            this.index = index;
+            return this;
+        }
+
+        /**
+         * TODO description
+         *
+         * @param size The TODO.
+         * @return This builder.
+         */
+        public Builder size(Integer size) {
+            this.size = size;
+            return this;
+        }
+
+        /**
+         * TODO description
+         *
+         * @param strategy
+         * @param pattern The TODO.
+         * @return This builder.
+         */
+        public Builder pattern(SearchPattern strategy, String pattern) {
+            this.searchPattern = Objects.requireNonNull(strategy, "Matching strategy is required.");
+            this.pattern = Objects.requireNonNull(pattern, "Pattern is required");
+            return this;
+        }
+
+        /**
+         * TODO description
+         *
+         * @param type The TODO.
+         * @return This builder.
+         */
+        public Builder type(Type type) {
+            this.type = type;
+            return this;
+        }
+
+        /**
+         * Builds the ListNumbersFilter request parameters.
+         *
+         * @return A new ListNumbersFilter instance with this builder's properties.
+         */
+        public ListNumbersFilter build() {
+            return new ListNumbersFilter(this);
+        }
     }
 }

src/main/java/com/vonage/client/numbers/ListNumbersResponse.java

@@ -21,25 +21,39 @@
 
 /**
  * Response from a request to list the numbers currently being rented buy an account.
- *
- * @deprecated This will be made package-private in a future release and the return type of
- * {@link NumbersClient#listNumbers(ListNumbersFilter)} will be replaced by {@code List<OwnedNumber>}.
  */
-@Deprecated
 public class ListNumbersResponse extends JsonableBaseObject {
     private int count;
     private OwnedNumber[] numbers;
 
+    /**
+     * Total amount of numbers owned by the account.
+     * Note that this may not be the same as the size of {@linkplain #getNumbers()}.
+     *
+     * @return The total number of owned numbers.
+     */
     @JsonProperty("count")
     public int getCount() {
         return count;
     }
 
+    /**
+     * A paginated array of owned numbers and their details.
+     * Number of results will depend on what you set in {@linkplain ListNumbersFilter#getSize()}.
+     *
+     * @return The owned numbers as an array.
+     */
     @JsonProperty("numbers")
     public OwnedNumber[] getNumbers() {
         return numbers != null ? numbers : new OwnedNumber[0];
     }
 
+    /**
+     * Creates an instance of this class from a JSON payload.
+     *
+     * @param json The JSON string to parse.
+     * @return An instance of this class with all known fields populated from the JSON payload, if present.
+     */
     public static ListNumbersResponse fromJson(String json) {
         return Jsonable.fromJson(json);
     }