SWI-5869 BXML Library Updates (#151)

* move @params to avoid warnings hopefully

* bxml formatting changes

* add wf dispatch to test wf

* not only on main

* fix javadoc warnings

* formatting

* on main only

Author: ckoegel

.github/workflows/test-pr.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - main
+  workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref }}

src/main/java/com/bandwidth/sdk/model/bxml/Bridge.java

@@ -31,31 +31,30 @@
 @Builder
 @Getter
 @EqualsAndHashCode
+/**
+ *
+ *   @param targetCallId (str): String containing the callId of the call to be bridged.
+ *   @param bridgeCompleteUrl (str, optional): URL to send the Bridge Complete event to and request new BXML.
+ *        If this attribute is specified, then Verbs following the <Bridge> verb will be ignored and the BXML returned in this webhook is executed on the call.
+ *        If this attribute is not specified then no webhook will be sent, and execution of the verbs following the <Bridge> verb continues. May be a relative URL. Defaults to None.
+ *   @param bridgeCompleteMethod (str, optional): The HTTP method to use for the request to bridgeCompleteUrl. GET or POST. Default value is POST.
+ *   @param bridgeCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Bridge Complete webhook delivery in case bridgeCompleteUrl fails to respond. Defaults to None.
+ *   @param bridgeCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Bridge Complete webhook to bridgeCompleteFallbackUrl. GET or POST. Default value is POST.
+ *   @param bridgeTargetCompleteUrl (str, optional):URL to send the Bridge Target Complete event to and request new BXML.
+ *        If this attribute is specified, then the BXML returned in this webhook is executed on the target call.
+ *        If this attribute is not specified then no webhook will be sent, and the target call will be hung up. May be a relative URL. Defaults to None.
+ *   @param bridgeTargetCompleteMethod (str, optional): The HTTP method to use for the request to bridgeTargetCompleteUrl. GET or POST. Default value is POST.
+ *   @param bridgeTargetCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Bridge Target Complete webhook delivery in case bridgeTargetCompleteUrl fails to respond. Defaults to None.
+ *   @param bridgeTargetCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Bridge Target Complete webhook to bridgeTargetCompleteFallbackUrl. GET or POST. Default value is POST.
+ *   @param username (str, optional): The username to send in the HTTP request to bridgeCompleteUrl and to bridgeTargetCompleteUrl. Defaults to None.
+ *   @param password (str, optional): The password to send in the HTTP request to bridgeCompleteUrl and to bridgeTargetCompleteUrl. Defaults to None.
+ *   @param fallbackUsername (str, optional): The username to send in the HTTP request to bridgeCompleteFallbackUrl and to bridgeTargetCompleteFallbackUrl. Defaults to None.
+ *   @param fallbackPassword (str, optional): The password to send in the HTTP request to bridgeCompleteFallbackUrl and to bridgeTargetCompleteFallbackUrl. Defaults to None.
+ *   @param tag (str, optional): A custom string that will be sent with the bridgeComplete webhook and all future webhooks of the call unless overwritten by a future tag attribute or <Tag> verb, or cleared. May be cleared by setting tag="". Max length 256 characters. Defaults to None.
+ *
+ */
 public class Bridge implements Verb {
 
-    /**
-     *
-     *   @param targetCallId (str): String containing the callId of the call to be bridged.
-     *   @param bridgeCompleteUrl (str, optional): URL to send the Bridge Complete event to and request new BXML.
-     *        If this attribute is specified, then Verbs following the <Bridge> verb will be ignored and the BXML returned in this webhook is executed on the call.
-     *        If this attribute is not specified then no webhook will be sent, and execution of the verbs following the <Bridge> verb continues. May be a relative URL. Defaults to None.
-     *   @param bridgeCompleteMethod (str, optional): The HTTP method to use for the request to bridgeCompleteUrl. GET or POST. Default value is POST.
-     *   @param bridgeCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Bridge Complete webhook delivery in case bridgeCompleteUrl fails to respond. Defaults to None.
-     *   @param bridgeCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Bridge Complete webhook to bridgeCompleteFallbackUrl. GET or POST. Default value is POST.
-     *   @param bridgeTargetCompleteUrl (str, optional):URL to send the Bridge Target Complete event to and request new BXML.
-     *        If this attribute is specified, then the BXML returned in this webhook is executed on the target call.
-     *        If this attribute is not specified then no webhook will be sent, and the target call will be hung up. May be a relative URL. Defaults to None.
-     *   @param bridgeTargetCompleteMethod (str, optional): The HTTP method to use for the request to bridgeTargetCompleteUrl. GET or POST. Default value is POST.
-     *   @param bridgeTargetCompleteFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the Bridge Target Complete webhook delivery in case bridgeTargetCompleteUrl fails to respond. Defaults to None.
-     *   @param bridgeTargetCompleteFallbackMethod (str, optional): The HTTP method to use to deliver the Bridge Target Complete webhook to bridgeTargetCompleteFallbackUrl. GET or POST. Default value is POST.
-     *   @param username (str, optional): The username to send in the HTTP request to bridgeCompleteUrl and to bridgeTargetCompleteUrl. Defaults to None.
-     *   @param password (str, optional): The password to send in the HTTP request to bridgeCompleteUrl and to bridgeTargetCompleteUrl. Defaults to None.
-     *   @param fallbackUsername (str, optional): The username to send in the HTTP request to bridgeCompleteFallbackUrl and to bridgeTargetCompleteFallbackUrl. Defaults to None.
-     *   @param fallbackPassword (str, optional): The password to send in the HTTP request to bridgeCompleteFallbackUrl and to bridgeTargetCompleteFallbackUrl. Defaults to None.
-     *   @param tag (str, optional): A custom string that will be sent with the bridgeComplete webhook and all future webhooks of the call unless overwritten by a future tag attribute or <Tag> verb, or cleared. May be cleared by setting tag="". Max length 256 characters. Defaults to None.
-     * 
-    */
-
     public static final String TYPE_NAME = "Bridge";
 
     @XmlValue

src/main/java/com/bandwidth/sdk/model/bxml/Bxml.java

@@ -1,6 +1,6 @@
 /**
  * The root {@code <Bxml>} verb. Other verbs get added to BXML and then the JAXB marshaller using the toBxml() method converts this to valid BXML.
- * 
+ *
  */
 
 package com.bandwidth.sdk.model.bxml;

src/main/java/com/bandwidth/sdk/model/bxml/Conference.java

@@ -1,7 +1,7 @@
 /**
  * The {@code <Conference>} verb is used to join the current call into a conference.
- * Conference names are created and specified by your application. Conferences are implicitly created the first time your application uses a conference name, 
- * and they are implicitly deleted when the last member leaves the conference. We will create a unique ID for the conference, 
+ * Conference names are created and specified by your application. Conferences are implicitly created the first time your application uses a conference name,
+ * and they are implicitly deleted when the last member leaves the conference. We will create a unique ID for the conference,
  * so your conference names can be whatever you want. If the conference ends and then you later use the same conference name, a new unique ID will be created.
  */
 
@@ -32,38 +32,37 @@
 @Builder
 @Getter
 @EqualsAndHashCode
+/**
+ *
+ * @param name (str): The name of the conference. Can contain up to 100 characters of letters, numbers, and the symbols -, _, and .
+ * @param mute (str, optional): A boolean value to indicate whether the member should be on mute in the conference. When muted, a member can hear others speak, but others cannot hear them speak. Defaults to false.
+ * @param hold (str, optional): A boolean value to indicate whether the member should be on hold in the conference. When on hold, a member cannot hear others, and they cannot be heard. Defaults to false.
+ * @param callIdsToCoach (str, optional): A comma-separated list of call ids to coach. When a call joins a conference with this attribute set, it will coach the listed calls.
+ *          Those calls will be able to hear and be heard by the coach, but other calls in the conference will not hear the coach.
+ * @param conferenceEventUrl (str, optional): URL to send Conference events to. The URL, method, username, and password are set by the BXML document that creates the conference,
+ *          and all events related to that conference will be delivered to that same endpoint. If more calls join afterwards and also have this property (or any other webhook related properties like username and password),
+ *          they will be ignored and the original webhook information will be used. This URL may be a relative endpoint.
+ * @param conferenceEventMethod (str, optional): The HTTP method to use for the request to conferenceEventUrl. GET or POST. Default value is POST.
+ * @param conferenceEventFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the conference webhook deliveries in case conferenceEventUrl fails to respond.
+ * @param conferenceEventFallbackMethod (str, optional): The HTTP method to use to deliver the conference webhooks to conferenceEventFallbackUrl. GET or POST. Default value is POST.
+ * @param username (str, optional):The username to send in the HTTP request to conferenceEventUrl.
+ * @param password (str, optional): The password to send in the HTTP request to conferenceEventUrl.
+ * @param fallbackUsername (str, optional): The username to send in the HTTP request to conferenceEventFallbackUrl.
+ * @param fallbackPassword (str, optional): The password to send in the HTTP request to conferenceEventFallbackUrl.
+ * @param tag (str, optional): A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared. May be cleared by setting tag="".
+ *          Max length 256 characters. Defaults to None.
+ * @param callbackTimeout (str, optional): This is the timeout (in seconds) to use when delivering webhooks for the conference.
+ *          If not set, it will inherit the webhook timeout from the call that creates the conference. Can be any numeric value (including decimals) between 1 and 25 * @parameter
+ *         Nested Verbs:
+ * @param     PlayAudio: (optional)
+ * @param     SpeakSentence: (optional)
+ * @param     StartRecording: (optional)
+ * @param     StopRecording: (optional)
+ * @param     PauseRecording: (optional)
+ * @param     ResumeRecording: (optional)
+ */
 public class Conference implements Verb {
 
-    /**
-     *      
-     * @param name (str): The name of the conference. Can contain up to 100 characters of letters, numbers, and the symbols -, _, and .
-     * @param mute (str, optional): A boolean value to indicate whether the member should be on mute in the conference. When muted, a member can hear others speak, but others cannot hear them speak. Defaults to false.
-     * @param hold (str, optional): A boolean value to indicate whether the member should be on hold in the conference. When on hold, a member cannot hear others, and they cannot be heard. Defaults to false.
-     * @param callIdsToCoach (str, optional): A comma-separated list of call ids to coach. When a call joins a conference with this attribute set, it will coach the listed calls.
-     *          Those calls will be able to hear and be heard by the coach, but other calls in the conference will not hear the coach.
-     * @param conferenceEventUrl (str, optional): URL to send Conference events to. The URL, method, username, and password are set by the BXML document that creates the conference,
-     *          and all events related to that conference will be delivered to that same endpoint. If more calls join afterwards and also have this property (or any other webhook related properties like username and password),
-     *          they will be ignored and the original webhook information will be used. This URL may be a relative endpoint.
-     * @param conferenceEventMethod (str, optional): The HTTP method to use for the request to conferenceEventUrl. GET or POST. Default value is POST.
-     * @param conferenceEventFallbackUrl (str, optional): A fallback url which, if provided, will be used to retry the conference webhook deliveries in case conferenceEventUrl fails to respond.
-     * @param conferenceEventFallbackMethod (str, optional): The HTTP method to use to deliver the conference webhooks to conferenceEventFallbackUrl. GET or POST. Default value is POST.
-     * @param username (str, optional):The username to send in the HTTP request to conferenceEventUrl.
-     * @param password (str, optional): The password to send in the HTTP request to conferenceEventUrl.
-     * @param fallbackUsername (str, optional): The username to send in the HTTP request to conferenceEventFallbackUrl.
-     * @param fallbackPassword (str, optional): The password to send in the HTTP request to conferenceEventFallbackUrl.
-     * @param tag (str, optional): A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared. May be cleared by setting tag="".
-     *          Max length 256 characters. Defaults to None.
-     * @param callbackTimeout (str, optional): This is the timeout (in seconds) to use when delivering webhooks for the conference.
-     *          If not set, it will inherit the webhook timeout from the call that creates the conference. Can be any numeric value (including decimals) between 1 and 25 * @parameter 
-     *         Nested Verbs:
-     * @param     PlayAudio: (optional)
-     * @param     SpeakSentence: (optional)
-     * @param     StartRecording: (optional)
-     * @param     StopRecording: (optional)
-     * @param     PauseRecording: (optional)
-     * @param     ResumeRecording: (optional)
-     */
-
     public static final String TYPE_NAME = "Conference";
 
     @XmlValue

src/main/java/com/bandwidth/sdk/model/bxml/CustomParam.java

@@ -1,5 +1,5 @@
 /**
- * The {@code <CustomParam>} verb is used to define optional user specified parameters that will be sent to the destination URL when the real-time transcription is first started. 
+ * The {@code <CustomParam>} verb is used to define optional user specified parameters that will be sent to the destination URL when the real-time transcription is first started.
  * You may specify up to 12 {@code <CustomParam>} elements nested within a {@code <StartTranscription>} tag.
  */
 
@@ -21,13 +21,14 @@
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
+/**
+ *
+ * @param name (str): The name of this parameter, up to 256 characters.
+ * @param value (str): The value of this parameter, up to 2048 characters.
+ *
+ */
 public class CustomParam {
-    /**
-     * 
-     * @param name (str): The name of this parameter, up to 256 characters.
-     * @param value (str): The value of this parameter, up to 2048 characters.
-     *
-     */         
+
     public static final String TYPE_NAME = "CustomParam";
 
     @XmlAttribute

src/main/java/com/bandwidth/sdk/model/bxml/Forward.java

@@ -1,5 +1,5 @@
 /**
- * The {@code <Forward>} verb is used to forward an unanswered incoming call to another number. Unlike {@code <Transfer>}, once your call is forwarded, 
+ * The {@code <Forward>} verb is used to forward an unanswered incoming call to another number. Unlike {@code <Transfer>}, once your call is forwarded,
  * your application will not have any control over either leg of the call. When either leg hangs up, a Disconnect event will be sent to your Call status webhook URL.
  */
 
@@ -26,35 +26,35 @@
 @Builder
 @Getter
 @EqualsAndHashCode
+/**
+ *
+ * @param to (str): The phone number destination of the call.
+ * @param from_ (str, optional): The phone number that the recipient will receive the call from.
+ * @param callTimeout (str, optional): The number of seconds to wait before timing out the call.
+ * @param diversionTreatment (str, optional): Can be any of the following:
+ *     none: No diversion headers are sent on the outbound leg of the transferred call.
+ *     propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg.
+ *     stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call.
+ *     Defaults to none. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call. Defaults to None.
+ * @param diversionReason (str, optional): Can be any of the following values:
+ *     unknown
+ *     user-busy
+ *     no-answer
+ *     unavailable
+ *     unconditional
+ *     time-of-day
+ *     do-not-disturb
+ *     deflection
+ *     follow-me
+ *     out-of-service
+ *     away
+ *     This parameter is considered only when diversionTreatment is set to stack. Defaults is unknown.
+ *     Defaults to None.
+ * @param uui (str, optional): The value of the User-To-User header to send within the outbound INVITE when forwarding to a SIP URI.
+ *     Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed.
+ *     This value, including the encoding specifier, may not exceed 256 characters.
+ */
 public class Forward implements Verb {
-    /**
-     *      
-     * @param to (str): The phone number destination of the call.
-     * @param from_ (str, optional): The phone number that the recipient will receive the call from.
-     * @param callTimeout (str, optional): The number of seconds to wait before timing out the call.
-     * @param diversionTreatment (str, optional): Can be any of the following:
-     *     none: No diversion headers are sent on the outbound leg of the transferred call.
-     *     propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg.
-     *     stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call.
-     *     Defaults to none. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call. Defaults to None.
-     * @param diversionReason (str, optional): Can be any of the following values:
-     *     unknown
-     *     user-busy
-     *     no-answer
-     *     unavailable
-     *     unconditional
-     *     time-of-day
-     *     do-not-disturb
-     *     deflection
-     *     follow-me
-     *     out-of-service
-     *     away
-     *     This parameter is considered only when diversionTreatment is set to stack. Defaults is unknown. 
-     *     Defaults to None.
-     * @param uui (str, optional): The value of the User-To-User header to send within the outbound INVITE when forwarding to a SIP URI. 
-     *     Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed. 
-     *     This value, including the encoding specifier, may not exceed 256 characters.
-     */   
 
     public static final String TYPE_NAME = "Forward";