Skip to content

Updated cosmos release notes #11684

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kushagraThapar merged 3 commits into from
Jun 3, 2020
Merged

Updated cosmos release notes #11684

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
914563a
Updated cosmos release notes
kushagraThapar Jun 2, 2020
d59f900
Updated cosmos release notes with categories and readme with logging …
kushagraThapar Jun 2, 2020
c04544f
Merged latest master and resolved conflicts
kushagraThapar Jun 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 59 additions & 6 deletions sdk/cosmos/azure-cosmos/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,65 @@
# Release History

## 4.0.1-beta.4 (Unreleased)
### New Features
* Added more samples & enriched docs to `CosmosClientBuilder`.
* Updated `CosmosDatabase` & `CosmosContainer` APIs with throughputProperties for autoscale/autopilot support.
* Renamed `CosmosClientException` to `CosmosException`.
* Replaced `AccessCondition` & `AccessConditionType` by `ifMatchETag()` & `ifNoneMatchETag()` APIs.
* Merged all `Cosmos*AsyncResponse` & `CosmosResponse` types to a single `CosmosResponse` type.
* Renamed `CosmosResponseDiagnostics` to `CosmosDiagnostics`.
* Wrapped `FeedResponseDiagnostics` in `CosmosDiagnostics`.
* Removed `jackson` dependency from azure-cosmos & relying on azure-core.
* Replaced `CosmosKeyCredential` with `AzureKeyCredential` type.
* Added `ProxyOptions` APIs to `GatewayConnectionConfig`.
* Updated SDK to use `Instant` type instead of `OffsetDateTime`.
* Added new enum type `OperationKind`.
* Renamed `FeedOptions` to `QueryRequestOptions`.
* Added `getETag()` & `getTimestamp()` APIs to `Cosmos*Properties` types.
* Added `userAgent` information in `CosmosException` & `CosmosDiagnostics`.
* Updated new line character in `Diagnostics` to System new line character.
### Key Bug Fixes

## 4.0.1-beta.3 (2020-05-15)
### New Features
* Added autoscale/autopilot throughput provisioning support to SDK.
* Replaced `ConnectionPolicy` with new connection configs. Exposed `DirectConnectionConfig` & `GatewayConnectionConfig` APIs through `CosmosClientBuilder` for Direct & Gateway mode connection configurations.
* Moved `JsonSerializable` & `Resource` to implementation package.
* Added `contentResponseOnWriteEnabled` API to CosmosClientBuilder which disables full response content on write operations.
* Exposed `getETag()` APIs on response types.
* Moved `CosmosAuthorizationTokenResolver` to implementation.
* Renamed `preferredLocations` & `multipleWriteLocations` API to `preferredRegions` & `multipleWriteRegions`.
* Updated `reactor-core` to 3.3.5.RELEASE, `reactor-netty` to 0.9.7.RELEASE & `netty` to 4.1.49.Final versions.
* Added support for `analyticalStoreTimeToLive` in SDK.
### Key Bug Fixes
* Fixed socket leak issues with Direct TCP client.
* Fixed `orderByQuery` with continuation token bug.

## 4.0.1-beta.3 (Unreleased)
## 4.0.1-beta.2 (2020-04-21)
### New Features
* `CosmosClientException` extends `AzureException`.
* Removed `maxItemCount` & `requestContinuationToken` APIs from `FeedOptions` instead using `byPage()` APIs from `CosmosPagedFlux` & `CosmosPagedIterable`.
* Introduced `CosmosPermissionProperties` on public surface for `Permission` APIs.
* Removed `SqlParameterList` type & replaced with `List`
* Fixed multiple memory leaks in Direct TCP client.
* Added support for `DISTINCT` queries.
* Removed external dependencies on `fasterxml.uuid, guava, commons-io, commons-collection4, commons-text`.
* Moved `CosmosPagedFlux` & `CosmosPagedIterable` to `utils` package.
* Updated netty to 4.1.45.Final & project reactor to 3.3.3 version.
* Updated public rest contracts to `Final` classes.
### Key Bug Fixes
* `ChangeFeedProcessor` bug fix for handling partition splits & when partition not found.
* `ChangeFeedProcessor` bug fix when synchronizing lease updates across different threads.


## 4.0.1-beta.2 (Unreleased)


## 4.0.1-beta.1 (Unreleased)
## 4.0.1-beta.1 (2020-03-10)
### New Features
* Updated package to `com.azure.cosmos`
* Added `models` package for model / rest contracts
* Added `utils` package for `CosmosPagedFlux` & `CosmosPagedIterable` types.
* Updated public APIs to use `Duration` across the SDK.
* Added all rest contracts to `models` package.
* `RetryOptions` renamed to `ThrottlingRetryOptions`.
* Added `CosmosPagedFlux` & `CosmosPagedIterable` pagination types for query APIs.
* Added support for sharing TransportClient across multiple instances of CosmosClients using a new API in the `CosmosClientBuilder#connectionSharingAcrossClientsEnabled(true)`
### Key Bug Fixes
* Fixed race condition causing `ArrayIndexOutOfBound` exception in StoreReader
181 changes: 133 additions & 48 deletions sdk/cosmos/azure-cosmos/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
# Azure CosmosDB Client Library for Java

