docs: Improve SMS API javadocs (#558)

Also refactors BinaryMessage to remove commons-codec dependency

.github/workflows/scorecard.yml

@@ -12,23 +12,18 @@ on:
   schedule:
     - cron: '16 23 * * 2'
   push:
-    branches: [ 'main' ]
+    branches:
+      - main
 
-# Declare default permissions as read only.
 permissions: read-all
 
 jobs:
   analysis:
     name: Scorecard analysis
     runs-on: ubuntu-latest
     permissions:
-      # Needed to upload the results to code-scanning dashboard.
       security-events: write
-      # Needed to publish results and get a badge (see publish_results below).
       id-token: write
-      # Uncomment the permissions below if installing in a private repository.
-      # contents: read
-      # actions: read
 
     steps:
       - name: Checkout code
@@ -47,13 +42,6 @@ jobs:
           # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
           # repo_token: ${{ secrets.SCORECARD_TOKEN }}
 
-          # Public repositories:
-          #   - Publish results to OpenSSF REST API for easy access by consumers
-          #   - Allows the repository to include the Scorecard badge.
-          #   - See https://github.com/ossf/scorecard-action#publishing-results.
-          # For private repositories:
-          #   - `publish_results` will always be set to `false`, regardless
-          #     of the value entered here.
           publish_results: true
 
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF

pom.xml

@@ -76,11 +76,6 @@
       <artifactId>commons-lang3</artifactId>
       <version>3.17.0</version>
     </dependency>
-    <dependency>
-      <groupId>commons-codec</groupId>
-      <artifactId>commons-codec</artifactId>
-      <version>1.17.1</version>
-    </dependency>
 
     <!-- Tests -->
     <dependency>
@@ -101,6 +96,12 @@
       <version>4.0.4</version>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>commons-codec</groupId>
+      <artifactId>commons-codec</artifactId>
+      <version>1.17.2</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>io.jsonwebtoken</groupId>
       <artifactId>jjwt-api</artifactId>

src/main/java/com/vonage/client/sms/MessageStatus.java

@@ -27,6 +27,7 @@
  * <a href=https://developer.vonage.com/api-errors/sms>the documentation</a> for more details.
  */
 public enum MessageStatus {
+
     /**
      * A status of zero does not indicate that Vonage delivered your message. Instead, this
      * status indicates the absence of an error - i.e. the REST call succeeded.
@@ -193,6 +194,11 @@ public static MessageStatus fromInt(int messageStatus) {
         this.messageStatus = messageStatus;
     }
 
+    /**
+     * Gets the message status as an int.
+     *
+     * @return The message status code.
+     */
     @JsonValue
     public int getMessageStatus() {
         return messageStatus;

src/main/java/com/vonage/client/sms/MessageType.java

@@ -26,6 +26,13 @@
 public enum MessageType {
     TEXT, UNICODE, BINARY, UNKNOWN;
 
+    /**
+     * Convert a string value to a MessageType enum.
+     *
+     * @param name The string value to convert.
+     *
+     * @return The message type as an enum.
+     */
     @JsonCreator
     public static MessageType fromString(String name) {
         try {

src/main/java/com/vonage/client/sms/SmsClient.java

@@ -17,7 +17,6 @@
 
 import com.vonage.client.*;
 import com.vonage.client.auth.ApiKeyHeaderAuthMethod;
-import com.vonage.client.auth.ApiKeyQueryParamsAuthMethod;
 import com.vonage.client.auth.SignatureAuthMethod;
 import com.vonage.client.common.HttpMethod;
 import com.vonage.client.sms.messages.Message;

src/main/java/com/vonage/client/sms/SmsSubmissionResponse.java

@@ -20,11 +20,19 @@
 import com.vonage.client.JsonableBaseObject;
 import java.util.List;
 
+/**
+ * Represents the response from the SMS API when a request is made to submit a message.
+ * Since a message may be split into multiple parts, the response metadata for each individual SMS
+ * can be retrieved from the {@link #getMessages()} method, which returns a list of
+ * {@link SmsSubmissionResponseMessage} for each corresponding message that was submitted.
+ */
 public class SmsSubmissionResponse extends JsonableBaseObject {
     private int messageCount;
     private List<SmsSubmissionResponseMessage> messages;
 
     /**
+     * Default constructor.
+     *
      * @deprecated This will be made private in the next major release.
      */
     @Deprecated

src/main/java/com/vonage/client/sms/SmsSubmissionResponseMessage.java

@@ -19,88 +19,112 @@
 import com.vonage.client.JsonableBaseObject;
 import java.math.BigDecimal;
 
+/**
+ * Represents the API response for a single SMS submission.
+ */
 public class SmsSubmissionResponseMessage extends JsonableBaseObject {
     private MessageStatus status;
     private String to, id, network, errorText, clientRef, accountRef;
     private BigDecimal remainingBalance, messagePrice;
 
     /**
-     * @return The number the message was sent to. Numbers are specified in E.164 format.
+     * The number the message was sent to.
+     *
+     * @return The receiving number in E.164 format.
      */
     @JsonProperty("to")
     public String getTo() {
         return to;
     }
 
     /**
-     * @return The ID of the message.
+     * ID of the message.
+     *
+     * @return The message ID as a string.
      */
     @JsonProperty("message-id")
     public String getId() {
         return id;
     }
 
     /**
-     * @return The status of the message. A non-zero code (i.e. anything that isn't
-     * {@link MessageStatus#OK} indicates an error. See
-     * <a href=https://developer.vonage.com/messaging/sms/guides/troubleshooting-sms>Troubleshooting Failed SMS</a>.
+     * Status of the message. A non-zero code (i.e. anything that isn't {@link MessageStatus#OK}) indicates an
+     * error. See <a href=https://developer.vonage.com/messaging/sms/guides/troubleshooting-sms>
+     * Troubleshooting Failed SMS</a> for more details.
+     *
+     * @return The message status as an enum.
      */
     @JsonProperty("status")
     public MessageStatus getStatus() {
         return status;
     }
 
     /**
-     * @return The description of the error, if present.
+     * Error description, if present.
+     *
+     * @return The description of the error, or {@code null} if not applicable.
      */
     @JsonProperty("error-text")
     public String getErrorText() {
         return errorText;
     }
 
     /**
-     * @return Your estimated remaining balance.
+     * Estimated account remaining balance.
+     *
+     * @return The remaining balance as a {@link BigDecimal}.
      */
     @JsonProperty("remaining-balance")
     public BigDecimal getRemainingBalance() {
         return remainingBalance;
     }
 
     /**
-     * @return The estimated cost of the message.
+     * Estimated cost of the message.
+     *
+     * @return The message price as a {@link BigDecimal}.
      */
     @JsonProperty("message-price")
     public BigDecimal getMessagePrice() {
         return messagePrice;
     }
 
     /**
-     * @return The estimated ID of the network of the recipient.
+     * Estimated ID of the network of the recipient.
+     *
+     * @return The recipient's network ID as a string, or {@code null} if unknown.
      */
     @JsonProperty("network")
     public String getNetwork() {
         return network;
     }
 
     /**
-     * @return If a client-ref was included when sending the SMS,
-     * this field will be included and hold the value that was sent.
+     * If a client-ref was included when sending the SMS, this field will be the value that was sent.
+     *
+     * @return The reference associated with the message as a string, or {@code null} if there wasn't one set.
      */
     @JsonProperty("client-ref")
     public String getClientRef() {
         return clientRef;
     }
 
     /**
-     * This is an advanced feature and requires activation via a support request before it can be used.
+     * Account reference. An optional string used to identify separate accounts using the SMS endpoint for billing
+     * purposes. This is an advanced feature and requires activation via a support request before it can be used.
      *
-     * @return An optional string used to identify separate accounts using the SMS endpoint for billing purposes.
+     * @return The account reference, or {@code null} if not applicable.
      */
     @JsonProperty("account-ref")
     public String getAccountRef() {
         return accountRef;
     }
 
+    /**
+     * Convenience method for checking if the message status indicates a temporary error.
+     *
+     * @return {@code true} if the status is a temporary error, {@code false} otherwise.
+     */
     public boolean isTemporaryError() {
         return status == MessageStatus.INTERNAL_ERROR || status == MessageStatus.TOO_MANY_BINDS
                 || status == MessageStatus.THROTTLED;

src/main/java/com/vonage/client/sms/messages/BinaryMessage.java

@@ -15,7 +15,7 @@
  */
 package com.vonage.client.sms.messages;
 
-import org.apache.commons.codec.binary.Hex;
+import java.util.Formatter;
 import java.util.Map;
 
 /**
@@ -26,7 +26,7 @@ public class BinaryMessage extends Message {
     private int protocolId = 0;
 
     /**
-     * Instantiate a new binary sms message request.
+     * Instantiate a new binary SMS message request.
      *
      * @param from              the 'from' address that will be seen on the handset when this message arrives,
      *                          typically either a valid short-code / long code that can be replied to, or a short text description of the application sending the message (Max 11 chars)
@@ -51,42 +51,63 @@ public BinaryMessage(final String from,
     }
 
     /**
-     * @return byte[] The raw binary message data to be sent to a handset.
-     * This api, and the Vonage sms service will send this data 'as-is' (in conjunction with the binary UDH) and will not make any corrections.
-     * so you should ensure that it is a correctly constructed message
+     * The raw binary message data to be sent to a handset. The Vonage SMS service will send this data 'as-is'
+     * (in conjunction with the binary UDH) and will not make any corrections, so you should ensure that it is correct.
+     *
+     * @return The message body as a byte array.
      */
     public byte[] getMessageBody() {
         return messageBody == null ? null : messageBody.clone();
     }
 
     /**
-     * @return byte[] Most binary content will require a UserDataHeader portion of the message containing commands to enable the handset to interpret the binary data
-     * (for example, a binary ringtone, a wap-push, OverTheAir configuration, etc.).
-     * Additionally, if you are sending a long text message as multiple concatenated messages and are performing this operation manually rather than
-     * using the automated long sms handling in the Vonage sms service, then you will need to construct and include here an appropriate
-     * UserDataHeader field that describes the segmentation/re-assembly fields required to successfully concatenate multiple short messages.
+     * Most binary content will require a UserDataHeader portion of the message containing commands to enable the
+     * handset to interpret the binary data (for example, a binary ringtone, a WAP-push, OverTheAir configuration, etc.).
+     * Additionally, if you are sending a long text message as multiple concatenated messages and are performing this
+     * operation manually rather than using the automated long sms handling in the Vonage SMS service, then you will
+     * need to construct and include here an appropriate UserDataHeader field that describes the segmentation /
+     * re-assembly fields required to successfully concatenate multiple short messages.
+     *
+     * @return The User Data Header as a byte array.
      */
     public byte[] getUdh() {
         return udh == null ? null : udh.clone();
     }
 
     /**
-     * @return Integer The value of the GSM Protocol ID field to be submitted with this message. Ordinarily this should be left as the default value of 0
+     * The value of the GSM Protocol ID field to be submitted with this message.
+     * Ordinarily this should be left as the default value of 0.
+     *
+     * @return The protocol ID.
      */
     public int getProtocolId() {
         return protocolId;
     }
 
+    /**
+     * Sets the protocol ID for this message.
+     *
+     * @param protocolId The protocol ID.
+     */
     public void setProtocolId(int protocolId) {
         this.protocolId = protocolId;
     }
 
     @Override
     public Map<String, String> makeParams() {
         Map<String, String> params = super.makeParams();
-        params.put("udh", Hex.encodeHexString(getUdh()));
-        params.put("body", Hex.encodeHexString(getMessageBody()));
+        params.put("udh", toHexString(getUdh()));
+        params.put("body", toHexString(getMessageBody()));
         params.put("protocol-id", Integer.toString(getProtocolId()));
         return params;
     }
+
+    private static String toHexString(byte[] data) {
+        StringBuilder sb = new StringBuilder(data.length * 2);
+        Formatter formatter = new Formatter(sb);
+        for (byte b : data) {
+            formatter.format("%02x", b);
+        }
+        return sb.toString();
+    }
 }