API review feedback fixes

sdk/communication/azure-communication-callingserver/README.md

@@ -46,7 +46,7 @@ Based on if the Contoso app join a call or not, APIs can be divided into two cat
 
 
 You can provide the connection string using the connectionString() function of `CallingServerClientBuilder`. Once you initialized a `CallingServerClient` class, you can do the different server calling operations.
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L28-L34 -->
+<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L31-L37 -->
 ```java
 // Your connectionString retrieved from your Azure Communication Service
 String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";
@@ -60,22 +60,21 @@ CallingServerClient callingServerClient = builder.buildClient();
 ### Create call, Add participant and Hangup a call
 
 #### Create a Call: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L46-L66 -->
+<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L49-L68 -->
 ```java
 CommunicationIdentifier source = new CommunicationUserIdentifier("<acs-user-identity>");
 CommunicationIdentifier firstCallee = new CommunicationUserIdentifier("<acs-user-identity-1>");
 CommunicationIdentifier secondCallee = new CommunicationUserIdentifier("<acs-user-identity-2>");
 
-CommunicationIdentifier[] targets = new CommunicationIdentifier[] { firstCallee, secondCallee };
+List<CommunicationIdentifier> targets = Arrays.asList(firstCallee, secondCallee);
 
 String callbackUri = "<callback-uri-for-notification>";
 
-MediaType[] requestedMediaTypes = new MediaType[] { MediaType.AUDIO, MediaType.VIDEO };
+List<MediaType> requestedMediaTypes = Arrays.asList(MediaType.AUDIO, MediaType.VIDEO);
 
