Form Recognizer builder clients

sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md

@@ -2,20 +2,22 @@
 
 ## 1.0.0-beta.3 (Unreleased)
 - Fix bug in FormRecognizer API's to support multipage document recognition.
+- Add `getFormRecognizerClient()` and `getFormRecognizerAsyncClient()` in FormTrainingClient and FormTrainingAsyncClient
+- Add `FormTrainingClientBuilder` to build `FormTrainingAsyncClient` and `FormTrainingClient`
 - Adopt the `training` namespace for Form Recognizer Training Clients
 - Rename parameter `fileSourceUrl` to `trainingFilesUrl` on `beginTraining` method in FormTrainingClients
 - Rename parameter `useLabelFile` to `useTrainingLabels` on `beginTraining` method in FormTrainingClients
-- Replace parameters `filePrefix` and `includeSubFolders` with `TrainModelOptions` model 
+- Replace parameters `filePrefix` and `includeSubFolders` with `TrainModelOptions` model
 - Rename AccountProperties `count` and `limit` to `customModelCount` and `customModelLimit`
 
 ## 1.0.0-beta.2 (2020-05-06)
 - Fixed Receipt type bug to select the valueString field via fieldValue.
 - Rename `apiKey()` to `credential()` on FormRecognizerClientBuilder.
 
-This package's 
-[documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.2/sdk/formrecognizer/azure-ai-formrecognizer/README.md) 
-and 
-[samples](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.2/sdk/formrecognizer/azure-ai-formrecognizer/src/samples) 
+This package's
+[documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.2/sdk/formrecognizer/azure-ai-formrecognizer/README.md)
+and
+[samples](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.2/sdk/formrecognizer/azure-ai-formrecognizer/src/samples)
 demonstrate the new API.
 
 ## 1.0.0-beta.1 (2020-04-23)
