Review Before Releasing Azure Cognitive Search

eng/code-quality-reports/src/main/resources/checkstyle/checkstyle-suppressions.xml

@@ -491,4 +491,12 @@
   <suppress checks="ConstantName" files="com.azure.spring.data.cosmos.repository|common.*\.java" />
   <suppress checks="ConstantName|MemberName" files="com.azure.cosmos.UserRepositoryConfiguration|AppConfiguration|MyDocument.java" />
 
+  <!-- These suppressions were added due to limitations in our custom Checkstyle rules and should be addressed in the future. -->
+  <!-- API naming is too restrictive -->
+  <suppress checks="com.azure.tools.checkstyle.checks.ServiceClientCheck" files="com.azure.search.documents.indexes.SearchIndexerAsyncClient.java"
+            lines="654,671,699,716"/>
+  <suppress checks="com.azure.tools.checkstyle.checks.ServiceClientCheck" files="com.azure.search.documents.indexes.SearchIndexerClient.java"
+            lines="495,513,529,547"/>
+
+  <!-- ServiceMethod return type for Collection doesn't check for sub-types -->
 </suppressions>

sdk/search/azure-search-documents/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Release History
 
-## 11.0.0 (Unreleased)
+## 11.0.0 (2020-07-10)
+
 - Changed version to 11.0.0.
-- Removed preview version `SearchClientOptions.ServiceVersion.V2019_05_06_Preview`
-  and added version `SearchClientOptions.ServiceVersion.V2020_06_30`.
-- Added value constructors for required parameters.
+- Removed preview version `SearchClientOptions.ServiceVersion.V2019_05_06_Preview` and added version `SearchClientOptions.ServiceVersion.V2020_06_30`.
+
+### New Features
+
+- Added `IndexDocumentsOptions` used to configure document operations.
+
+### Breaking Changes
+
+- Moved search result metadata to `SearchPagedFlux` and `SearchPagedIterable` from `SearchPagedResponse`.
+- Changed many model classes from fluent setter pattern to immutable constructor pattern.
+- Removed `RequestOptions` from APIs, instead use pipeline context to pass per method contextual information.
+- Removed strongly type GeoJSON classes.
+
+### Bug Fixes
+
+- Removed `implementation` classes from APIs.
 
 ## 1.0.0-beta.4 (2020-06-09)
 - Split `SearchServiceClient` into two clients `SearchIndexClient`, `SearchIndexerClient`.

sdk/search/azure-search-documents/README.md

@@ -21,7 +21,7 @@ The Azure Cognitive Search service is well suited for the following
 * In a search client application, implement query logic and user experiences
   similar to commercial web search engines.
 
-Use the Azure Search client library to:
+Use the Azure Cognitive Search client library to:
 
 * Submit queries for simple and advanced query forms that include fuzzy
   search, wildcard search, regular expressions.

sdk/search/azure-search-documents/pom.xml

@@ -11,8 +11,8 @@
     <relativePath>../../parents/azure-client-sdk-parent</relativePath>
   </parent>
 
-  <name>Microsoft Azure Search client for Java</name>
-  <description>This package contains client functionality for Microsoft Azure Search</description>
+  <name>Microsoft Azure Cognitive Search client for Java</name>
+  <description>This package contains client functionality for Microsoft Azure Cognitive Search</description>
 
   <groupId>com.azure</groupId>
   <artifactId>azure-search-documents</artifactId>

sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchAsyncClient.java

