Deprecated PartitionedHttpClientBuilder and partition client APIs (#…

…2131)

Motivation:

`PartitionedHttpClientBuilder` is hard to use because it requires
implementation of a special `ServiceDiscoverer` that we do not provide
OOTB. We are unaware of anyone using this feature, but if there are any
users they should consider `ClientGroup` as an alternative or reach out
to us to provide more context why the `PartitionedHttpClientBuilder` is
required.

Modifications:

- Deprecate `PartitionedHttpClientBuilder` and
`HttpClients.forPartitionedAddress`;
- Deprecate everything in `io.servicetalk.client.api.partition` package

Result:

`PartitionedHttpClientBuilder` is deprecated and can be removed in
future releases.

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/ClosedPartitionException.java

@@ -15,12 +15,19 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
+
 import static java.util.Objects.requireNonNull;
 
 /**
  * Thrown when a request is issued against a valid partition that was closed after selection.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public final class ClosedPartitionException extends IllegalStateException {
+@Deprecated
+public final class ClosedPartitionException extends IllegalStateException { // FIXME: 0.43 - remove deprecated class
 
     private static final long serialVersionUID = 9006673188565077317L;
 

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/DuplicateAttributeException.java

@@ -15,14 +15,20 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.client.api.partition.PartitionAttributes.Key;
 
 import static java.util.Objects.requireNonNull;
 
 /**
  * Indicates that a duplicate value was added while constructing a {@link PartitionAttributes}.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public final class DuplicateAttributeException extends IllegalStateException {
+@Deprecated
+public final class DuplicateAttributeException extends IllegalStateException {  // FIXME: 0.43 - remove deprecated class
     private static final long serialVersionUID = 8374128121212690894L;
 
     private final Key key;

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/PartitionAttributes.java

@@ -15,6 +15,8 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
+
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.BiConsumer;
 import javax.annotation.Nullable;
@@ -30,8 +32,13 @@
  * { [Key(shard) = "shard X"], [Key(data center) = "data center X"], [Key(is main) = "false/true"] }
  * </pre>
  * This construct allows for the attributes to partially specify a partition and preform "wild card" type matching.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionAttributes {
+@Deprecated
+public interface PartitionAttributes {  // FIXME: 0.43 - remove deprecated interface
     /**
      * A key identifies a specific object in a {@link PartitionAttributes}.
      * @param <T> The type of value associated with a {@link PartitionAttributes.Key}.

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/PartitionAttributesBuilder.java

@@ -15,11 +15,18 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
+
 /**
  * A builder for {@link PartitionAttributes} objects. Duplicates are not necessarily detected/enforced via the
  * {@link #add(PartitionAttributes.Key, Object)} method.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionAttributesBuilder {
+@Deprecated
+public interface PartitionAttributesBuilder {   // FIXME: 0.43 - remove deprecated interface
     /**
      * Add a key/value pair to this builder.
      * <p>

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/PartitionMap.java

@@ -15,6 +15,7 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.client.api.ServiceDiscoverer;
 import io.servicetalk.concurrent.api.AsyncCloseable;
 import io.servicetalk.concurrent.api.ListenableAsyncCloseable;
@@ -25,9 +26,15 @@
 /**
  * A map like interface which manages {@link PartitionAttributes} that are fully specified and returns the corresponding
  * partitions those {@link PartitionAttributes} belong to.
+ *
  * @param <T> The value object which represents the partition.
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionMap<T extends AsyncCloseable> extends ListenableAsyncCloseable {
+@Deprecated
+public interface PartitionMap<T extends AsyncCloseable> // FIXME: 0.43 - remove deprecated interface
+        extends ListenableAsyncCloseable {
     /**
      * Add a new {@link PartitionAttributes} that is absolutely specified. This may create new partitions.
      * <p>

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/PartitionMapFactory.java

@@ -15,14 +15,20 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.concurrent.api.AsyncCloseable;
 
 import java.util.function.Function;
 
 /**
  * A generic factory for {@link PartitionMap} objects.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionMapFactory {
+@Deprecated
+public interface PartitionMapFactory {  // FIXME: 0.43 - remove deprecated interface
     /**
      * Create a new {@link PartitionMap} object.
      * @param valueFactory The factory used to create new partitions.

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/PartitionedServiceDiscovererEvent.java

@@ -15,13 +15,20 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.client.api.ServiceDiscovererEvent;
 
 /**
  * An {@link ServiceDiscovererEvent} which is associated with a partition.
+ *
  * @param <ResolvedAddress> The type of resolved address.
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionedServiceDiscovererEvent<ResolvedAddress> extends ServiceDiscovererEvent<ResolvedAddress> {
+@Deprecated
+public interface PartitionedServiceDiscovererEvent<ResolvedAddress> // FIXME: 0.43 - remove deprecated interface
+        extends ServiceDiscovererEvent<ResolvedAddress> {
     /**
      * Get the fully specified {@link PartitionAttributes} that uniquely identifies {@link #address()}.
      * @return the fully specified {@link PartitionAttributes} that uniquely identifies {@link #address()}.

servicetalk-client-api/src/main/java/io/servicetalk/client/api/partition/UnknownPartitionException.java

@@ -15,12 +15,19 @@
  */
 package io.servicetalk.client.api.partition;
 