[![Maven Central][cosmos_maven_svg]][cosmos_maven]

Azure Cosmos DB is Microsoft’s globally distributed, multi-model database service for operational and analytics workloads. It offers multi-mastering feature by automatically scaling throughput, compute, and storage.
This project provides SDK library in Java for interacting with [SQL API][sql_api_query] of [Azure Cosmos DB Database Service][cosmos_introduction].

[Source code][source_code] | [API reference documentation][api_documentation] | [Product documentation][cosmos_docs] |
[Source code][source_code] | [Package (Maven)][cosmos_maven] | [API reference documentation][api_documentation] | [Product documentation][cosmos_docs] |
[Samples][samples]

## Getting started
Expand Down Expand Up @@ -68,12 +66,24 @@ A Cosmos DB account contains zero or more databases, a database (DB) contains ze
You may read more about databases, containers and items [here](https://docs.microsoft.com/en-us/azure/cosmos-db/databases-containers-items).
A few important properties defined at the level of the container, among them are provisioned throughput and partition key.

### Global Distribution
- Azure Cosmos DB is a globally distributed database service that's designed to provide low latency, elastic scalability of throughput, well-defined semantics for data consistency, and high availability.
In short, if your application needs guaranteed fast response time anywhere in the world, if it's required to be always online, and needs unlimited and elastic scalability of throughput and storage, you should build your application on Azure Cosmos DB.
You may read more about global distribution [here](https://docs.microsoft.com/en-us/azure/cosmos-db/distribute-data-globally).
- 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.

### Throughput Provisioning
- Azure Cosmos DB allows you to set provisioned throughput on your databases and containers.
There are two types of provisioned throughput, standard (manual) or autoscale. 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](https://docs.microsoft.com/en-us/azure/cosmos-db/set-throughput).

### Request Units (RUs)
- Azure Cosmos DB supports many APIs, such as SQL, MongoDB, Cassandra, Gremlin, and Table.
Each API has its own set of database operations. These operations range from simple point reads and writes to complex queries.
Each database operation consumes system resources based on the complexity of the operation. The cost of all database operations is normalized by Azure Cosmos DB and is expressed by Request Units (or RUs, for short).
You can think of RUs per second as the currency for throughput. RUs per second is a rate-based currency. It abstracts the system resources such as CPU, IOPS, and memory that are required to perform the database operations supported by Azure Cosmos DB.
You may read more about request units [here](https://docs.microsoft.com/en-us/azure/cosmos-db/request-units).

### Partitioning
- As items are inserted into a 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, and 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; therefore you are advised to choose a partition key which is relatively random or evenly-distributed.
Expand All @@ -82,57 +92,95 @@ You may learn more about partitioning [here](https://docs.microsoft.com/en-us/az

## Examples

See the complete code in [`HelloWorldDemo.java`](../azure-cosmos-examples/src/main/java/com/azure/cosmos/examples/HelloWorldDemo.java)
The following section provides several code snippets covering some of the most common CosmosDB SQL API tasks, including:
* [Create Cosmos Client](#create-cosmos-client "Create Cosmos Client")
* [Create Database](#create-database "Create Database")
* [Create Container](#create-container "Create Container")
* [CRUD operation on Items](#crud-operation-on-items "CRUD operation on Items")

### Create Cosmos Client
```java
import com.azure.cosmos.*;
import reactor.core.publisher.Mono;
// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient cosmosAsyncClient = new CosmosClientBuilder()
.endpoint("<YOUR ENDPOINT HERE>")
.key("<YOUR KEY HERE>")
.buildAsyncClient();

import java.io.IOException;
// Create a new CosmosClient via the CosmosClientBuilder
CosmosClient cosmosClient = new CosmosClientBuilder()
.endpoint("<YOUR ENDPOINT HERE>")
.key("<YOUR KEY HERE>")
.buildClient();

// ...
// Create a new CosmosClient with customizations
CosmosClient cosmosClient = new CosmosClientBuilder()
.endpoint(serviceEndpoint)
.key(key)
.directMode(directConnectionConfig, gatewayConnectionConfig)
.consistencyLevel(ConsistencyLevel.SESSION)
.connectionSharingAcrossClientsEnabled(true)
.contentResponseOnWriteEnabled(true)
.userAgentSuffix("my-application1-client")
.preferredRegions(Collections.singletonList("West US", "East US"))
.buildClient();
```

// Create a new CosmosAsyncClient via the CosmosClientBuilder
// It only requires endpoint and key, but other useful settings are available
CosmosAsyncClient client = new CosmosClientBuilder()
.endpoint("<YOUR ENDPOINT HERE>")
.key("<YOUR KEY HERE>")
.buildAsyncClient();

// Get a reference to the container
// This will create (or read) a database and its container.
CosmosAsyncContainer container = client.createDatabaseIfNotExists(DATABASE_NAME)
// TIP: Our APIs are Reactor Core based, so try to chain your calls
.flatMap(response -> client.getDatabase(DATABASE_NAME)
.createContainerIfNotExists(CONTAINER_NAME, "/id"))
.flatMap(response -> Mono.just(client.getDatabase(DATABASE_NAME).getContainer(CONTAINER_NAME)))
.block();
### Create Database
Using any one of the clients created in previous example, you can create a database like this:

```java
// Get a reference to the container
// This will create (or read) a database and its container.
client.createDatabaseIfNotExists(DATABASE_NAME)
// TIP: Our APIs are Reactor Core based, so try to chain your calls
.flatMap(response -> client.getDatabase(DATABASE_NAME)
.subscribe();
```

### Create Container
Using the above created database, you can chain another operation to it for creating a container like this:

```java
client.createDatabaseIfNotExists(DATABASE_NAME)
// TIP: Our APIs are Reactor Core based, so try to chain your calls
.flatMap(response -> client.getDatabase(DATABASE_NAME)
// Create Container
.createContainerIfNotExists(CONTAINER_NAME, "/id"))
.flatMap(response -> Mono.just(client.getDatabase(DATABASE_NAME).getContainer(CONTAINER_NAME)))
.subscribe();
```
### CRUD operation on Items

```java

// Create an item
container.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
.flatMap(response -> {
System.out.println("Created item: " + response.getItem());
// Read that item 👓
return container.readItem(response.getItem().getId(),
new PartitionKey(response.getItem().getId()),
Passenger.class);
})
.flatMap(response -> {
System.out.println("Read item: " + response.getItem());
// Replace that item 🔁
Passenger p = response.getItem();
p.setDestination("SFO");
return container.replaceItem(p,
response.getItem().getId(),
new PartitionKey(response.getItem().getId()));
})
// delete that item 💣
.flatMap(response -> container.deleteItem(response.getItem().getId(),
new PartitionKey(response.getItem().getId())))
.block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// Create an item
container.createItem(new Passenger("carla.davis@outlook.com", "Carla Davis", "SEA", "IND"))
.flatMap(response -> {
System.out.println("Created item: " + response.getItem());
// Read that item 👓
return container.readItem(response.getItem().getId(),
new PartitionKey(response.getItem().getId()),
Passenger.class);
})
.flatMap(response -> {
System.out.println("Read item: " + response.getItem());
// Replace that item 🔁
Passenger p = response.getItem();
p.setDestination("SFO");
return container.replaceItem(p,
response.getItem().getId(),
new PartitionKey(response.getItem().getId()));
})
// delete that item 💣
.flatMap(response -> container.deleteItem(response.getItem().getId(),
new PartitionKey(response.getItem().getId())))
.block(); // Blocking for demo purposes (avoid doing this in production unless you must)
// ...
```

See the complete code in [`HelloWorldDemo.java`](../azure-cosmos-examples/src/main/java/com/azure/cosmos/examples/HelloWorldDemo.java)

We have a get started sample app available [here][getting_started].

Also, we have more examples [examples project][samples].
Expand All @@ -148,7 +196,44 @@ However, because Azure Cosmos DB is accessed via network calls there are client-

- [Performance][perf_guide] guide covers these client-side optimizations.

- [Troubleshooting guide][troubleshooting] covers common issues, workarounds, diagnostic steps, and tools when you use Azure Cosmos DB Java SDK v4 with Azure Cosmos DB SQL API accounts.
- [Troubleshooting guide][troubleshooting] covers common issues, workarounds, diagnostic steps, and tools when you use Azure Cosmos DB Java SDK v4 with Azure Cosmos DB SQL API accounts.

### Enable Client Logging
Azure Cosmos DB Java SDK v4 uses SLF4j as the logging facade that supports logging into popular logging frameworks such as log4j and logback.

For example, if you want to use log4j as the logging framework, add the following libs in your Java classpath.

```xml
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>${slf4j.version}</version>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>${log4j.version}</version>
</dependency>
```

Also add a log4j config.

```properties
# this is a sample log4j configuration

# Set root logger level to DEBUG and its only appender to A1.
log4j.rootLogger=INFO, A1

log4j.category.com.azure.cosmos=DEBUG
#log4j.category.io.netty=INFO
#log4j.category.io.reactivex=INFO
# A1 is set to be a ConsoleAppender.
log4j.appender.A1=org.apache.log4j.ConsoleAppender

# A1 uses PatternLayout.
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d %5X{pid} [%t] %-5p %c - %m%n
```

## Next Steps

Expand Down