[Form Recognizer] Address API view feedback (#36233)

Azure · Aug 4, 2023 · f2a67eb · f2a67eb
1 parent e618ba1
commit f2a67eb
Show file tree

Hide file tree

Showing 18 changed files with 376 additions and 258 deletions.
diff --git a/...er/src/main/java/com/azure/ai/formrecognizer/documentanalysis/DocumentAnalysisClient.java b/...er/src/main/java/com/azure/ai/formrecognizer/documentanalysis/DocumentAnalysisClient.java
@@ -363,6 +363,76 @@ private SyncPoller<OperationResult, AnalyzeResult> beginAnalyzeDocumentFromUrlSy
             fetchingOperation(modelId, finalContext));
     }
 
+    /**
+     * Classify a given document using a document classifier.
+     * For more information on how to build a custom classifier model,
+     * see <a href="https://aka.ms/azsdk/formrecognizer/buildclassifiermodel"></a>
+     * <p>The service does not support cancellation of the long running operation and returns with an
+     * error message indicating absence of cancellation support</p>
+     *
+     * <p><strong>Code sample</strong></p>
+     * <p> Analyze a document using the URL of the document with configurable options. </p>
+     * <!-- src_embed com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocumentFromUrl#string-string -->
+     * <pre>
+     * String documentUrl = &quot;&#123;file_source_url&#125;&quot;;
+     * String classifierId = &quot;&#123;custom_trained_classifier_id&#125;&quot;;
+     *
+     * documentAnalysisClient.beginClassifyDocumentFromUrl&#40;classifierId, documentUrl&#41;
+     *     .getFinalResult&#40;&#41;
+     *     .getDocuments&#40;&#41;
+     *     .forEach&#40;analyzedDocument -&gt; System.out.printf&#40;&quot;Doc Type: %s%n&quot;, analyzedDocument.getDocType&#40;&#41;&#41;&#41;;
+     * </pre>
+     * <!-- end com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocumentFromUrl#string-string -->
+     *
+     * @param classifierId The unique classifier ID to be used. Use this to specify the custom classifier ID.
+     * Prebuilt model IDs supported can be found <a href="https://aka.ms/azsdk/formrecognizer/models">here</a>
+     * @param documentUrl The source URL to the input document.
+     *
+     * @return A {@link SyncPoller} to poll the progress of the analyze document operation until it has completed,
+     * has failed, or has been cancelled. The completed operation returns an {@link AnalyzeResult}.
+     * @throws HttpResponseException If analyze operation fails and returns with an {@link OperationStatus#FAILED}.
+     * @throws IllegalArgumentException If {@code documentUrl} or {@code classifierId} is null.
+     */
+    @ServiceMethod(returns = ReturnType.LONG_RUNNING_OPERATION)
+    public SyncPoller<OperationResult, AnalyzeResult>
+        beginClassifyDocumentFromUrl(String classifierId, String documentUrl) {
+        return beginClassifyDocumentFromUrl(documentUrl, classifierId, Context.NONE);
+    }
+
+    /**
+     * Classify a given document using a document classifier.
+     * For more information on how to build a custom classifier model,
+     * see <a href="https://aka.ms/azsdk/formrecognizer/buildclassifiermodel"></a>
+     * <p>The service does not support cancellation of the long running operation and returns with an
+     * error message indicating absence of cancellation support.</p>
+     *
+     * <p><strong>Code sample</strong></p>
+     * <!-- src_embed com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData -->
+     * <pre>
+     * File document = new File&#40;&quot;&#123;local&#47;file_path&#47;fileName.jpg&#125;&quot;&#41;;
+     * String classifierId = &quot;&#123;custom_trained_classifier_id&#125;&quot;;
+     * byte[] fileContent = Files.readAllBytes&#40;document.toPath&#40;&#41;&#41;;
+     *
+     * documentAnalysisClient.beginClassifyDocument&#40;classifierId, BinaryData.fromBytes&#40;fileContent&#41;&#41;
+     *     .getFinalResult&#40;&#41;
+     *     .getDocuments&#40;&#41;
+     *     .forEach&#40;analyzedDocument -&gt; System.out.printf&#40;&quot;Doc Type: %s%n&quot;, analyzedDocument.getDocType&#40;&#41;&#41;&#41;;
+     * </pre>
+     * <!-- end com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData -->
+     *
+     * @param classifierId The unique classifier ID to be used. Use this to specify the custom classifier ID.
+     * @param document The data of the document to analyze information from.
+     * @return A {@link SyncPoller} that polls the of progress of analyze document operation until it has completed,
+     * has failed, or has been cancelled. The completed operation returns an {@link AnalyzeResult}.
+     * @throws HttpResponseException If analyze operation fails and returns with an {@link OperationStatus#FAILED}.
+     * @throws IllegalArgumentException If {@code document} or {@code classifierId} is null.
+     */
+    @ServiceMethod(returns = ReturnType.LONG_RUNNING_OPERATION)
+    public SyncPoller<OperationResult, AnalyzeResult>
+        beginClassifyDocument(String classifierId, BinaryData document) {
+        return beginClassifyDocument(classifierId, document, Context.NONE);
+    }
+
     /**
      * Classify a given document using a document classifier.
      * For more information on how to build a custom classifier model,
@@ -399,28 +469,6 @@ private SyncPoller<OperationResult, AnalyzeResult> beginAnalyzeDocumentFromUrlSy
         beginClassifyDocumentFromUrl(String classifierId, String documentUrl, Context context) {
         return beginClassifyDocumentFromUrlSync(documentUrl, classifierId, context);
     }
-    private SyncPoller<OperationResult, AnalyzeResult> beginClassifyDocumentFromUrlSync(String documentUrl, String classifierId, Context context) {
-        if (CoreUtils.isNullOrEmpty(documentUrl)) {
-            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'documentUrl' is required and cannot"
-                + " be null or empty"));
-        }
-        if (CoreUtils.isNullOrEmpty(classifierId)) {
-            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'classifierId' is required and cannot"
-                + " be null or empty"));
-        }
-        context = enableSyncRestProxy(getTracingContext(context));
-        Context finalContext = context;
-        return SyncPoller.createPoller(
-            DEFAULT_POLL_INTERVAL,
-            cxt -> new PollResponse<>(LongRunningOperationStatus.NOT_STARTED, classifyActivationOperation(classifierId,
-                null,
-                documentUrl,
-                finalContext).apply(cxt)),
-            pollingClassifierOperation(classifierId, finalContext),
-            getCancellationIsNotSupported(),
-            fetchingClassifierOperation(classifierId, finalContext));
-    }
-
     /**
      * Classify a given document using a document classifier.
      * For more information on how to build a custom classifier model,
@@ -429,7 +477,7 @@ private SyncPoller<OperationResult, AnalyzeResult> beginClassifyDocumentFromUrlS
      * error message indicating absence of cancellation support.</p>
      *
      * <p><strong>Code sample</strong></p>
-     * <!-- src_embed com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData -->
+     * <!-- src_embed com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData-Context -->
      * <pre>
      * File document = new File&#40;&quot;&#123;local&#47;file_path&#47;fileName.jpg&#125;&quot;&#41;;
      * String classifierId = &quot;&#123;custom_trained_classifier_id&#125;&quot;;
@@ -440,7 +488,7 @@ private SyncPoller<OperationResult, AnalyzeResult> beginClassifyDocumentFromUrlS
      *     .getDocuments&#40;&#41;
      *     .forEach&#40;analyzedDocument -&gt; System.out.printf&#40;&quot;Doc Type: %s%n&quot;, analyzedDocument.getDocType&#40;&#41;&#41;&#41;;
      * </pre>
-     * <!-- end com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData -->
+     * <!-- end com.azure.ai.formrecognizer.documentanalysis.DocumentAnalysisClient.beginClassifyDocument#string-BinaryData-Context -->
      *
      * @param classifierId The unique classifier ID to be used. Use this to specify the custom classifier ID.
      * @param document The data of the document to analyze information from.
@@ -477,6 +525,28 @@ private SyncPoller<OperationResult, AnalyzeResult> beginClassifyDocumentFromUrlS
             fetchingClassifierOperation(classifierId, finalContext));
     }
 
+    private SyncPoller<OperationResult, AnalyzeResult> beginClassifyDocumentFromUrlSync(String documentUrl, String classifierId, Context context) {
+        if (CoreUtils.isNullOrEmpty(documentUrl)) {
+            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'documentUrl' is required and cannot"
+                + " be null or empty"));
+        }
+        if (CoreUtils.isNullOrEmpty(classifierId)) {
+            throw LOGGER.logExceptionAsError(new IllegalArgumentException("'classifierId' is required and cannot"
+                + " be null or empty"));
+        }
+        context = enableSyncRestProxy(getTracingContext(context));
+        Context finalContext = context;
+        return SyncPoller.createPoller(
+            DEFAULT_POLL_INTERVAL,
+            cxt -> new PollResponse<>(LongRunningOperationStatus.NOT_STARTED, classifyActivationOperation(classifierId,
+                null,
+                documentUrl,
+                finalContext).apply(cxt)),
+            pollingClassifierOperation(classifierId, finalContext),
+            getCancellationIsNotSupported(),
+            fetchingClassifierOperation(classifierId, finalContext));
+    }
+
     private Function<PollingContext<OperationResult>, OperationResult> analyzeActivationOperation(
         String modelId, List<String> pages, String locale,
         List<com.azure.ai.formrecognizer.documentanalysis.models.DocumentAnalysisFeature> features,