Emphasized RxJava vs Reactor guide; removed Legacy naming; added Azure Cosmos DB prefix; modified wording

Author: anfeldma-ms

articles/cosmos-db/migrate-java-v4-sdk.md

@@ -15,46 +15,46 @@ ms.reviewer: sngun
 > For more information about this SDK, please view the Azure Cosmos DB Java SDK v4 Release notes, [Maven repository](https://mvnrepository.com/artifact/com.azure/azure-cosmos), Azure Cosmos DB Java SDK v4 [performance tips](performance-tips-java-sdk-v4-sql.md), and Azure Cosmos DB Java SDK v4 [troubleshooting guide](troubleshoot-java-sdk-v4-sql.md).
 >
 
-This article explains how to upgrade your existing Java application that is using older Azure Cosmos DB Java SDK to the newer Java SDK 4.0 for Core (SQL) API. The Java V4 SDK corresponds to the `com.azure.cosmos` package. You can use the instructions in this doc if you are migrating your application from any of the following SDKs: 
+This article explains how to upgrade your existing Java application that is using older Azure Cosmos DB Java SDK to the newer Java SDK 4.0 for Core (SQL) API. The Azure Cosmos DB Java SDK v4 corresponds to the `com.azure.cosmos` package. You can use the instructions in this doc if you are migrating your application from any of the following Azure Cosmos DB Java SDKs: 
 
-* Legacy Sync Java SDK 2.x.x
+* Sync Java SDK 2.x.x
 * Async Java SDK 2.x.x
 * Java SDK 3.x.x
 
-## Java SDK’s and package mappings
+## Azure Cosmos DB Java SDK’s and package mappings
 
 The following table lists different Azure Cosmos DB Java SDKs, the package name and the release information:
 
 | Java SDK| Release Date | Bundled APIs   | Maven Jar  | Java package name  |API Reference   | Release Notes  |
 |-------|------|-----------|-----------|--------------|-------------|---------------------------|
 | Async 2.x.x  | June 2018    | Async(RxJava)  | `com.microsoft.azure::azure-cosmosdb` | `com.microsoft.azure.cosmosdb.rx` | [API](https://azure.github.io/azure-cosmosdb-java/2.0.0/) | [Release Notes](sql-api-sdk-async-java.md) |
-| Legacy Sync 2.x.x     | Sept 2018    | Sync   | `com.microsoft.azure::azure-documentdb` | `com.microsoft.azure.cosmosdb` | [API](https://azure.github.io/azure-cosmosdb-java/2.0.0/) | [Release Notes](sql-api-sdk-java.md)  |
+| Sync 2.x.x     | Sept 2018    | Sync   | `com.microsoft.azure::azure-documentdb` | `com.microsoft.azure.cosmosdb` | [API](https://azure.github.io/azure-cosmosdb-java/2.0.0/) | [Release Notes](sql-api-sdk-java.md)  |
 | 3.x.x    | July 2019    | Async(Reactor)/Sync  | `com.microsoft.azure::azure-cosmos`  | `com.azure.data.cosmos` | [API](https://azure.github.io/azure-cosmosdb-java/3.0.0/) | - |
 | 4.0   | April 2020   | Async(Reactor)/Sync  | `com.azure::azure-cosmos` | `com.azure.cosmos`   | -  | -  |
 
 ## SDK level implementation changes
 
 The following are the key implementation differences between different SDKs:
 
-### RxJava is replaced with reactor in Java 3.x.x and 4.0 SDKs
+### RxJava is replaced with reactor in Azure Cosmos DB Java SDK versions 3.x.x and 4.0
 
-If you have been using the 3.x.x Java SDK or the preview versions of that SDK and migrating to the 4.0 SDK, see the [Reactor pattern guide](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-pattern-guide.md) for an introduction to async programming and Reactor.
+If you are unfamiliar with asynchronous programming or Reactive Programming, see the [Reactor pattern guide](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-pattern-guide.md) for an introduction to async programming and Project Reactor. This guide may be useful if you have been using Azure Cosmos DB Sync Java SDK 2.x.x or Azure Cosmos DB Java SDK 3.x.x Sync API in the past.
 
-If you have been using Async Java SDK 2.x.x, and migrating to the 4.0 SDK, see the [Reactor vs RxJava Guide](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-rxjava-guide.md) for guidance on converting RxJava code to use Reactor.
+If you have been using Azure Cosmos DB Async Java SDK 2.x.x, and you plan on migrating to the 4.0 SDK, see the [Reactor vs RxJava Guide](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-rxjava-guide.md) for guidance on converting RxJava code to use Reactor.
 
-### Java SDK 4.0 has direct connectivity mode in both Async and Sync APIs
+### Azure Cosmos DB Java SDK v4 has direct connectivity mode in both Async and Sync APIs
 
-If you have been using the legacy Sync Java SDK 2.x.x, note that the direct connection mode based on TCP (as opposed to HTTP) is implemented in Java SDK 4.0 for both the Async and Sync APIs.
+If you have been using Azure Cosmos DB Sync Java SDK 2.x.x, note that the direct connection mode based on TCP (as opposed to HTTP) is implemented in Azure Cosmos DB Java SDK 4.0 for both the Async and Sync APIs.
 
 ## API level changes
 
-The following are the API level changes between Java 3.x.x Vs 4.x.x SDK and Async Java SDK 2.x.x and Legacy sync Java SDK 2.x.x:
+The following are the API level changes in Azure Cosmos DB Java SDK 4.x.x compared to previous SDKs (Java SDK 3.x.x, Async Java SDK 2.x.x, and Sync Java SDK 2.x.x):
 
 ![Azure Cosmos DB Java SDK naming conventions](./media/migrate-java-v4-sdk/java-sdk-naming-conventions.png)
 
-* The Java SDK 3.x.x and 4.0 refer the client resources as `Cosmos<resourceName>`. For example, `CosmosClient`, `CosmosDatabase`, `CosmosContainer`. Whereas in version 2.x.x, the Java SDKs doesn’t have a uniform naming scheme.
+* The Azure Cosmos DB Java SDK 3.x.x and 4.0 refer the client resources as `Cosmos<resourceName>`. For example, `CosmosClient`, `CosmosDatabase`, `CosmosContainer`. Whereas in version 2.x.x, the Azure Cosmos DB Java SDKs don’t have a uniform naming scheme.
 
-* The Java SDK 3.x.x and 4.0 offer both Sync and Async APIs.
+* Azure Cosmos DB Java SDK 3.x.x and 4.0 offer both Sync and Async APIs.
 
   * **Java SDK 4.0** : All the classes belong to the Sync API unless the class name is appended with `Async` after `Cosmos`.
 
@@ -64,31 +64,31 @@ The following are the API level changes between Java 3.x.x Vs 4.x.x SDK and Asyn
 
 ### Hierarchical API structure
 
-The Java SDK 4.0 and Java SDK 3.x.x introduces a hierarchical API structure that organizes the clients, databases, and containers in a nested fashion as shown in the following 4.0 SDK code snippet:
+Azure Cosmos DB Java SDK 4.0 and 3.x.x introduce a hierarchical API structure that organizes the clients, databases, and containers in a nested fashion as shown in the following 4.0 SDK code snippet:
 
 ```java
 CosmosContainer = client.getDatabase("MyDatabaseName").getContainer("MyContainerName");
 ```
 
-In version 2.x.x of Java SDKs, all operations on resources and documents are performed through the client instance.
+In version 2.x.x of the Azure Cosmos DB Java SDK, all operations on resources and documents are performed through the client instance.
 
 ### Representing documents
 
-In Java SDK 4.0, custom POJO's and `JsonNodes` are the two options to read and write the documents from Azure Cosmos DB.
+In Azure Cosmos DB Java SDK 4.0, custom POJO's and `JsonNodes` are the two options to read and write the documents from Azure Cosmos DB.
 
-In the Java SDK 3.x.x, the `CosmosItemProperties` object is exposed by the public API and served as a document representation. This class is no longer exposed in Java SDK 4.0.
+In the Azure Cosmos DB Java SDK 3.x.x, the `CosmosItemProperties` object is exposed by the public API and served as a document representation. This class is no longer exposed publicly in version 4.0.
 
 ### Imports
 
-* The Java SDK 4.0 packages begin with `com.azure.cosmos`
-  * Java SDK 3.x.x packages begin with `com.azure.data.cosmos`
+* The Azure Cosmos DB Java SDK 4.0 packages begin with `com.azure.cosmos`
+  * Azure Cosmos DB Java SDK 3.x.x packages begin with `com.azure.data.cosmos`
 
-* Java SDK 4.0 places several classes in a nested package `com.azure.cosmos.models`. Some of these packages include:
+* Azure Cosmos DB Java SDK 4.0 places several classes in a nested package `com.azure.cosmos.models`. Some of these packages include:
 
   * `CosmosContainerResponse`
   * `CosmosDatabaseResponse`
   * `CosmosItemResponse`
-  * The Async API analogs for all the above packages
+  * The Async API analogs for all of the above packages
   * `CosmosContainerProperties`
   * `FeedOptions`
   * `PartitionKey`
@@ -97,9 +97,9 @@ In the Java SDK 3.x.x, the `CosmosItemProperties` object is exposed by the publi
 
 ### Accessors
 
-The Java SDK 4.0 exposes `get` and `set` methods to access the instance members. For example, the `CosmosContainer` instance has `container.getId()` and `container.setId()` methods.
+Azure Cosmos DB Java SDK 4.0 exposes `get` and `set` methods to access the instance members. For example, the `CosmosContainer` instance has `container.getId()` and `container.setId()` methods.
 
-This is different from Java SDK 3.x.x which exposes a fluent interface. For example, a `CosmosSyncContainer` instance has `container.id()` which is overloaded to get or set the `id` value.
+This is different from Azure Cosmos DB Java SDK 3.x.x which exposes a fluent interface. For example, a `CosmosSyncContainer` instance has `container.id()` which is overloaded to get or set the `id` value.
 
 ## Code snippet comparisons
 
@@ -541,4 +541,5 @@ SalesOrder salesOrder = new SalesOrder(
 ## Next steps
 
 * [Build a Java app](create-sql-api-java.md) to manage Azure Cosmos DB SQL API data using the V4 SDK
-* Learn about the [Reactor-based Java SDKs](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-pattern-guide.md)
+* Learn about the [Reactor-based Java SDKs](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-pattern-guide.md)
+* Learn about converting RxJava async code to Reactor async code with the [Reactor vs RxJava Guide](https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples/blob/master/reactor-rxjava-guide.md)