-EventSubscriptionType[] requestedCallEvents = new EventSubscriptionType[] {
+List<EventSubscriptionType> requestedCallEvents = Arrays.asList(
     EventSubscriptionType.DTMF_RECEIVED,
-    EventSubscriptionType.PARTICIPANTS_UPDATED
-};
+    EventSubscriptionType.PARTICIPANTS_UPDATED);
 
 CreateCallOptions createCallOptions = new CreateCallOptions(
     callbackUri,
@@ -86,14 +85,14 @@ CallConnection callConnection = callingServerClient.createCallConnection(source,
 ```
 
 #### Add a participant to a Call:
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L86-L87 -->
+<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L88-L89 -->
 ```java
 CommunicationIdentifier thirdCallee = new CommunicationUserIdentifier("<acs-user-identity-3>");
 callConnection.addParticipant(thirdCallee, "ACS User 3", "<string-for-tracing-responses>");
 ```
 
 #### Hangup a Call:
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L76-L76 -->
+<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L78-L78 -->
 ```java
 callConnection.hangup();
 ```
@@ -134,6 +133,16 @@ serverCall.stopRecording(recordingId);
 CallRecordingStateResult callRecordingStateResult = serverCall.getRecordingState(recordingId);
 ```
 
+#### Download a Recording into a file:
+<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L100-L100 -->
+```java
+callingServerClient.downloadTo(
+            recordingUrl,
+            Paths.get(filePath),
+            null,
+            true
+        );
+```
 ### Play Audio in Call
 
 #### Play Audio: 

sdk/communication/azure-communication-callingserver/pom.xml

@@ -124,7 +124,7 @@
     </dependency>
   </dependencies>
   <build>
-    <plugins>
+      <plugins>
       <plugin>
         <groupId>org.jacoco</groupId>
         <artifactId>jacoco-maven-plugin</artifactId>
@@ -134,6 +134,15 @@
             <include>com/azure/communication/callingserver/*.class</include>
           </includes>
         </configuration>
+        <executions>
+          <execution>
+            <id>coverage-report</id>
+            <phase>verify</phase>
+            <goals>
+              <goal>report</goal>
+            </goals>
+          </execution>
+        </executions>
       </plugin>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
@@ -149,6 +158,22 @@
           </rules>
         </configuration>
       </plugin>
+      <plugin>
+        <groupId>org.revapi</groupId>
+        <artifactId>revapi-maven-plugin</artifactId>
+        <version>0.11.2</version> <!-- {x-version-update;org.revapi:revapi-maven-plugin;external_dependency} -->
+        <configuration>
+          <analysisConfiguration>
+            <revapi.ignore>
+              <item>
+                <code>java.method.added</code>
+                <class>com.azure.core.util.HttpClientOptions</class>
+                <justification>Transitive from Core. Not our problem</justification>
+              </item>
+            </revapi.ignore>
+          </analysisConfiguration>
+        </configuration>
+      </plugin>
     </plugins>
   </build>
 </project>

sdk/communication/azure-communication-callingserver/src/main/java/com/azure/communication/callingserver/CallConnection.java

@@ -4,6 +4,7 @@
 package com.azure.communication.callingserver;
 
 import com.azure.communication.callingserver.models.AddParticipantResult;
+import com.azure.communication.callingserver.models.CallingServerErrorException;
 import com.azure.communication.callingserver.models.CancelAllMediaOperationsResult;
 import com.azure.communication.callingserver.models.PlayAudioOptions;
 import com.azure.communication.callingserver.models.PlayAudioResult;
@@ -45,6 +46,8 @@ public String getCallConnectionId() {
      * @param callbackUri call back uri to receive notifications.
      * @param operationContext The value to identify context of the operation. This is used to co-relate other
      *                         communications related to this operation
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return the response payload for play audio operation.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -65,46 +68,15 @@ public PlayAudioResult playAudio(
      *                     audio prompts are supported. More specifically, the audio content in the wave file must
      *                     be mono (single-channel), 16-bit samples with a 16,000 (16KHz) sampling rate.
      * @param playAudioOptions Options for play audio.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return the response payload for play audio operation.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public PlayAudioResult playAudio(String audioFileUri, PlayAudioOptions playAudioOptions) {
         return callConnectionAsync.playAudioInternal(audioFileUri, playAudioOptions).block();
     }
 
-    /**
-     * Play audio in a call.
-     *
-     * @param audioFileUri The media resource uri of the play audio request. Currently only Wave file (.wav) format
-     *                     audio prompts are supported. More specifically, the audio content in the wave file must
-     *                     be mono (single-channel), 16-bit samples with a 16,000 (16KHz) sampling rate.
-     * @param loop The flag indicating whether audio file needs to be played in loop or not.
-     * @param audioFileId An id for the media in the AudioFileUri, using which we cache the media.
-     * @param callbackUri call back uri to receive notifications.
-     * @param operationContext The value to identify context of the operation. This is used to co-relate other
-     *                         communications related to this operation
-     * @param context A {@link Context} representing the request context.
-     * @return the response payload for play audio operation.
-     */
-    @ServiceMethod(returns = ReturnType.SINGLE)
-    public Response<PlayAudioResult> playAudioWithResponse(
-        String audioFileUri,
-        boolean loop,
-        String audioFileId,
-        String callbackUri,
-        String operationContext,
-        final Context context) {
-        return callConnectionAsync
-            .playAudioWithResponseInternal(
-                audioFileUri,
-                loop,
-                audioFileId,
-                callbackUri,
-                operationContext,
-                context)
-            .block();
-    }
-
     /**
      * Play audio in a call.
      *
@@ -113,6 +85,8 @@ public Response<PlayAudioResult> playAudioWithResponse(
      *                     be mono (single-channel), 16-bit samples with a 16,000 (16KHz) sampling rate.
      * @param playAudioOptions Options for play audio.
      * @param context A {@link Context} representing the request context.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return the response payload for play audio operation.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -127,6 +101,9 @@ public Response<PlayAudioResult> playAudioWithResponse(
 
     /**
      * Disconnect the current caller in a group-call or end a p2p-call.
+     *
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public void hangup() {
@@ -137,6 +114,8 @@ public void hangup() {
      * Disconnect the current caller in a group-call or end a p2p-call.
      *
      * @param context A {@link Context} representing the request context.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful hangup request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -149,6 +128,8 @@ public Response<Void> hangupWithResponse(final Context context) {
      *
      * @param operationContext The value to identify context of the operation. This is used to co-relate other
      *                         communications related to this operation
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful cancel all media operations request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -162,6 +143,8 @@ public CancelAllMediaOperationsResult cancelAllMediaOperations(String operationC
      * @param operationContext The value to identify context of the operation. This is used to co-relate other
      *                         communications related to this operation
      * @param context A {@link Context} representing the request context.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful cancel all media operations request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -178,6 +161,8 @@ public Response<CancelAllMediaOperationsResult> cancelAllMediaOperationsWithResp
      * @param alternateCallerId The phone number to use when adding a phone number participant.
      * @param operationContext The value to identify context of the operation. This is used to co-relate other
      *                         communications related to this operation
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful add participant request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -196,6 +181,8 @@ public AddParticipantResult addParticipant(
      * @param operationContext The value to identify context of the operation. This is used to co-relate other
      *                         communications related to this operation
      * @param context A {@link Context} representing the request context.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful add participant request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
@@ -212,6 +199,8 @@ public Response<AddParticipantResult> addParticipantWithResponse(
      * Remove a participant from the call.
      *
      * @param participantId Participant id.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public void removeParticipant(String participantId) {
@@ -223,6 +212,8 @@ public void removeParticipant(String participantId) {
      *
      * @param participantId Participant id.
      * @param context A {@link Context} representing the request context.
+     * @throws CallingServerErrorException thrown if the request is rejected by server.
+     * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return response for a successful remove participant request.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)