Update Communication Libraries to New Codesnippet Tooling (Azure#25411)

Update Communication Libraries to New Codesnippet Tooling
XiaofeiCao · Nov 18, 2021 · 0c60fd0 · 0c60fd0
1 parent 06dad3a
commit 0c60fd0
Show file tree

Hide file tree

Showing 34 changed files with 532 additions and 200 deletions.
diff --git a/sdk/communication/azure-communication-callingserver/README.md b/sdk/communication/azure-communication-callingserver/README.md
@@ -46,8 +46,8 @@ 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#L33-L39 -->
-```java
+
+```java readme-sample-createCallingServerClient
 // Your connectionString retrieved from your Azure Communication Service
 String connectionString = "endpoint=https://<resource-name>.communication.azure.com/;accesskey=<access-key>";
 
@@ -59,8 +59,8 @@ CallingServerClient callingServerClient = builder.buildClient();
 
 Alternatively, calling clients can also be authenticated using a valid token credential. With this option,
 `AZURE_CLIENT_SECRET`, `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` environment variables need to be set up for authentication. 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSample.java#L117-128 -->
-```java
+
+```java readme-sample-createCallingServerClientWithTokenCredential
 // Your endpoint retrieved from your Azure Communication Service
 String endpoint = "https://<resource-name>.communication.azure.com";
 
@@ -78,8 +78,8 @@ CallingServerClient callingServerClient  = new CallingServerClientBuilder()
 ### Create call, Add participant and Hangup a call
 
 #### Create a Call: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L51-L70 -->
-```java
+
+```java readme-sample-createCallConnection
 CommunicationIdentifier source = new CommunicationUserIdentifier("<acs-user-identity>");
 CommunicationIdentifier firstCallee = new CommunicationUserIdentifier("<acs-user-identity-1>");
 CommunicationIdentifier secondCallee = new CommunicationUserIdentifier("<acs-user-identity-2>");
@@ -103,74 +103,75 @@ CallConnection callConnection = callingServerClient.createCallConnection(source,
 ```
 
 #### Add a participant to a Call:
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L90-L91 -->
-```java
+
+```java readme-sample-addParticipant
 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#L80-L80 -->
-```java
+
+```java readme-sample-hangupCallConnection
 callConnection.hangup();
 ```
 
 ### Start, Pause, Resume, Stop and Get a recording
 
 #### Start a Recording: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L49-L53 -->
-```java
+
+```java readme-sample-startRecording
 String serverCallId = "<serverCallId received from starting call>";
 String recordingStateCallbackUri = "<webhook endpoint to which calling service can report status>";
 ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
-StartCallRecordingResponse response = serverCall.startRecording(recordingStateCallbackUri);
-String recordingId = response.getRecordingId();
+StartCallRecordingResult result = serverCall.startRecording(recordingStateCallbackUri);
+String recordingId = result.getRecordingId();
 ```
 
 #### Pause a Recording: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L67-L67 -->
-```java
+
+```java readme-sample-pauseRecording
 serverCall.pauseRecording(recordingId);
 ```
 
 #### Resume a Recording: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L80-L80 -->
-```java
+
+```java readme-sample-resumeRecording
 serverCall.resumeRecording(recordingId);
 ```
 
 #### Stop a Recording: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L93-L93 -->
-```java
+
+```java readme-sample-stopRecording
 serverCall.stopRecording(recordingId);
 ```
 
 #### Get the Recording State: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L107-L107 -->
-```java
-CallRecordingStateResult callRecordingStateResult = serverCall.getRecordingState(recordingId);
+
+```java readme-sample-getRecordingState
+CallRecordingState callRecordingState = callRecordingStateResult.getRecordingState();
 ```
 
 #### Download a Recording into a file:
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ReadmeSamples.java#L102-L102 -->
-```java
+
+```java readme-sample-getRecordingStream
 callingServerClient.downloadTo(
-            recordingUrl,
-            Paths.get(filePath),
-            null,
-            true
-        );
+    recordingUrl,
+    Paths.get(filePath),
+    null,
+    true
+);
 ```
 ### Play Audio in Call
 
 #### Play Audio: 
-<!-- embedme src/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java#L124-L129 -->
-```java
+
+```java readme-sample-playAudio
 String audioFileUri = "<uri of the file to play>";
 String audioFileId = "<a name to use for caching the audio file>";
 String callbackUri = "<webhook endpoint to which calling service can report status>";
 String context = "<Identifier for correlating responses>";
-PlayAudioResponse playAudioResponse = serverCall.playAudio(audioFileUri, audioFileId, callbackUri, context);
+ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
+PlayAudioResult playAudioResult = serverCall.playAudio(audioFileUri, audioFileId, callbackUri, context);
 ```
 
 ## Troubleshooting

diff --git a/sdk/communication/azure-communication-callingserver/pom.xml b/sdk/communication/azure-communication-callingserver/pom.xml
@@ -47,6 +47,9 @@
     <javaModulesSurefireArgLine>
       --add-opens com.azure.communication.callingserver/com.azure.communication.callingserver.implementation=ALL-UNNAMED
     </javaModulesSurefireArgLine>
+    <codesnippet.skip>false</codesnippet.skip>
+    <javadocDoclet></javadocDoclet>
+    <javadocDocletOptions></javadocDocletOptions>
   </properties>
 
   <dependencies>

diff --git a/...gserver/src/main/java/com/azure/communication/callingserver/CallingServerAsyncClient.java b/...gserver/src/main/java/com/azure/communication/callingserver/CallingServerAsyncClient.java
@@ -49,7 +49,18 @@
  *
  * <p><strong>Instantiating a asynchronous CallingServer client</strong></p>
  *
- * {@codesnippet com.azure.communication.callingserver.CallingServerAsyncClient.pipeline.instantiation}
+ * <!-- src_embed com.azure.communication.callingserver.CallingServerAsyncClient.pipeline.instantiation -->
+ * <pre>
+ * HttpPipeline pipeline = new HttpPipelineBuilder&#40;&#41;
+ *     .policies&#40;&#47;* add policies *&#47;&#41;
+ *     .build&#40;&#41;;
+ *
+ * CallingServerAsyncClient callingServerAsyncClient = new CallingServerClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .connectionString&#40;connectionString&#41;
+ *     .buildAsyncClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.communication.callingserver.CallingServerAsyncClient.pipeline.instantiation -->
  *
  * <p>View {@link CallingServerClientBuilder this} for additional ways to construct the client.</p>
  *
@@ -81,7 +92,21 @@ public final class CallingServerAsyncClient {
      * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return Response for a successful CreateCallConnection request.
      *
-     * {@codesnippet com.azure.communication.callingserver.CallingServerAsyncClient.create.call.connection.async}
+     * <!-- src_embed com.azure.communication.callingserver.CallingServerAsyncClient.create.call.connection.async -->
+     * <pre>
+     * List&lt;CommunicationIdentifier&gt; targets = Arrays.asList&#40;firstCallee, secondCallee&#41;;
+     * List&lt;MediaType&gt; requestedMediaTypes = Arrays.asList&#40;MediaType.AUDIO, MediaType.VIDEO&#41;;
+     * List&lt;EventSubscriptionType&gt; requestedCallEvents = Arrays.asList&#40;
+     *     EventSubscriptionType.DTMF_RECEIVED,
+     *     EventSubscriptionType.PARTICIPANTS_UPDATED&#41;;
+     * CreateCallOptions createCallOptions = new CreateCallOptions&#40;
+     *     callbackUri,
+     *     requestedMediaTypes,
+     *     requestedCallEvents&#41;;
+     * CallConnectionAsync callAsyncConnection = callingServerAsyncClient
+     *     .createCallConnection&#40;source, targets, createCallOptions&#41;.block&#40;&#41;;
+     * </pre>
+     * <!-- end com.azure.communication.callingserver.CallingServerAsyncClient.create.call.connection.async -->
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<CallConnectionAsync> createCallConnection(

diff --git a/...allingserver/src/main/java/com/azure/communication/callingserver/CallingServerClient.java b/...allingserver/src/main/java/com/azure/communication/callingserver/CallingServerClient.java
@@ -26,7 +26,18 @@
  *
  * <p><strong>Instantiating a synchronous Calling Server Client</strong></p>
  *
- * {@codesnippet com.azure.communication.callingserver.CallingServerClient.pipeline.instantiation}
+ * <!-- src_embed com.azure.communication.callingserver.CallingServerClient.pipeline.instantiation -->
+ * <pre>
+ * HttpPipeline pipeline = new HttpPipelineBuilder&#40;&#41;
+ *     .policies&#40;&#47;* add policies *&#47;&#41;
+ *     .build&#40;&#41;;
+ *
+ * CallingServerClient callingServerClient = new CallingServerClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .connectionString&#40;connectionString&#41;
+ *     .buildClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.communication.callingserver.CallingServerClient.pipeline.instantiation -->
  *
  * <p>View {@link CallingServerClientBuilder this} for additional ways to construct the client.</p>
  *
@@ -50,7 +61,20 @@ public final class CallingServerClient {
      * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent.
      * @return Response for a successful CreateCallConnection request.
      *
-     * {@codesnippet com.azure.communication.callingserver.CallingServerClient.create.call.connection}
+     * <!-- src_embed com.azure.communication.callingserver.CallingServerClient.create.call.connection -->
+     * <pre>
+     * List&lt;CommunicationIdentifier&gt; targets = Arrays.asList&#40;firstCallee, secondCallee&#41;;
+     * List&lt;MediaType&gt; requestedMediaTypes = Arrays.asList&#40;MediaType.AUDIO, MediaType.VIDEO&#41;;
+     * List&lt;EventSubscriptionType&gt; requestedCallEvents = Arrays.asList&#40;
+     *     EventSubscriptionType.DTMF_RECEIVED,
+     *     EventSubscriptionType.PARTICIPANTS_UPDATED&#41;;
+     * CreateCallOptions createCallOptions = new CreateCallOptions&#40;
+     *     callbackUri,
+     *     requestedMediaTypes,
+     *     requestedCallEvents&#41;;
+     * CallConnection callConnection = callingServerClient.createCallConnection&#40;source, targets, createCallOptions&#41;;
+     * </pre>
+     * <!-- end com.azure.communication.callingserver.CallingServerClient.create.call.connection -->
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public CallConnection createCallConnection(

diff --git a/...erver/src/main/java/com/azure/communication/callingserver/CallingServerClientBuilder.java b/...erver/src/main/java/com/azure/communication/callingserver/CallingServerClientBuilder.java
@@ -42,7 +42,23 @@
  *
  * <p><strong>Instantiating synchronous and asynchronous Calling Server Clients</strong></p>
  *
- * {@codesnippet com.azure.communication.callingserver.CallingServerClientBuilder.pipeline.instantiation}
+ * <!-- src_embed com.azure.communication.callingserver.CallingServerClientBuilder.pipeline.instantiation -->
+ * <pre>
+ * HttpPipeline pipeline = new HttpPipelineBuilder&#40;&#41;
+ *     .policies&#40;&#47;* add policies *&#47;&#41;
+ *     .build&#40;&#41;;
+ *
+ * CallingServerClient callingServerClient = new CallingServerClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .connectionString&#40;connectionString&#41;
+ *     .buildClient&#40;&#41;;
+ *
+ * CallingServerAsyncClient callingServerAsyncClient = new CallingServerClientBuilder&#40;&#41;
+ *     .pipeline&#40;pipeline&#41;
+ *     .connectionString&#40;connectionString&#41;
+ *     .buildAsyncClient&#40;&#41;;
+ * </pre>
+ * <!-- end com.azure.communication.callingserver.CallingServerClientBuilder.pipeline.instantiation -->
  */
 @ServiceClientBuilder(serviceClients = { CallingServerClient.class, CallingServerAsyncClient.class })
 public final class CallingServerClientBuilder {

diff --git a/...rver/src/main/java/com/azure/communication/callingserver/CallingServerServiceVersion.java b/...rver/src/main/java/com/azure/communication/callingserver/CallingServerServiceVersion.java
@@ -9,6 +9,9 @@
  * Versions of CallingServer service supported by this client library.
  */
 public enum CallingServerServiceVersion implements ServiceVersion {
+    /**
+     * Service version {@code 2021-08-30-preview}.
+     */
     V2021_08_30_PREVIEW("2021-08-30-preview");
 
     private final String version;

diff --git a/...c/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java b/...c/samples/java/com/azure/communication/callingserver/ConversationClientReadmeSamples.java
@@ -44,11 +44,14 @@ public CallingServerClient createCallingServerClient() {
      * @return recordingId to use with other recording operations.
      */
     public String startRecording(CallingServerClient callingServerClient) {
+        // BEGIN: readme-sample-startRecording
         String serverCallId = "<serverCallId received from starting call>";
         String recordingStateCallbackUri = "<webhook endpoint to which calling service can report status>";
         ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
         StartCallRecordingResult result = serverCall.startRecording(recordingStateCallbackUri);
         String recordingId = result.getRecordingId();
+        // END: readme-sample-startRecording
+
         return recordingId;
     }
 
@@ -62,7 +65,10 @@ public String startRecording(CallingServerClient callingServerClient) {
     public void pauseRecording(CallingServerClient callingServerClient,
                                String serverCallId, String recordingId) {
         ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
+
+        // BEGIN: readme-sample-pauseRecording
         serverCall.pauseRecording(recordingId);
+        // END: readme-sample-pauseRecording
     }
 
     /**
@@ -75,7 +81,10 @@ public void pauseRecording(CallingServerClient callingServerClient,
     public void resumeRecording(CallingServerClient callingServerClient,
                                 String serverCallId, String recordingId) {
         ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
+
+        // BEGIN: readme-sample-resumeRecording
         serverCall.resumeRecording(recordingId);
+        // END: readme-sample-resumeRecording
     }
 
     /**
@@ -88,7 +97,10 @@ public void resumeRecording(CallingServerClient callingServerClient,
     public void stopRecording(CallingServerClient callingServerClient,
                               String serverCallId, String recordingId) {
         ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
+
+        // BEGIN: readme-sample-stopRecording
         serverCall.stopRecording(recordingId);
+        // END: readme-sample-stopRecording
     }
 
     /**
@@ -107,7 +119,9 @@ public CallRecordingState getRecordingState(CallingServerClient callingServerCli
         // CallRecordingState: Active, Inactive
         // If the call has ended, CommunicationErrorException will be thrown. Inactive is
         // only returned when the recording is paused.
+        // BEGIN: readme-sample-getRecordingState
         CallRecordingState callRecordingState = callRecordingStateResult.getRecordingState();
+        // END: readme-sample-getRecordingState
         return callRecordingState;
     }
 
@@ -119,12 +133,15 @@ public CallRecordingState getRecordingState(CallingServerClient callingServerCli
      * @return information about the play audio request, {@link PlayAudioResult}.
      */
     public PlayAudioResult playAudio(CallingServerClient callingServerClient, String serverCallId) {
+        // BEGIN: readme-sample-playAudio
         String audioFileUri = "<uri of the file to play>";
         String audioFileId = "<a name to use for caching the audio file>";
         String callbackUri = "<webhook endpoint to which calling service can report status>";
         String context = "<Identifier for correlating responses>";
         ServerCall serverCall = callingServerClient.initializeServerCall(serverCallId);
         PlayAudioResult playAudioResult = serverCall.playAudio(audioFileUri, audioFileId, callbackUri, context);
+        // END: readme-sample-playAudio
+
         return playAudioResult;
     }
 }