Acrolinx fixes

Author: KarlErickson

articles/cosmos-db/nosql/quickstart-java-spring-data.md

@@ -46,23 +46,23 @@ Azure Cosmos DB is a multi-model database service that lets you quickly create a
 
 * An Azure account with an active subscription.
   * No Azure subscription? You can [try Azure Cosmos DB free](../try-free.md) with no credit card required.
-* [Java Development Kit (JDK) 8](https://www.azul.com/downloads/azure-only/zulu/?&version=java-8-lts&architecture=x86-64-bit&package=jdk). Point your `JAVA_HOME` environment variable to the folder where the JDK is installed.
+* [Java Development Kit (JDK) 8](https://www.azul.com/downloads/azure-only/zulu/?&version=java-8-lts&architecture=x86-64-bit&package=jdk). Set the `JAVA_HOME` environment variable to the JDK install folder.
 * A [Maven binary archive](https://maven.apache.org/download.cgi). On Ubuntu, run `apt-get install maven` to install Maven.
 * [Git](https://www.git-scm.com/downloads). On Ubuntu, run `sudo apt-get install git` to install Git.
 
 ## Introductory notes
 
-*The structure of an Azure Cosmos DB account.* Irrespective of API or programming language, an Azure Cosmos DB *account* contains zero or more *databases*, a *database* (DB) contains zero or more *containers*, and a *container* contains zero or more items, as shown in the diagram below:
+*The structure of an Azure Cosmos DB account.* Irrespective of API or programming language, an Azure Cosmos DB *account* contains zero or more *databases*, a *database* (DB) contains zero or more *containers*, and a *container* contains zero or more items, as shown in the following diagram:
 
 :::image type="content" source="../media/account-databases-containers-items/cosmos-entities.png" alt-text="Azure Cosmos DB account entities" border="false":::
 
 For more information about databases, containers, and items, see [Azure Cosmos DB resource model](../account-databases-containers-items.md). A few important properties are defined at the level of the container, among them *provisioned throughput* and *partition key*.
 
-The provisioned throughput is measured in Request Units (*RUs*) which have a monetary price and are a substantial determining factor in the operating cost of the account. Provisioned throughput can be selected at per-container granularity or per-database granularity, however container-level throughput specification is typically preferred. You may read more about throughput provisioning [here.](../set-throughput.md)
+The provisioned throughput is measured in Request Units (*RUs*) which have a monetary price and are a substantial determining factor in the operating cost of the account. You can select provisioned throughput at per-container granularity or per-database granularity. However, you should prefer container-level throughput specification. For more information, see [Introduction to provisioned throughput in Azure Cosmos DB](../set-throughput.md).
 
 As items are inserted into an Azure Cosmos DB container, the database grows horizontally by adding more storage and compute to handle requests. Storage and compute capacity are added in discrete units known as *partitions*. You must choose one field in your documents to be the partition key, which maps each document to a partition.
 
-The way partitions are managed is that each partition is assigned a roughly equal slice out of the range of partition key values. For this reason, you should choose a partition key that's relatively random or evenly distributed. Otherwise, some partitions (called *hot partitions*) will see substantially more requests, while other partitions (called *cold partitions*) will see substantially fewer requests, and this is to be avoided. For more information, see [Partitioning and horizontal scaling in Azure Cosmos DB](../partitioning-overview.md).
+The way partitions are managed is that each partition is assigned a roughly equal slice out of the range of partition key values. For this reason, you should choose a partition key that's relatively random or evenly distributed. Otherwise, you get *hot partitions* and *cold partitions*, which see substantially more or fewer requests. For information on avoiding this condition, see [Partitioning and horizontal scaling in Azure Cosmos DB](../partitioning-overview.md).
 
 ## Create a database account
 
@@ -85,7 +85,7 @@ Before you can create a document database, you need to create an API for NoSQL a
 
 ## Clone the sample application
 
-Now let's switch to working with code. Let's clone an API for NoSQL app from GitHub, set the connection string, and run it. You see how easy it is to work with data programmatically.
+Now let's switch to working with code. Let's clone an API for NoSQL app from GitHub, set the connection string, and run it.
 
 Run the following command to clone the sample repository. This command creates a copy of the sample app on your computer.
 
@@ -99,17 +99,17 @@ This step is optional. If you're interested in learning how the database resourc
 
 ### [Passwordless (Recommended)](#tab/passwordless)
 
-In this section, neither the configurations nor the code has any authentication operations. However, connecting to Azure service requires authentication. To complete the authentication, you need to use Azure Identity. Spring Cloud Azure uses `DefaultAzureCredential`, which is provided by Azure Identity to help you get credentials without any code changes.
+In this section, the configurations and the code don't have any authentication operations. However, connecting to Azure service requires authentication. To complete the authentication, you need to use Azure Identity. Spring Cloud Azure uses `DefaultAzureCredential`, which Azure Identity provides to help you get credentials without any code changes.
 
-`DefaultAzureCredential` supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code. For more information, see the [Default Azure credential](/azure/developer/java/sdk/identity-azure-hosted-auth#default-azure-credential) section of [Authenticate Azure-hosted Java applications](/azure/developer/java/sdk/identity-azure-hosted-auth).
+`DefaultAzureCredential` supports multiple authentication methods and determines which method to use at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code. For more information, see the [Default Azure credential](/azure/developer/java/sdk/identity-azure-hosted-auth#default-azure-credential) section of [Authenticate Azure-hosted Java applications](/azure/developer/java/sdk/identity-azure-hosted-auth).
 
 [!INCLUDE [cosmos-nosql-create-assign-roles](../../../includes/passwordless/cosmos-nosql/cosmos-nosql-create-assign-roles.md)]
 
 ### Authenticate using DefaultAzureCredential
 
 [!INCLUDE [default-azure-credential-sign-in](../../../includes/passwordless/default-azure-credential-sign-in.md)]
 
-You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the `azure-identity` [dependency](https://mvnrepository.com/artifact/com.azure/azure-identity) to your application. `DefaultAzureCredential` will automatically discover and use the account you signed in with in the previous step.
+You can authenticate to Cosmos DB for NoSQL using `DefaultAzureCredential` by adding the `azure-identity` [dependency](https://mvnrepository.com/artifact/com.azure/azure-identity) to your application. `DefaultAzureCredential` automatically discovers and uses the account you signed in with in the previous step.
 
 ### Application configuration file
 
@@ -124,41 +124,7 @@ spring:
         database: ${COSMOS_DATABASE}
 ```
 
-After creating the Azure Cosmos DB account, database and container, Spring Boot/Spring Data will connect to the database and container for `delete`, `add`, and `find` operations.
-
-### Java source
-
-Spring Data provides a simple, clean, standardized, and platform-independent interface for operating on datastores, as shown in the following examples. These CRUD and query examples enable you to manipulate Azure Cosmos DB documents by using Spring Data Azure Cosmos DB. These examples build on the Spring Data GitHub sample linked to earlier in this article.
-
-* Item creation and updates by using the `save` method.
-
-  ```java
-  // Save the User class to Azure Cosmos DB database.
-  final Mono<User> saveUserMono = repository.save(testUser);
-  ```
-
-* Point-reads using the derived query method defined in the repository. The `findById` performs point-reads for `repository`. The fields mentioned in the method name cause Spring Data to execute a point-read defined by the `id` field:
-
-  ```java
-  //  Nothing happens until we subscribe to these Monos.
-  //  findById will not return the user as user is not present.
-  final Mono<User> findByIdMono = repository.findById(testUser.getId());
-  final User findByIdUser = findByIdMono.block();
-  Assert.isNull(findByIdUser, "User must be null");
-  ```
-
-* Item deletes using `deleteAll`:
-
-  ```java
-  repository.deleteAll().block();
-  LOGGER.info("Deleted all data in container.");
-  ```
-
-* Derived query based on repository method name. Spring Data implements the `repository` `findByFirstName` method as a Java SDK SQL query on the `firstName` field. This query couldn't be implemented as a point-read.
-
-  ```java
-  final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");
-  ```
+After Spring Boot and Spring Data create the Azure Cosmos DB account, database, and container, they connect to the database and container for `delete`, `add`, and `find` operations.
 
 ### [Password](#tab/password)
 
@@ -176,11 +142,13 @@ spring:
         database: ${COSMOS_DATABASE}
 ```
 
-Once you create an Azure Cosmos DB account, database, and container, just fill-in-the-blanks in the config file and Spring Boot/Spring Data will automatically do the following: (1) create an underlying Java SDK `CosmosClient` instance with the URI and key, and (2) connect to the database and container. You're all set - no more resource management code!
+Once you create an Azure Cosmos DB account, database, and container, just fill-in-the-blanks in the config file and Spring Boot/Spring Data does the following: (1) creates an underlying Java SDK `CosmosClient` instance with the URI and key, and (2) connects to the database and container. You're all set - no more resource management code!
+
+---
 
 ### Java source
 
-The Spring Data value-add also comes from its simple, clean, standardized and platform-independent interface for operating on datastores. Building on the Spring Data GitHub sample linked above, below are CRUD and query samples for manipulating Azure Cosmos DB documents with Spring Data Azure Cosmos DB.
+Spring Data provides a simple, clean, standardized, and platform-independent interface for operating on datastores, as shown in the following examples. These CRUD and query examples enable you to manipulate Azure Cosmos DB documents by using Spring Data Azure Cosmos DB. These examples build on the Spring Data GitHub sample linked to earlier in this article.
 
 * Item creation and updates by using the `save` method.
 
@@ -206,38 +174,36 @@ The Spring Data value-add also comes from its simple, clean, standardized and pl
   LOGGER.info("Deleted all data in container.");
   ```
 
-* Derived query based on repository method name. Spring Data implements the `repository` `findByFirstName` method as a Java SDK SQL query on the `firstName` field. This query couldn't be implemented as a point-read.
+* Derived query based on repository method name. Spring Data implements the `repository` `findByFirstName` method as a Java SDK SQL query on the `firstName` field. You can't implement this query as a point-read.
 
   ```java
   final Flux<User> firstNameUserFlux = repository.findByFirstName("testFirstName");
   ```
 
----
-
 ## Run the app
 
-Now go back to the Azure portal to get your connection string information and launch the app with your endpoint information. This enables your app to communicate with your hosted database.
+Now go back to the Azure portal to get your connection string information. Then, use the following steps to launch the app with your endpoint information so your app can communicate with your hosted database.
 
-1. In the git terminal window, `cd` to the sample code folder.
+1. In the Git terminal window, `cd` to the sample code folder.
 
    ```bash
    cd azure-spring-boot-samples/cosmos/spring-cloud-azure-starter-data-cosmos/spring-cloud-azure-data-cosmos-sample
    ```
 
-1. In the git terminal window, use the following command to install the required Spring Data Azure Cosmos DB packages.
+1. In the Git terminal window, use the following command to install the required Spring Data Azure Cosmos DB packages.
 
    ```bash
    mvn clean package
    ```
 
-1. In the git terminal window, use the following command to start the Spring Data Azure Cosmos DB application:
+1. In the Git terminal window, use the following command to start the Spring Data Azure Cosmos DB application:
 
    ```bash
    mvn spring-boot:run
    ```
 
 1. The app loads *application.yml* and connects the resources in your Azure Cosmos DB account.
-1. The app performs point CRUD operations described above.
+1. The app performs point CRUD operations described previously.
 1. The app performs a derived query.
 1. The app doesn't delete your resources. Switch back to the portal to [clean up the resources](#clean-up-resources) from your account if you want to avoid incurring charges.
 
@@ -251,7 +217,7 @@ Now go back to the Azure portal to get your connection string information and la
 
 ## Next steps
 
-In this quickstart, you've learned how to create an Azure Cosmos DB for NoSQL account, create a document database and container using the Data Explorer, and run a Spring Data app to do the same thing programmatically. You can now import more data into your Azure Cosmos DB account.
+In this quickstart, you learned how to create an Azure Cosmos DB for NoSQL account and create a document database and container using the Data Explorer. You then ran a Spring Data app to do the same thing programmatically. You can now import more data into your Azure Cosmos DB account.
 
 Trying to do capacity planning for a migration to Azure Cosmos DB? You can use information about your existing database cluster for capacity planning.