Updated documentation around match and if none match etag for request options (#43717)

* Updated documentation around match and if none match etag for request options

* Fixed some missing documentation

* Code review comments

Author: kushagraThapar

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosBatchItemRequestOptions.java

@@ -22,6 +22,9 @@ public CosmosBatchItemRequestOptions() {
 
     /**
      * Gets the If-Match (ETag) associated with the operation in CosmosBatch.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return ifMatchETag the ifMatchETag associated with the request.
      */
@@ -31,6 +34,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the operation in CosmosBatch.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options
@@ -42,6 +48,11 @@ public CosmosBatchItemRequestOptions setIfMatchETag(final String ifMatchETag) {
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in operation in CosmosBatch.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -51,6 +62,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in operation in CosmosBatch.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchEtag the ifNoneMatchETag associated with the request.
      * @return the current request options

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosBatchPatchItemRequestOptions.java

@@ -42,6 +42,9 @@ public CosmosBatchPatchItemRequestOptions setFilterPredicate(String filterPredic
 
     /**
      * Gets the If-Match (ETag) associated with the operation in CosmosBatch.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return ifMatchETag the ifMatchETag associated with the request.
      */
@@ -51,6 +54,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the operation in CosmosBatch.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options
@@ -62,6 +68,11 @@ public CosmosBatchPatchItemRequestOptions setIfMatchETag(final String ifMatchETa
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in operation in CosmosBatch.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -71,6 +82,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in operation in CosmosBatch.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchEtag the ifNoneMatchETag associated with the request.
      * @return the current request options

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosBulkItemRequestOptions.java

@@ -23,6 +23,9 @@ public CosmosBulkItemRequestOptions() {
 
     /**
      * Gets the If-Match (ETag) associated with the operation in {@link CosmosItemOperation}.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return ifMatchETag the ifMatchETag associated with the request.
      */
@@ -32,6 +35,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the operation in {@link CosmosItemOperation}.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options
@@ -43,6 +49,11 @@ public CosmosBulkItemRequestOptions setIfMatchETag(final String ifMatchETag) {
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in operation in {@link CosmosItemOperation}.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -52,6 +63,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in operation in {@link CosmosItemOperation}.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchEtag the ifNoneMatchETag associated with the request.
      * @return the current request options.

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosBulkPatchItemRequestOptions.java

@@ -85,6 +85,11 @@ public CosmosBulkPatchItemRequestOptions setContentResponseOnWriteEnabled(Boolea
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in operation in {@link CosmosItemOperation}.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -94,6 +99,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in operation in {@link CosmosItemOperation}.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchEtag the ifNoneMatchETag associated with the request.
      * @return the current request options.
@@ -105,6 +115,9 @@ public CosmosBulkPatchItemRequestOptions setIfNoneMatchETag(final String ifNoneM
 
     /**
      * Gets the If-Match (ETag) associated with the operation in {@link CosmosItemOperation}.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return ifMatchETag the ifMatchETag associated with the request.
      */
@@ -114,6 +127,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the operation in {@link CosmosItemOperation}.
+     * Most commonly used with replace, upsert and delete requests.
+     * This will be ignored if specified for create requests or for upsert requests if the item doesn't exist.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosConflictRequestOptions.java

@@ -28,6 +28,9 @@ public CosmosConflictRequestOptions(PartitionKey partitionKey) {
 
     /**
      * Gets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used with replace and delete requests.
+     * This will be ignored if specified for create requests.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return ifMatchETag the ifMatchETag associated with the request.
      */
@@ -37,6 +40,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used with replace and delete requests.
+     * This will be ignored if specified for create requests.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options
@@ -48,6 +54,11 @@ public CosmosConflictRequestOptions setIfMatchETag(String ifMatchETag) {
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -57,6 +68,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchEtag the ifNoneMatchETag associated with the request.
      * @return the current request options

sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/models/CosmosContainerRequestOptions.java

@@ -82,6 +82,9 @@ public CosmosContainerRequestOptions setSessionToken(String sessionToken) {
 
     /**
      * Gets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used with replace and delete requests.
+     * This will be ignored if specified for create requests.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifMatchETag associated with the request.
      */
@@ -91,6 +94,9 @@ public String getIfMatchETag() {
 
     /**
      * Sets the If-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used with replace and delete requests.
+     * This will be ignored if specified for create requests.
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifMatchETag the ifMatchETag associated with the request.
      * @return the current request options
@@ -102,6 +108,11 @@ public CosmosContainerRequestOptions setIfMatchETag(String ifMatchETag) {
 
     /**
      * Gets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @return the ifNoneMatchETag associated with the request.
      */
@@ -111,6 +122,11 @@ public String getIfNoneMatchETag() {
 
     /**
      * Sets the If-None-Match (ETag) associated with the request in the Azure Cosmos DB service.
+     * Most commonly used to detect changes to the resource via read requests.
+     * When Item Etag matches the specified ifNoneMatchETag then 304 status code will be returned, otherwise existing Item will be returned with 200.
+     * To match any Etag use "*"
+     * This will be ignored if specified for write requests (ex: Create, Replace, Delete).
+     * For more details, refer to <a href="https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency#implementing-optimistic-concurrency-control-using-etag-and-http-headers">optimistic concurrency control documentation</a>
      *
      * @param ifNoneMatchETag the ifNoneMatchETag associated with the request.
      * @return the current request options