Add client-level excluded regions and make it mutable.

[jeet1995]

Description

This PR introduces a way to inject a set of excluded regions at the client-level through a custom Supplier type.

Configuring the Supplier

Configure the Supplier with CosmosClientBuilder.

// store the set of excluded regions
AtomicReference<CosmosExcludedRegions> cosmosExcludedRegionsAtomicReference 
= new AtomicReference<>(new CosmosExcludedRegions(new HashSet<>()));

CosmosAsyncClient cosmosAsyncClientWithExcludeRegions = new CosmosClientBuilder()
          .endpoint("<account URL goes here")
          .key("<account key goes here>")
          .endpointDiscoveryEnabled(true)
          .preferredRegions(Arrays.asList("East US", "South Central US", "West US"))
          .excludedRegionsSupplier(() -> cosmosExcludedRegionsAtomicReference.get())
          .buildAsyncClient();

List<String> excludedRegions = Arrays.asList("South Central US");

// modify the set of excluded regions
cosmosExcludedRegionsAtomicReference.set(new CosmosExcludedRegions(new HashSet<>(excludedRegions)));

• NOTE: The supplier passed through excludedRegionsSupplier() should implement Supplier<CosmosExcludedRegions>.

CosmosExcludedRegions class structure

• The below class is part of the public API surface which is used to encapsulate a set of excluded regions. The downstream application can also use this class to get back the set.
• NOTE: The set of excluded regions passed through the constructor should not be null.

public final class CosmosExcludedRegions {
    private final Set<String> excludedRegions;
    private final String excludedRegionsAsString;
    private static final Pattern SPACE_PATTERN = Pattern.compile(" ");

    public CosmosExcludedRegions(Set<String> excludedRegions) {
        checkArgument(excludedRegions != null, "excludedRegions cannot be set to null");
        
        this.excludedRegions = new HashSet<>(excludedRegions);
        this.excludedRegionsAsString = stringifyExcludedRegions(this.excludedRegions);
    }

    public Set<String> getExcludedRegions() {

        if (this.excludedRegions == null || this.excludedRegions.isEmpty()) {
            return new HashSet<>();
        }

        return new HashSet<>(this.excludedRegions);
    }

    @Override
    public String toString() {
        return this.excludedRegionsAsString;
    }

    private static String stringifyExcludedRegions(Set<String> excludedRegions) {
        String substring = "";

        if (excludedRegions == null || excludedRegions.isEmpty()) {
            substring =  "";
        } else {
            substring = excludedRegions
                .stream()
                .map(r -> SPACE_PATTERN.matcher(r.toLowerCase(Locale.ROOT)).replaceAll(""))
                .collect(Collectors.joining(","));
        }

        return "[" + substring + "]";
    }
}

[azure-sdk]

API change check

APIView has identified API level changes in this PR and created following API reviews.

azure-cosmos

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[kushagraThapar]

LGTM with some questions, thanks @jeet1995 for the changes!

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jeet1995]

/azp run java - cosmos - tests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[FabianMeiswinkel]

I guess you clone the Set here to avoid allwoign modifications on it?

For perf reasons ou internal API shoudl avoid the cloning - either via internal property getter that returns the raw set or by creating an ImmutableSet in the ctor when you clone the Set passed into the struct.

[FabianMeiswinkel]

LGTM except for the comment around why we have to create new Sets all the time.

[FabianMeiswinkel]

LGTM - Thanks!