+import io.servicetalk.client.api.ClientGroup;
+
 import static java.util.Objects.requireNonNull;
 
 /**
  * Thrown when a request is issued but there is no associated partition to send the request to.
+ *
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public final class UnknownPartitionException extends IllegalStateException {
+@Deprecated
+public final class UnknownPartitionException extends IllegalStateException {    // FIXME: 0.43 - remove deprecated class
     private static final long serialVersionUID = 2870933612596267788L;
 
     private final PartitionAttributes partitionSelector;

servicetalk-http-api/src/main/java/io/servicetalk/http/api/PartitionedHttpClientBuilder.java

@@ -16,6 +16,7 @@
 package io.servicetalk.http.api;
 
 import io.servicetalk.buffer.api.BufferAllocator;
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.client.api.ServiceDiscoverer;
 import io.servicetalk.client.api.ServiceDiscovererEvent;
 import io.servicetalk.client.api.partition.PartitionAttributes;
@@ -36,8 +37,13 @@
  * could be overridden to address specific use cases.
  * @param <U> the type of address before resolution (unresolved address)
  * @param <R> the type of address after resolution (resolved address)
+ * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+ * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers describing
+ * the use-case.
  */
-public interface PartitionedHttpClientBuilder<U, R> extends HttpClientBuilder<U, R, ServiceDiscovererEvent<R>> {
+@Deprecated
+public interface PartitionedHttpClientBuilder<U, R> // FIXME: 0.43 - remove deprecated interface
+        extends HttpClientBuilder<U, R, ServiceDiscovererEvent<R>> {
     /**
      * Initializes the {@link SingleAddressHttpClientBuilder} for each new client.
      * @param <U> the type of address before resolution (unresolved address)

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/HttpClients.java

@@ -15,6 +15,7 @@
  */
 package io.servicetalk.http.netty;
 
+import io.servicetalk.client.api.ClientGroup;
 import io.servicetalk.client.api.LoadBalancer;
 import io.servicetalk.client.api.ServiceDiscoverer;
 import io.servicetalk.client.api.ServiceDiscovererEvent;
@@ -220,7 +221,11 @@ public static <U, R> SingleAddressHttpClientBuilder<U, R> forSingleAddress(
      * @param <U> the type of address before resolution (unresolved address)
      * @param <R> the type of address after resolution (resolved address)
      * @return new builder with provided configuration
+     * @deprecated We are unaware of anyone using "partition" feature and plan to remove it in future releases.
+     * If you depend on it, consider using {@link ClientGroup} as an alternative or reach out to the maintainers
+     * describing the use-case.
      */
+    @Deprecated // FIXME: 0.43 - remove deprecated method
     public static <U, R> PartitionedHttpClientBuilder<U, R> forPartitionedAddress(
             final ServiceDiscoverer<U, R, PartitionedServiceDiscovererEvent<R>> serviceDiscoverer,
             final U address,