Fixes to Tables tests, as well as client documentation and exceptions. (Azure#23336)

* - Ensured that tests exclusive to Storage are not run when testing a Cosmos endpoint.
- Fixed tests that failed due to Cosmos not returning a `[email protected]` property in a `TableEntity` alongside the `Timestamp` property, like Storage does. This is apparently intended behavior, so we now treat `Timestamp` as a special case that needs to be always converted to `OffsetDateTime`.
- Fixed the `setGetProperty()` tests in `TableServiceClientTest` and `TableServiceAsyncClientTest`, which failed for Storage because properties can take up to 30 seconds to be propagated on Storage accounts.
- Updated `TableEntity` documentation to remove all mentions of using its subclasses.
- Updated clients to properly map the implementation `TableServiceErrorException` to the public `TableServiceException` in operations such as `getAccessPolicies()`, `getProperties()`, `setProperties()` and `getStatistics()`, including their "withResponse" variants.
- Updated client documentation to accurately reflect which exceptions are thrown by service methods.
- Fixed batch operations to properly log exceptions other than `TableTransactionFailedException`.

* Removed unused import.

* Applied PR feedback:

- Removed assumption that prevented the `canUseSasTokenToCreateValidTableClient()` tests to run on Cosmos endpoints.
- Changed `TableAsyncClient.submitTransactionWithResponse()` to wrap an `IllegalArgumentException` with a `Mono` when no transaction actions are provided.
- Updated `submitTransactionAsyncWithSameRowKeys()` tests to check the error's status code instead of just the error message.

* Skipping `canUseSasTokenToCreateValidTableClient()` tests for Cosmos endpoints to unblock nightly test runs. Will investigate further until this can be resolved.

* Fixed CheckStyle issue.

Author: vcolin7

sdk/tables/azure-data-tables/src/main/java/com/azure/data/tables/TableAsyncClient.java

@@ -863,7 +863,6 @@ public void close() {
      * empty.
      * @throws TableServiceException If no {@link TableEntity entity} with the provided {@code partitionKey} and
      * {@code rowKey} exists within the table.
-     * table.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<TableEntity> getEntity(String partitionKey, String rowKey) {
@@ -939,12 +938,16 @@ <T extends TableEntity> Mono<Response<T>> getEntityWithResponse(String partition
      * Retrieves details about any stored {@link TableAccessPolicies access policies} specified on the table that may
      * be used with Shared Access Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Gets a table's {@link TableAccessPolicies access policies}. Prints out the details of the retrieved
      * {@link TableAccessPolicies access policies}.</p>
      * {@codesnippet com.azure.data.tables.tableAsyncClient.getAccessPolicies}
      *
      * @return A {@link Mono} containing the table's {@link TableAccessPolicies access policies}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<TableAccessPolicies> getAccessPolicies() {
@@ -956,13 +959,17 @@ public Mono<TableAccessPolicies> getAccessPolicies() {
      * Retrieves details about any stored {@link TableAccessPolicies access policies} specified on the table that may be
      * used with Shared Access Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Gets a table's {@link TableAccessPolicies access policies}. Prints out the details of the
      * {@link Response HTTP response} and the retrieved {@link TableAccessPolicies access policies}.</p>
      * {@codesnippet com.azure.data.tables.tableAsyncClient.getAccessPoliciesWithResponse}
      *
      * @return A {@link Mono} containing an {@link Response HTTP response} that in turn contains the table's
      * {@link TableAccessPolicies access policies}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<Response<TableAccessPolicies>> getAccessPoliciesWithResponse() {
@@ -975,6 +982,7 @@ Mono<Response<TableAccessPolicies>> getAccessPoliciesWithResponse(Context contex
         try {
             return tablesImplementation.getTables()
                 .getAccessPolicyWithResponseAsync(tableName, null, null, context)
+                .onErrorMap(TableUtils::mapThrowableToTableServiceException)
                 .map(response -> new SimpleResponse<>(response,
                     new TableAccessPolicies(response.getValue() == null ? null : response.getValue().stream()
                         .map(this::toTableSignedIdentifier)
@@ -1008,13 +1016,17 @@ private TableAccessPolicy toTableAccessPolicy(AccessPolicy accessPolicy) {
      * Sets stored {@link TableAccessPolicies access policies} for the table that may be used with Shared Access
      * Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Sets stored {@link TableAccessPolicies access policies} on a table.</p>
      * {@codesnippet com.azure.data.tables.tableAsyncClient.setAccessPolicies#List}
      *
      * @param tableSignedIdentifiers The {@link TableSignedIdentifier access policies} for the table.
      *
      * @return An empty {@link Mono}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<Void> setAccessPolicies(List<TableSignedIdentifier> tableSignedIdentifiers) {
@@ -1025,6 +1037,8 @@ public Mono<Void> setAccessPolicies(List<TableSignedIdentifier> tableSignedIdent
      * Sets stored {@link TableAccessPolicies access policies} for the table that may be used with Shared Access
      * Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Sets stored {@link TableAccessPolicies access policies} on a table. Prints out details of the
      * {@link Response HTTP response}.</p>
@@ -1033,6 +1047,8 @@ public Mono<Void> setAccessPolicies(List<TableSignedIdentifier> tableSignedIdent
      * @param tableSignedIdentifiers The {@link TableSignedIdentifier access policies} for the table.
      *
      * @return A {@link Mono} containing the {@link Response HTTP response}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Mono<Response<Void>> setAccessPoliciesWithResponse(List<TableSignedIdentifier> tableSignedIdentifiers) {
@@ -1081,6 +1097,7 @@ OffsetDateTime.now will only give back milliseconds (more precise fields are zer
         try {
             return tablesImplementation.getTables()
                 .setAccessPolicyWithResponseAsync(tableName, null, null, signedIdentifiers, context)
+                .onErrorMap(TableUtils::mapThrowableToTableServiceException)
                 .map(response -> new SimpleResponse<>(response, response.getValue()));
         } catch (RuntimeException e) {
             return monoError(logger, e);
@@ -1132,6 +1149,7 @@ private AccessPolicy toAccessPolicy(TableAccessPolicy tableAccessPolicy) {
      * correspond to each {@link TableTransactionAction action} in the transaction.
      *
      * @throws IllegalArgumentException If no {@link TableTransactionAction actions} have been added to the list.
+     * @throws TableServiceException If the request is rejected by the service.
      * @throws TableTransactionFailedException If any {@link TableTransactionResult action} within the transaction
      * fails. See the documentation for the client methods in {@link TableClient} to understand the conditions that
      * may cause a given {@link TableTransactionAction action} to fail.
@@ -1168,6 +1186,7 @@ public Mono<TableTransactionResult> submitTransaction(List<TableTransactionActio
      * correspond to each {@link TableTransactionAction action} in the transaction.
      *
      * @throws IllegalArgumentException If no {@link TableTransactionAction actions} have been added to the list.
+     * @throws TableServiceException If the request is rejected by the service.
      * @throws TableTransactionFailedException If any {@link TableTransactionAction action} within the transaction
      * fails. See the documentation for the client methods in {@link TableClient} to understand the conditions that
      * may cause a given {@link TableTransactionAction action} to fail.
@@ -1180,8 +1199,8 @@ public Mono<Response<TableTransactionResult>> submitTransactionWithResponse(List
     Mono<Response<TableTransactionResult>> submitTransactionWithResponse(List<TableTransactionAction> transactionActions, Context context) {
         Context finalContext = context == null ? Context.NONE : context;
 
-        if (transactionActions.size() == 0) {
-            throw logger.logExceptionAsError(
+        if (transactionActions.isEmpty()) {
+            return monoError(logger,
                 new IllegalArgumentException("A transaction must contain at least one operation."));
         }
 
@@ -1224,18 +1243,23 @@ Mono<Response<TableTransactionResult>> submitTransactionWithResponse(List<TableT
             }
         }
 
-        return Flux.fromIterable(operations)
-            .flatMapSequential(op -> op.prepareRequest(transactionalBatchClient).zipWith(Mono.just(op)))
-            .collect(TransactionalBatchRequestBody::new, (body, pair) ->
-                body.addChangeOperation(new TransactionalBatchSubRequest(pair.getT2(), pair.getT1())))
-            .publishOn(Schedulers.boundedElastic())
-            .flatMap(body ->
-                transactionalBatchImplementation.submitTransactionalBatchWithRestResponseAsync(body, null,
-                    finalContext).zipWith(Mono.just(body)))
-            .flatMap(pair -> parseResponse(pair.getT2(), pair.getT1()))
-            .map(response ->
-                new SimpleResponse<>(response.getRequest(), response.getStatusCode(), response.getHeaders(),
-                    new TableTransactionResult(transactionActions, response.getValue())));
+        try {
+            return Flux.fromIterable(operations)
+                .flatMapSequential(op -> op.prepareRequest(transactionalBatchClient).zipWith(Mono.just(op)))
+                .collect(TransactionalBatchRequestBody::new, (body, pair) ->
+                    body.addChangeOperation(new TransactionalBatchSubRequest(pair.getT2(), pair.getT1())))
+                .publishOn(Schedulers.boundedElastic())
+                .flatMap(body ->
+                    transactionalBatchImplementation.submitTransactionalBatchWithRestResponseAsync(body, null,
+                        finalContext).zipWith(Mono.just(body)))
+                .onErrorMap(TableUtils::mapThrowableToTableServiceException)
+                .flatMap(pair -> parseResponse(pair.getT2(), pair.getT1()))
+                .map(response ->
+                    new SimpleResponse<>(response.getRequest(), response.getStatusCode(), response.getHeaders(),
+                        new TableTransactionResult(transactionActions, response.getValue())));
+        } catch (RuntimeException e) {
+            return monoError(logger, e);
+        }
     }
 
     private Mono<Response<List<TableTransactionActionResponse>>> parseResponse(TransactionalBatchRequestBody requestBody,

sdk/tables/azure-data-tables/src/main/java/com/azure/data/tables/TableClient.java

@@ -524,12 +524,16 @@ public Response<TableEntity> getEntityWithResponse(String partitionKey, String r
      * Retrieves details about any stored {@link TableAccessPolicies access policies} specified on the table that may
      * be used with Shared Access Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Gets a table's {@link TableAccessPolicies access policies}. Prints out the details of the retrieved
      * {@link TableAccessPolicies access policies}.</p>
      * {@codesnippet com.azure.data.tables.tableClient.getAccessPolicies}
      *
      * @return The table's {@link TableAccessPolicies access policies}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public TableAccessPolicies getAccessPolicies() {
@@ -540,6 +544,8 @@ public TableAccessPolicies getAccessPolicies() {
      * Retrieves details about any stored {@link TableAccessPolicies access policies} specified on the table that may be
      * used with Shared Access Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Gets a table's {@link TableAccessPolicies access policies}. Prints out the details of the
      * {@link Response HTTP response} and the retrieved {@link TableAccessPolicies access policies}.</p>
@@ -550,6 +556,8 @@ public TableAccessPolicies getAccessPolicies() {
      * the service call.
      *
      * @return An {@link Response HTTP response} containing the table's {@link TableAccessPolicies access policies}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Response<TableAccessPolicies> getAccessPoliciesWithResponse(Duration timeout, Context context) {
@@ -560,11 +568,15 @@ public Response<TableAccessPolicies> getAccessPoliciesWithResponse(Duration time
      * Sets stored {@link TableAccessPolicies access policies} for the table that may be used with Shared Access
      * Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Sets stored {@link TableAccessPolicies access policies} on a table.</p>
      * {@codesnippet com.azure.data.tables.tableClient.setAccessPolicies#List}
      *
      * @param tableSignedIdentifiers The {@link TableSignedIdentifier access policies} for the table.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public void setAccessPolicies(List<TableSignedIdentifier> tableSignedIdentifiers) {
@@ -575,6 +587,8 @@ public void setAccessPolicies(List<TableSignedIdentifier> tableSignedIdentifiers
      * Sets stored {@link TableAccessPolicies access policies} for the table that may be used with Shared Access
      * Signatures.
      *
+     * <p>This operation is only supported on Azure Storage endpoints.</p>
+     *
      * <p><strong>Code Samples</strong></p>
      * <p>Sets stored {@link TableAccessPolicies access policies} on a table. Prints out details of the
      * {@link Response HTTP response}.</p>
@@ -586,6 +600,8 @@ public void setAccessPolicies(List<TableSignedIdentifier> tableSignedIdentifiers
      * the service call.
      *
      * @return The {@link Response HTTP response}.
+     *
+     * @throws TableServiceException If the request is rejected by the service.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
     public Response<Void> setAccessPoliciesWithResponse(List<TableSignedIdentifier> tableSignedIdentifiers,
@@ -618,6 +634,7 @@ public Response<Void> setAccessPoliciesWithResponse(List<TableSignedIdentifier>
      * {@link TableTransactionResult action} in the transaction.
      *
      * @throws IllegalArgumentException If no {@link TableTransactionAction actions} have been added to the list.
+     * @throws TableServiceException If the request is rejected by the service.
      * @throws TableTransactionFailedException If any {@link TableTransactionResult action} within the transaction
      * fails. See the documentation for the client methods in {@link TableClient} to understand the conditions that
      * may cause a given {@link TableTransactionAction action} to fail.
@@ -657,6 +674,7 @@ public TableTransactionResult submitTransaction(List<TableTransactionAction> tra
      * {@link TableTransactionAction action} in the transaction.
      *
      * @throws IllegalArgumentException If no {@link TableTransactionAction actions} have been added to the list.
+     * @throws TableServiceException If the request is rejected by the service.
      * @throws TableTransactionFailedException If any {@link TableTransactionAction action} within the transaction
      * fails. See the documentation for the client methods in {@link TableClient} to understand the conditions that
      * may cause a given {@link TableTransactionAction action} to fail.