@@ -37,8 +39,8 @@ https://azure.github.io/azure-sdk/releases/latest/java.html.
 - All service errors use the base type: `com.azure.ai.formrecognizer.models.ErrorResponseException`
 - Reactive streams support using [Project Reactor](https://projectreactor.io/).
 
-This package's 
-[documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.1/sdk/formrecognizer/azure-ai-formrecognizer/README.md) 
-and 
-[samples](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.1/sdk/formrecognizer/azure-ai-formrecognizer/src/samples) 
+This package's
+[documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.1/sdk/formrecognizer/azure-ai-formrecognizer/README.md)
+and
+[samples](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-formrecognizer_1.0.0-beta.1/sdk/formrecognizer/azure-ai-formrecognizer/src/samples)
 demonstrate the new API.

sdk/formrecognizer/azure-ai-formrecognizer/README.md

@@ -74,7 +74,7 @@ To use AzureKeyCredential authentication, provide the [key][key] as a string to
 az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>
 ``` 
 Use the API key as the credential parameter to authenticate the client:
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L38-L41 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L39-L42 -->
 ```java
 FormRecognizerClient formRecognizerClient = new FormRecognizerClientBuilder()
     .credential(new AzureKeyCredential("{key}"))
@@ -83,7 +83,7 @@ FormRecognizerClient formRecognizerClient = new FormRecognizerClientBuilder()
 ```
 The Azure Form Recognizer client library provides a way to **rotate the existing API key**.
 
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L48-L54 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L49-L55 -->
 ```java
 AzureKeyCredential credential = new AzureKeyCredential("{key}");
 FormRecognizerClient formRecognizerClient = new FormRecognizerClientBuilder()
@@ -143,7 +143,7 @@ The following section provides several code snippets covering some of the most c
 ### Recognize Forms Using a Custom Model
 Recognize name/value pairs and table data from forms. These models are trained with your own data,
 so they're tailored to your forms. You should only recognize forms of the same form type that the custom model was trained on.
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L58-L74 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L59-L75 -->
 ```java
 String analyzeFilePath = "{file_source_url}";
 String modelId = "{custom_trained_model_id}";
@@ -166,7 +166,7 @@ recognizedForms.forEach(form -> {
 
 ### Recognize Content
 Recognize text and table structures, along with their bounding box coordinates, from documents.
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L78-L98 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L79-L99 -->
 ```java
 String analyzeFilePath = "{file_source_url}";
 SyncPoller<OperationResult, IterableStream<FormPage>> recognizeLayoutPoller =
@@ -193,7 +193,7 @@ layoutPageResults.forEach(formPage -> {
 
 ### Recognize receipts
 Recognize data from a USA sales receipts using a prebuilt model.
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L102-L119 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L103-L120 -->
 ```java
 String receiptSourceUrl = "https://docs.microsoft.com/en-us/azure/cognitive-services/form-recognizer/media"
     + "/contoso-allinone.jpg";
@@ -219,7 +219,7 @@ receiptPageResults.forEach(recognizedReceipt -> {
 Train a machine-learned model on your own form type. The resulting model will be able to recognize values from the types of forms it was trained on.
 Provide a container SAS url to your Azure Storage Blob container where you're storing the training documents. See details on setting this up
 in the [service quickstart documentation][quickstart_training].
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L123-L143 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L124-L144 -->
 ```java
 String trainingFilesUrl = "{training_set_SAS_URL}";
 SyncPoller<OperationResult, CustomFormModel> trainingPoller =
@@ -246,7 +246,7 @@ customFormModel.getSubModels().forEach(customFormSubModel -> {
 
 ### Manage your models
 Manage the custom models attached to your account.
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L147-L176 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L148-L177 -->
 ```java
 AtomicReference<String> modelId = new AtomicReference<>();
 // First, we see how many custom models we have, and what our limit is
@@ -288,7 +288,7 @@ to provide an invalid file source URL an `ErrorResponseException` would be raise
 In the following code snippet, the error is handled 
 gracefully by catching the exception and display the additional information about the error.
 
-<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L183-L187 -->
+<!-- embedme ./src/samples/java/com/azure/ai/formrecognizer/ReadmeSamples.java#L184-L188 -->
 ```java
 try {
     formRecognizerClient.beginRecognizeContentFromUrl("invalidSourceUrl");
@@ -354,8 +354,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 [form_recognizer_account]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows
 [form_recognizer_async_client]: src/main/java/com/azure/ai/formrecognizer/FormRecognizerAsyncClient.java
 [form_recognizer_sync_client]: src/main/java/com/azure/ai/formrecognizer/FormRecognizerClient.java
-[form_training_async_client]: src/main/java/com/azure/ai/formrecognizer/FormTrainingAsyncClient.java
-[form_training_sync_client]: src/main/java/com/azure/ai/formrecognizer/FormTrainingClient.java
+[form_training_async_client]: src/main/java/com/azure/ai/formrecognizer/training/FormTrainingAsyncClient.java
+[form_training_sync_client]: src/main/java/com/azure/ai/formrecognizer/training/FormTrainingClient.java
 [http_clients_wiki]: https://github.com/Azure/azure-sdk-for-java/wiki/HTTP-clients
 [fr_labeling_tool]: https://docs.microsoft.com/en-us/azure/cognitive-services/form-recognizer/quickstarts/label-tool
 [fr_train_without_labels]: https://docs.microsoft.com/en-us/azure/cognitive-services/form-recognizer/overview#train-without-labels

sdk/formrecognizer/azure-ai-formrecognizer/src/main/java/com/azure/ai/formrecognizer/FormRecognizerAsyncClient.java

@@ -15,7 +15,6 @@
 import com.azure.ai.formrecognizer.models.OperationResult;
 import com.azure.ai.formrecognizer.models.RecognizedForm;
 import com.azure.ai.formrecognizer.models.RecognizedReceipt;
-import com.azure.ai.formrecognizer.training.FormTrainingAsyncClient;
 import com.azure.core.annotation.ReturnType;
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
@@ -75,16 +74,6 @@ public final class FormRecognizerAsyncClient {
         this.serviceVersion = serviceVersion;
     }
 
-    /**
-     * Creates a new {@link FormTrainingAsyncClient} object. The new {@code FormTrainingAsyncClient}
-     * uses the same request policy pipeline as the {@code FormRecognizerAsyncClient}.
-     *
-     * @return A new {@link FormTrainingAsyncClient} object.
-     */
-    public FormTrainingAsyncClient getFormTrainingAsyncClient() {
-        return new FormTrainingAsyncClient(this.service, this.serviceVersion);
-    }
-
     /**
      * Gets the service version the client is using.
      *

sdk/formrecognizer/azure-ai-formrecognizer/src/main/java/com/azure/ai/formrecognizer/FormRecognizerClient.java

@@ -9,7 +9,6 @@
 import com.azure.ai.formrecognizer.models.OperationResult;
 import com.azure.ai.formrecognizer.models.RecognizedForm;
 import com.azure.ai.formrecognizer.models.RecognizedReceipt;
-import com.azure.ai.formrecognizer.training.FormTrainingClient;
 import com.azure.core.annotation.ReturnType;
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
@@ -45,16 +44,6 @@ public final class FormRecognizerClient {
         this.client = client;
     }
 
-    /**
-     * Creates a new {@link FormTrainingClient} object.The new {@code FormRecognizerClient} uses the same request policy
-     * pipeline as the {@code FormRecognizerClient}.
-     *
-     * @return A new {@link FormTrainingClient} object.
-     */
-    public FormTrainingClient getFormTrainingClient() {
-        return new FormTrainingClient(client.getFormTrainingAsyncClient());
-    }
-
     /**
      * Recognizes and extracts receipt data from documents using optical character recognition (OCR)
      * and a custom trained model.

sdk/formrecognizer/azure-ai-formrecognizer/src/main/java/com/azure/ai/formrecognizer/FormRecognizerClientBuilder.java

@@ -43,10 +43,17 @@
  *
  * <p>
  * The client needs the service endpoint of the Azure Form Recognizer to access the resource service.
- * {@link #credential(AzureKeyCredential)} gives
- * the builder access credential.
+ * {@link #credential(AzureKeyCredential)} gives the builder access credential.
  * </p>
  *
+ * <p><strong>Instantiating an asynchronous Form Recognizer Client</strong></p>
+ *
+ * {@codesnippet com.azure.ai.formrecognizer.FormRecognizerAsyncClient.instantiation}
+ *
+ * <p><strong>Instantiating a synchronous Form Recognizer Client</strong></p>
+ *
+ * {@codesnippet com.azure.ai.formrecognizer.FormRecognizerClient.instantiation}
+ *
  * <p>
  * Another way to construct the client is using a {@link HttpPipeline}. The pipeline gives the client an
  * authenticated way to communicate with the service. Set the pipeline with {@link #pipeline(HttpPipeline) this} and
@@ -55,6 +62,8 @@
  * {@link FormRecognizerAsyncClient} is built.
  * </p>
  *
+ * {@codesnippet com.azure.ai.formrecognizer.FormRecognizerClient.pipeline.instantiation}
+ *
  * @see FormRecognizerAsyncClient
  * @see FormRecognizerClient
  */

sdk/formrecognizer/azure-ai-formrecognizer/src/main/java/com/azure/ai/formrecognizer/training/FormTrainingAsyncClient.java

@@ -19,6 +19,7 @@
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
 import com.azure.core.exception.HttpResponseException;
+import com.azure.core.http.HttpPipeline;
 import com.azure.core.http.rest.PagedFlux;
 import com.azure.core.http.rest.PagedResponse;
 import com.azure.core.http.rest.PagedResponseBase;
@@ -55,30 +56,56 @@
  * <p><strong>Instantiating an asynchronous Form Training Client</strong></p>
  * {@codesnippet com.azure.ai.formrecognizer.training.FormTrainingAsyncClient.initialization}
  *
- * @see FormRecognizerClientBuilder
- * @see FormRecognizerAsyncClient
+ * @see FormTrainingClientBuilder
+ * @see FormTrainingAsyncClient
  */
-@ServiceClient(builder = FormRecognizerClientBuilder.class, isAsync = true)
-public class FormTrainingAsyncClient {
+@ServiceClient(builder = FormTrainingClientBuilder.class, isAsync = true)
+public final class FormTrainingAsyncClient {
 
     private final ClientLogger logger = new ClientLogger(FormTrainingAsyncClient.class);
     private final FormRecognizerClientImpl service;
     private final FormRecognizerServiceVersion serviceVersion;
 
     /**
      * Create a {@link FormTrainingClient} that sends requests to the Form Recognizer service's endpoint.
-     * Each service call goes through the {@link FormRecognizerClientBuilder#pipeline http pipeline}.
+     * Each service call goes through the {@link FormTrainingClientBuilder#pipeline http pipeline}.
      *
      * @param service The proxy service used to perform REST calls.
      * @param serviceVersion The versions of Azure Form Recognizer supported by this client library.
      */
-    // TODO (savaity): Should not be a public constructor, still deciding the best approach here,
-    //  to be redone in #10909
-    public FormTrainingAsyncClient(FormRecognizerClientImpl service, FormRecognizerServiceVersion serviceVersion) {
+    FormTrainingAsyncClient(FormRecognizerClientImpl service, FormRecognizerServiceVersion serviceVersion) {
         this.service = service;
         this.serviceVersion = serviceVersion;
     }
 
+    /**
+     * Creates a new {@link FormRecognizerAsyncClient} object. The new {@code FormTrainingAsyncClient}
+     * uses the same request policy pipeline as the {@code FormTrainingAsyncClient}.
+     *
+     * @return A new {@code FormRecognizerAsyncClient} object.
+     */
+    public FormRecognizerAsyncClient getFormRecognizerAsyncClient() {
+        return new FormRecognizerClientBuilder().endpoint(getEndpoint()).pipeline(getHttpPipeline()).buildAsyncClient();
+    }
+
+    /**
+     * Gets the pipeline the client is using.
+     *
+     * @return the pipeline the client is using.
+     */
+    HttpPipeline getHttpPipeline() {
+        return service.getHttpPipeline();
+    }
+
+    /**
+     * Gets the endpoint the client is using.
+     *
+     * @return the endpoint the client is using.
+     */
+    String getEndpoint() {
+        return service.getEndpoint();
+    }
+
     /**
      * Gets the service version the client is using.
      *

sdk/formrecognizer/azure-ai-formrecognizer/src/main/java/com/azure/ai/formrecognizer/training/FormTrainingClient.java

@@ -3,7 +3,6 @@
 
 package com.azure.ai.formrecognizer.training;
 
-import com.azure.ai.formrecognizer.FormRecognizerAsyncClient;
 import com.azure.ai.formrecognizer.FormRecognizerClient;
 import com.azure.ai.formrecognizer.FormRecognizerClientBuilder;
 import com.azure.ai.formrecognizer.models.AccountProperties;
@@ -30,25 +29,35 @@
  * <p><strong>Instantiating a synchronous Form Training Client</strong></p>
  * {@codesnippet com.azure.ai.formrecognizer.training.FormTrainingClient.initialization}
  *
- * @see FormRecognizerClientBuilder
- * @see FormRecognizerClient
+ * @see FormTrainingClientBuilder
+ * @see FormTrainingClient
  */
-@ServiceClient(builder = FormRecognizerClientBuilder.class)
-public class FormTrainingClient {
+@ServiceClient(builder = FormTrainingClientBuilder.class)
+public final class FormTrainingClient {
 
     private final FormTrainingAsyncClient client;
 
     /**
      * Create a {@link FormTrainingClient} that sends requests to the Form Recognizer service's endpoint.
-     * Each service call goes through the {@link FormRecognizerClientBuilder#pipeline http pipeline}.
+     * Each service call goes through the {@link FormTrainingClientBuilder#pipeline http pipeline}.
      *
-     * @param formTrainingAsyncClient The {@link FormRecognizerAsyncClient} that the client routes its request through.
+     * @param formTrainingAsyncClient The {@link FormTrainingAsyncClient} that the client routes its request through.
      */
-    // TODO (savaity): Still deciding the best approach here, to be redone in #10909
-    public FormTrainingClient(FormTrainingAsyncClient formTrainingAsyncClient) {
+    FormTrainingClient(FormTrainingAsyncClient formTrainingAsyncClient) {
         this.client = formTrainingAsyncClient;
     }
 
+    /**
+     * Creates a new {@link FormRecognizerClient} object. The new {@code FormTrainingClient}
+     * uses the same request policy pipeline as the {@code FormTrainingClient}.
+     *
+     * @return A new {@code FormRecognizerClient} object.
+     */
+    public FormRecognizerClient getFormRecognizerClient() {
+        return new FormRecognizerClientBuilder().endpoint(client.getEndpoint()).pipeline(client.getHttpPipeline())
+            .buildClient();
+    }
+
     /**
      * Create and train a custom model.
      * <p>Models are trained using documents that are of the following content