@@ -69,7 +69,10 @@
 import static com.azure.core.util.FluxUtil.withContext;
 
 /**
- * Cognitive Search Asynchronous Client to query an index and upload, merge, or delete documents
+ * This class provides a client that contains the operations for querying an index and uploading, merging, or deleting
+ * documents in an Azure Cognitive Search service.
+ *
+ * @see SearchClientBuilder
  */
 @ServiceClient(builder = SearchClientBuilder.class, isAsync = true)
 public final class SearchAsyncClient {
@@ -213,8 +216,7 @@ public Mono<Response<IndexDocumentsResult>> uploadDocumentsWithResponse(Iterable
 
     Mono<Response<IndexDocumentsResult>> uploadDocumentsWithResponse(Iterable<?> documents,
         IndexDocumentsOptions options, Context context) {
-        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.UPLOAD), options,
-            context);
+        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.UPLOAD), options, context);
     }
 
     /**
@@ -283,8 +285,7 @@ public Mono<Response<IndexDocumentsResult>> mergeDocumentsWithResponse(Iterable<
 
     Mono<Response<IndexDocumentsResult>> mergeDocumentsWithResponse(Iterable<?> documents,
         IndexDocumentsOptions options, Context context) {
-        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.MERGE), options,
-            context);
+        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.MERGE), options, context);
     }
 
     /**
@@ -411,8 +412,7 @@ public Mono<Response<IndexDocumentsResult>> deleteDocumentsWithResponse(Iterable
 
     Mono<Response<IndexDocumentsResult>> deleteDocumentsWithResponse(Iterable<?> documents,
         IndexDocumentsOptions options, Context context) {
-        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.DELETE), options,
-            context);
+        return indexDocumentsWithResponse(buildIndexBatch(documents, IndexActionType.DELETE), options, context);
     }
 
     /**
@@ -468,11 +468,9 @@ public Mono<Response<IndexDocumentsResult>> indexDocumentsWithResponse(IndexDocu
     Mono<Response<IndexDocumentsResult>> indexDocumentsWithResponse(IndexDocumentsBatch<?> batch,
         IndexDocumentsOptions options, Context context) {
         try {
-            IndexDocumentsOptions documentsOptions = (options == null)
-                ? new IndexDocumentsOptions() : options;
+            IndexDocumentsOptions documentsOptions = (options == null) ? new IndexDocumentsOptions() : options;
             return restClient.getDocuments()
-                .indexWithResponseAsync(IndexBatchBaseConverter.map(batch), null,
-                    context)
+                .indexWithResponseAsync(IndexBatchBaseConverter.map(batch), null, context)
                 .onErrorMap(MappingUtils::exceptionMapper)
                 .flatMap(response -> (response.getStatusCode() == MULTI_STATUS_CODE
                     && documentsOptions.throwOnAnyError())
@@ -527,22 +525,21 @@ public <T> Mono<T> getDocument(String key, Class<T> modelClass) {
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Lookup-Document">Lookup document</a>
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
-    public <T> Mono<Response<T>> getDocumentWithResponse(String key, Class<T> modelClass,
-        List<String> selectedFields) {
-        return withContext(context -> getDocumentWithResponse(key, modelClass,
-            selectedFields, context));
+    public <T> Mono<Response<T>> getDocumentWithResponse(String key, Class<T> modelClass, List<String> selectedFields) {
+        return withContext(context -> getDocumentWithResponse(key, modelClass, selectedFields, context));
     }
 
     @SuppressWarnings("unchecked")
-    <T> Mono<Response<T>> getDocumentWithResponse(String key, Class<T> modelClass,
-        List<String> selectedFields, Context context) {
+    <T> Mono<Response<T>> getDocumentWithResponse(String key, Class<T> modelClass, List<String> selectedFields,
+        Context context) {
         try {
             return restClient.getDocuments()
                 .getWithResponseAsync(key, selectedFields, null, context)
                 .onErrorMap(DocumentResponseConversions::exceptionMapper)
                 .map(res -> {
                     if (SearchDocument.class == modelClass) {
-                        TypeReference<Map<String, Object>> typeReference = new TypeReference<Map<String, Object>>() { };
+                        TypeReference<Map<String, Object>> typeReference = new TypeReference<Map<String, Object>>() {
+                        };
                         SearchDocument doc = new SearchDocument(MAPPER.convertValue(res.getValue(), typeReference));
                         return new SimpleResponse<T>(res, (T) doc);
                     }
@@ -603,7 +600,7 @@ Mono<Response<Long>> getDocumentCountWithResponse(Context context) {
      * <p>
      * If {@code searchText} is set to {@code null} or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
-     * syntax in Azure Search</a> for more information about search query syntax.
+     * syntax in Azure Cognitive Search</a> for more information about search query syntax.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -617,16 +614,17 @@ Mono<Response<Long>> getDocumentCountWithResponse(Context context) {
      * information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Search-Documents">Search documents</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SearchPagedFlux search(String searchText) {
-        return this.search(searchText, null, null);
+        return this.search(searchText, null);
     }
 
     /**
      * Searches for documents in the Azure Cognitive Search index.
      * <p>
      * If {@code searchText} is set to {@code null} or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
-     * syntax in Azure Search</a> for more information about search query syntax.
+     * syntax in Azure Cognitive Search</a> for more information about search query syntax.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -641,6 +639,7 @@ public SearchPagedFlux search(String searchText) {
      * information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Search-Documents">Search documents</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SearchPagedFlux search(String searchText, SearchOptions searchOptions) {
         SearchRequest request = createSearchRequest(searchText, searchOptions);
         // The firstPageResponse shared among all fucntional calls below.
@@ -661,16 +660,16 @@ SearchPagedFlux search(String searchText, SearchOptions searchOptions, Context c
         return new SearchPagedFlux(() -> func.apply(null), func);
     }
 
-    private Mono<SearchPagedResponse> search(SearchRequest request,
-        String continuationToken, SearchFirstPageResponseWrapper firstPageResponseWrapper, Context context) {
+    private Mono<SearchPagedResponse> search(SearchRequest request, String continuationToken,
+        SearchFirstPageResponseWrapper firstPageResponseWrapper, Context context) {
         if (continuationToken == null && firstPageResponseWrapper.getFirstPageResponse() != null) {
             return Mono.just(firstPageResponseWrapper.getFirstPageResponse());
         }
-        SearchRequest requestToUse = (continuationToken == null) ? request
+        SearchRequest requestToUse = (continuationToken == null)
+            ? request
             : SearchContinuationToken.deserializeToken(serviceVersion.getVersion(), continuationToken);
 
-        return restClient.getDocuments().searchPostWithResponseAsync(requestToUse,
-            null, context)
+        return restClient.getDocuments().searchPostWithResponseAsync(requestToUse, null, context)
             .onErrorMap(MappingUtils::exceptionMapper)
             .map(response -> {
                 SearchDocumentsResult result = response.getValue();
@@ -726,6 +725,7 @@ private static Map<String, List<FacetResult>> getFacets(SearchDocumentsResult re
      * {@link SuggestPagedResponse} object for each page containing HTTP response and coverage information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Suggestions">Suggestions</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SuggestPagedFlux suggest(String searchText, String suggesterName) {
         return suggest(searchText, suggesterName, null);
     }
@@ -747,6 +747,7 @@ public SuggestPagedFlux suggest(String searchText, String suggesterName) {
      * {@link SuggestPagedResponse} object for each page containing HTTP response and coverage information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Suggestions">Suggestions</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SuggestPagedFlux suggest(String searchText, String suggesterName, SuggestOptions suggestOptions) {
         SuggestRequest suggestRequest = createSuggestRequest(searchText, suggesterName,
             SuggestOptionsHandler.ensureSuggestOptions(suggestOptions));
@@ -762,8 +763,7 @@ SuggestPagedFlux suggest(String searchText, String suggesterName, SuggestOptions
     }
 
     private Mono<SuggestPagedResponse> suggest(SuggestRequest suggestRequest, Context context) {
-        return restClient.getDocuments().suggestPostWithResponseAsync(suggestRequest,
-            null, context)
+        return restClient.getDocuments().suggestPostWithResponseAsync(suggestRequest, null, context)
             .onErrorMap(MappingUtils::exceptionMapper)
             .map(response -> {
                 SuggestDocumentsResult result = response.getValue();
@@ -792,8 +792,9 @@ private static List<SuggestResult> getSuggestResults(SuggestDocumentsResult resu
      * @param suggesterName suggester name
      * @return auto complete result.
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public AutocompletePagedFlux autocomplete(String searchText, String suggesterName) {
-        return autocomplete(searchText, suggesterName, null, null);
+        return autocomplete(searchText, suggesterName, null);
     }
 
     /**
@@ -825,8 +826,7 @@ AutocompletePagedFlux autocomplete(String searchText, String suggesterName, Auto
     }
 
     private Mono<AutocompletePagedResponse> autocomplete(AutocompleteRequest request, Context context) {
-        return restClient.getDocuments().autocompletePostWithResponseAsync(request,
-            null, context)
+        return restClient.getDocuments().autocompletePostWithResponseAsync(request, null, context)
             .onErrorMap(MappingUtils::exceptionMapper)
             .map(MappingUtils::mappingAutocompleteResponse);
     }

sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/SearchClient.java

@@ -27,7 +27,10 @@
 import java.util.List;
 
 /**
- * Cognitive Search Synchronous Client to query an index and upload, merge, or delete documents
+ * This class provides a client that contains the operations for querying an index and uploading, merging, or deleting
+ * documents in an Azure Cognitive Search service.
+ *
+ * @see SearchClientBuilder
  */
 @ServiceClient(builder = SearchClientBuilder.class)
 public final class SearchClient {
@@ -182,7 +185,7 @@ public IndexDocumentsResult mergeDocuments(Iterable<?> documents) {
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Response<IndexDocumentsResult> mergeDocumentsWithResponse(Iterable<?> documents,
-            IndexDocumentsOptions options, Context context) {
+        IndexDocumentsOptions options, Context context) {
         return asyncClient.mergeDocumentsWithResponse(documents, options, context).block();
     }
 
@@ -249,7 +252,7 @@ public IndexDocumentsResult mergeOrUploadDocuments(Iterable<?> documents) {
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Response<IndexDocumentsResult> mergeOrUploadDocumentsWithResponse(Iterable<?> documents,
-                IndexDocumentsOptions options, Context context) {
+        IndexDocumentsOptions options, Context context) {
         return asyncClient.mergeOrUploadDocumentsWithResponse(documents, options, context).block();
     }
 
@@ -443,7 +446,7 @@ public Response<Long> getDocumentCountWithResponse(Context context) {
      * <p>
      * If {@code searchText} is set to {@code null} or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
-     * syntax in Azure Search</a> for more information about search query syntax.
+     * syntax in Azure Cognitive Search</a> for more information about search query syntax.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -457,6 +460,7 @@ public Response<Long> getDocumentCountWithResponse(Context context) {
      * information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Search-Documents">Search documents</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SearchPagedIterable search(String searchText) {
         return search(searchText, null, Context.NONE);
     }
@@ -466,7 +470,7 @@ public SearchPagedIterable search(String searchText) {
      * <p>
      * If {@code searchText} is set to {@code null} or {@code "*"} all documents will be matched, see
      * <a href="https://docs.microsoft.com/rest/api/searchservice/Simple-query-syntax-in-Azure-Search">simple query
-     * syntax in Azure Search</a> for more information about search query syntax.
+     * syntax in Azure Cognitive Search</a> for more information about search query syntax.
      *
      * <p><strong>Code Sample</strong></p>
      *
@@ -482,6 +486,7 @@ public SearchPagedIterable search(String searchText) {
      * information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Search-Documents">Search documents</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SearchPagedIterable search(String searchText, SearchOptions searchOptions, Context context) {
         return new SearchPagedIterable(asyncClient.search(searchText, searchOptions, context));
     }
@@ -502,6 +507,7 @@ public SearchPagedIterable search(String searchText, SearchOptions searchOptions
      * the {@link SuggestPagedResponse} object for each page containing HTTP response and coverage information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Suggestions">Suggestions</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SuggestPagedIterable suggest(String searchText, String suggesterName) {
         return suggest(searchText, suggesterName, null, Context.NONE);
     }
@@ -524,10 +530,10 @@ public SuggestPagedIterable suggest(String searchText, String suggesterName) {
      * the {@link SuggestPagedResponse} object for each page containing HTTP response and coverage information.
      * @see <a href="https://docs.microsoft.com/rest/api/searchservice/Suggestions">Suggestions</a>
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public SuggestPagedIterable suggest(String searchText, String suggesterName, SuggestOptions suggestOptions,
         Context context) {
-        return new SuggestPagedIterable(asyncClient.suggest(searchText, suggesterName, suggestOptions,
-            context));
+        return new SuggestPagedIterable(asyncClient.suggest(searchText, suggesterName, suggestOptions, context));
     }
 
     /**
@@ -543,6 +549,7 @@ public SuggestPagedIterable suggest(String searchText, String suggesterName, Sug
      * @param suggesterName suggester name
      * @return auto complete result.
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public AutocompletePagedIterable autocomplete(String searchText, String suggesterName) {
         return autocomplete(searchText, suggesterName, null, Context.NONE);
     }
@@ -562,6 +569,7 @@ public AutocompletePagedIterable autocomplete(String searchText, String suggeste
      * @param context additional context that is passed through the HTTP pipeline during the service call
      * @return auto complete result.
      */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
     public AutocompletePagedIterable autocomplete(String searchText, String suggesterName,
         AutocompleteOptions autocompleteOptions, Context context) {
         return new AutocompletePagedIterable(asyncClient.autocomplete(searchText, suggesterName, autocompleteOptions,