Small improvements and rewording for HTTP LoadBalancer example (#3115)

Motivations:

1. This is the only example that currently doesn't have an override for
its gradle module name in `settings.gradle`.
2. While internally we name it `DefaultLoadBalancer`, this type is not
public. We should use publicly available names to make it easier for
users to relate.
3. In preparation to promoting this LB from experimental package, word
it such that it's the only LB users should use/customize.

Modifications:

- Rename module & package `defaultloadbalancer` to `loadbalancer`,
`DefaultLoadBalancerClient` to `CustomLoadBalancerClient`.
- Assign module name to `servicetalk-examples-http-loadbalancer`.
- Update javadoc, docs, links.

servicetalk-examples/docs/modules/ROOT/pages/_partials/nav-versioned.adoc

@@ -12,7 +12,7 @@
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#HTTP2[HTTP/2]
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#Mutual-TLS[Mutual TLS]
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#Observer[Observer]
-** xref:{page-version}@servicetalk-examples::http/index.adoc#DefaultLoadBalancer[DefaultLoadBalancer]
+** xref:{page-version}@servicetalk-examples::http/index.adoc#LoadBalancer[LoadBalancer]
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#OpenTracing[OpenTracing]
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#Redirects[Redirects]
 ** xref:{page-version}@servicetalk-examples::http/index.adoc#Retries[Retries]

servicetalk-examples/docs/modules/ROOT/pages/http/index.adoc

@@ -234,17 +234,19 @@ on via a client filter on the client builder.
 link:{source-root}/servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpLifecycleObserver.java[HttpLifecycleObserver]
 on via a client filter on the client builder.
 
-[#DefaultLoadBalancer]
-== DefaultLoadBalancer
-This example demonstrates how to use the experimental link:{source-root}/servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/DefaultLoadBalancer.java[DefaultLoadBalancer]:
+[#LoadBalancer]
+== LoadBalancer
+This example demonstrates how to use and configure the experimental link:{source-root}/servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancers.java[LoadBalancers]:
 
-- by setting the load balancer to DefaultLoadBalancer for a HTTP client
-- configuring xDS failure detection for that client using default settings
+- by using link:{source-root}/servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancerBuilder.java[LoadBalancerBuilder] to customize its setting:
+  * configuring a different link:{source-root}/servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/LoadBalancingPolicy.java[LoadBalancingPolicy]
+  * configuring xDS failure detection using link:{source-root}/servicetalk-loadbalancer-experimental/src/main/java/io/servicetalk/loadbalancer/OutlierDetectorConfig.java[OutlierDetectorConfig]
+- by using link:{source-root}/servicetalk-http-api/src/main/java/io/servicetalk/http/api/DefaultHttpLoadBalancerFactory.java[DefaultHttpLoadBalancerFactory] to adapt a LoadBalancer to HTTP and configure it via client builder
 
 Using the following classes:
 
-- link:{source-root}/servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/DefaultLoadBalancerClient.java[DefaultLoadBalancerClient] - A client that uses the DefaultLoadBalancer.
-- link:{source-root}/servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/HelloWorldServer.java[HelloWorldServer] - A simple server implementation.
+- link:{source-root}/servicetalk-examples/http/loadbalancer/src/main/java/io/servicetalk/examples/http/loadbalancer/CustomLoadBalancerClient.java[CustomLoadBalancerClient] - A client that configures custom settings for its LoadBalancer.
+- link:{source-root}/servicetalk-examples/http/loadbalancer/src/main/java/io/servicetalk/examples/http/loadbalancer/HelloWorldServer.java[HelloWorldServer] - A simple server implementation.
 
 NOTE: DefaultLoadBalancer is currently considered experimental and therefore the API is subject to change.
 

servicetalk-examples/http/loadbalancer/README.adoc

@@ -0,0 +1,4 @@
+== ServiceTalk LoadBalancer Example
+
+A simple hello-world style application that uses a client that configures custom settings for its LoadBalancer and
+xDS style outlier detection.

servicetalk-examples/http/defaultloadbalancer/build.gradle → servicetalk-examples/http/loadbalancer/build.gradle

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2019 Apple Inc. and the ServiceTalk project authors
+ * Copyright © 2024 Apple Inc. and the ServiceTalk project authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/DefaultLoadBalancerClient.java → servicetalk-examples/http/loadbalancer/src/main/java/io/servicetalk/examples/http/loadbalancer/CustomLoadBalancerClient.java

@@ -13,33 +13,33 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.servicetalk.examples.http.defaultloadbalancer;
+package io.servicetalk.examples.http.loadbalancer;
 
 import io.servicetalk.client.api.LoadBalancerFactory;
 import io.servicetalk.http.api.BlockingHttpClient;
 import io.servicetalk.http.api.DefaultHttpLoadBalancerFactory;
 import io.servicetalk.http.api.FilterableStreamingHttpLoadBalancedConnection;
 import io.servicetalk.http.api.HttpResponse;
-import io.servicetalk.http.api.SingleAddressHttpClientBuilder;
 import io.servicetalk.http.netty.HttpClients;
-import io.servicetalk.loadbalancer.LoadBalancingPolicies;
 import io.servicetalk.loadbalancer.LoadBalancers;
+import io.servicetalk.loadbalancer.LoadBalancingPolicies;
 import io.servicetalk.loadbalancer.OutlierDetectorConfig;
-import io.servicetalk.transport.api.HostAndPort;
 
 import java.net.InetSocketAddress;
 
 import static io.servicetalk.http.api.HttpSerializers.textSerializerUtf8;
 import static java.time.Duration.ofSeconds;
 
-public final class DefaultLoadBalancerClient {
+/**
+ * A client that configures custom settings for its LoadBalancer.
+ */
+public final class CustomLoadBalancerClient {
 
     public static void main(String[] args) throws Exception {
-        SingleAddressHttpClientBuilder<HostAndPort, InetSocketAddress> builder =
-                HttpClients.forSingleAddress("localhost", 8080)
+        try (BlockingHttpClient client = HttpClients.forSingleAddress("localhost", 8080)
                 .loadBalancerFactory(new DefaultHttpLoadBalancerFactory<>(
-                        loadBalancer("localhost-defaultloadbalancer")));
-        try (BlockingHttpClient client = builder.buildBlocking()) {
+                        loadBalancer("my-custom-loadbalancer")))
+                .buildBlocking()) {
             HttpResponse response = client.request(client.get("/sayHello"));
             System.out.println(response.toString((name, value) -> value));
             System.out.println(response.payloadBody(textSerializerUtf8()));
@@ -48,10 +48,9 @@ public static void main(String[] args) throws Exception {
 
     private static LoadBalancerFactory<InetSocketAddress, FilterableStreamingHttpLoadBalancedConnection> loadBalancer(
             String id) {
-        return LoadBalancers.<InetSocketAddress, FilterableStreamingHttpLoadBalancedConnection>
-                builder(id)
+        return LoadBalancers.<InetSocketAddress, FilterableStreamingHttpLoadBalancedConnection>builder(id)
                 .loadBalancingPolicy(
-                        // DefaultLoadBalancer supports multiple patterns for selecting hosts including
+                        // LoadBalancerBuilder supports multiple patterns for selecting hosts including
                         // - Round robin: linear iteration through the host list, skipping unhealthy hosts, per request.
                         // - Power of two choices (P2C): randomly select two hosts and take the best based on score.
                         // Both policies consider outlier detection (see below) but only P2C can bias traffic toward

servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/HelloWorldServer.java → servicetalk-examples/http/loadbalancer/src/main/java/io/servicetalk/examples/http/loadbalancer/HelloWorldServer.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package io.servicetalk.examples.http.defaultloadbalancer;
+package io.servicetalk.examples.http.loadbalancer;
 
 import io.servicetalk.http.netty.HttpServers;
 

servicetalk-examples/http/defaultloadbalancer/src/main/java/io/servicetalk/examples/http/defaultloadbalancer/package-info.java → servicetalk-examples/http/loadbalancer/src/main/java/io/servicetalk/examples/http/loadbalancer/package-info.java

@@ -14,6 +14,6 @@
  * limitations under the License.
  */
 @ElementsAreNonnullByDefault
-package io.servicetalk.examples.http.defaultloadbalancer;
+package io.servicetalk.examples.http.loadbalancer;
 
 import io.servicetalk.annotations.ElementsAreNonnullByDefault;

settings.gradle

@@ -78,7 +78,7 @@ include "servicetalk-annotations",
         "servicetalk-examples:http:compression",
         "servicetalk-examples:http:debugging",
         "servicetalk-examples:http:timeout",
-        "servicetalk-examples:http:defaultloadbalancer",
+        "servicetalk-examples:http:loadbalancer",
         "servicetalk-examples:http:files",
         "servicetalk-gradle-plugin-internal",
         "servicetalk-grpc-api",
@@ -150,6 +150,7 @@ project(":servicetalk-examples:http:helloworld").name = "servicetalk-examples-ht
 project(":servicetalk-examples:http:debugging").name = "servicetalk-examples-http-debugging"
 project(":servicetalk-examples:http:timeout").name = "servicetalk-examples-http-timeout"
 project(":servicetalk-examples:http:jaxrs").name = "servicetalk-examples-http-jaxrs"
+project(":servicetalk-examples:http:loadbalancer").name = "servicetalk-examples-http-loadbalancer"
 project(":servicetalk-examples:http:metadata").name = "servicetalk-examples-http-metadata"
 project(":servicetalk-examples:http:opentracing").name = "servicetalk-examples-http-opentracing"
 project(":servicetalk-examples:http:observer").name = "servicetalk-examples-http-observer"