Deprecates builder classes' constructors over builder methods (line#2348

)

Related: line#2221 

* Makes user to use ServerListener.builder() to get ServerListenerBuilder
* Makes user to use SimpleCompositeService.builder() to get SimplecompositeServiceBuilder
* Makes user to use SimpleCompositeRpcService.builder() to get SimplecompositeRpcServiceBuilder
* Makes user to use CorsPolicy.builder() to get CorsPolicyBuilder
* Makes user to use DocService.builder() to get DocServiceBuilder
* Makes user to use LoggingService.builder() to get LoggingServiceBuilder
* Makes user to use JettyService.builder() to get JettyServiceBuilder
* Makes user to use SamlServiceProvider.builder() to get SamlServiceProviderBuilder
* Makes user to use ZooKeeperUpdatingListener.builder() to get ZooKeeperUpdatingListenerBuilder

core/src/main/java/com/linecorp/armeria/server/ServerListener.java

@@ -23,6 +23,14 @@
  * @see Server#removeListener(ServerListener)
  */
 public interface ServerListener {
+
+    /**
+     * Returns a new {@link ServerListenerBuilder}.
+     */
+    static ServerListenerBuilder builder() {
+        return new ServerListenerBuilder();
+    }
+
     /**
      * Invoked when a {@link Server} begins its startup procedure. Note that the {@link Server} will abort
      * its startup when a {@link ServerListener#serverStarting(Server)} throws an exception.

core/src/main/java/com/linecorp/armeria/server/ServerListenerBuilder.java

@@ -29,7 +29,7 @@
  * Builds a new {@link ServerListener}.
  * <h2>Example</h2>
  * <pre>{@code
- * ServerListenerBuilder slb = new ServerListenerBuilder();
+ * ServerListenerBuilder slb = ServerListener.builder();
  * // Add a {@link ServerListener#serverStarting(Server)} callback.
  * slb.addStartingCallback((Server server) -> {...});
  * // Add multiple {@link ServerListener#serverStarted(Server)} callbacks, one by one.
@@ -68,6 +68,14 @@ public final class ServerListenerBuilder {
      * */
     private final List<Consumer<? super Server>> serverStoppedCallbacks = new ArrayList<>();
 
+    /**
+     * Creates a new {@link ServerListenerBuilder}.
+     *
+     * @deprecated Use {@link ServerListener#builder()}.
+     */
+    @Deprecated
+    public ServerListenerBuilder() {}
+
     private static class CallbackServerListener implements ServerListener {
         /**
          * {@link Consumer}s invoked when the {@link Server} is starting.

core/src/main/java/com/linecorp/armeria/server/composition/SimpleCompositeRpcService.java

@@ -31,6 +31,13 @@
 public final class SimpleCompositeRpcService
         extends AbstractCompositeService<RpcService, RpcRequest, RpcResponse> implements RpcService {
 
+    /**
+     * Returns a new {@link SimpleCompositeRpcServiceBuilder}.
+     */
+    public static SimpleCompositeRpcServiceBuilder builder() {
+        return new SimpleCompositeRpcServiceBuilder();
+    }
+
     /**
      * Creates a new instance that is composed of the specified entries.
      */

core/src/main/java/com/linecorp/armeria/server/composition/SimpleCompositeRpcServiceBuilder.java

@@ -25,6 +25,14 @@
  */
 public final class SimpleCompositeRpcServiceBuilder extends AbstractCompositeServiceBuilder<RpcService> {
 
+    /**
+     * Creates a new {@link SimpleCompositeRpcServiceBuilder}.
+     *
+     * @deprecated Use {@link SimpleCompositeRpcService#builder()}.
+     */
+    @Deprecated
+    public SimpleCompositeRpcServiceBuilder() {}
+
     @Override
     public SimpleCompositeRpcServiceBuilder serviceUnder(String pathPrefix, RpcService service) {
         return (SimpleCompositeRpcServiceBuilder) super.serviceUnder(pathPrefix, service);

core/src/main/java/com/linecorp/armeria/server/composition/SimpleCompositeService.java

@@ -31,6 +31,13 @@
 public final class SimpleCompositeService
         extends AbstractCompositeService<HttpService, HttpRequest, HttpResponse> implements HttpService {
 
+    /**
+     * Returns a new {@link SimpleCompositeServiceBuilder}.
+     */
+    public static SimpleCompositeServiceBuilder builder() {
+        return new SimpleCompositeServiceBuilder();
+    }
+
     /**
      * Creates a new instance that is composed of the specified entries.
      */

core/src/main/java/com/linecorp/armeria/server/composition/SimpleCompositeServiceBuilder.java

@@ -25,6 +25,14 @@
  */
 public final class SimpleCompositeServiceBuilder extends AbstractCompositeServiceBuilder<HttpService> {
 
+    /**
+     * Creates a new {@link SimpleCompositeServiceBuilder}.
+     *
+     * @deprecated Use {@link SimpleCompositeService#builder()}.
+     */
+    @Deprecated
+    public SimpleCompositeServiceBuilder() {}
+
     @Override
     public SimpleCompositeServiceBuilder serviceUnder(String pathPrefix, HttpService  service) {
         return (SimpleCompositeServiceBuilder) super.serviceUnder(pathPrefix, service);

core/src/main/java/com/linecorp/armeria/server/cors/CorsDecoratorsFactoryFunction.java

@@ -42,7 +42,7 @@ public final class CorsDecoratorsFactoryFunction implements DecoratorFactoryFunc
         }
         cb.firstPolicyBuilder.setConfig(corsDecorator);
         for (int i = 1; i < policies.length; i++) {
-            final CorsPolicyBuilder builder = new CorsPolicyBuilder(policies[i].origins());
+            final CorsPolicyBuilder builder = CorsPolicy.builder(policies[i].origins());
             builder.setConfig(policies[i]);
             cb.addPolicy(builder.build());
         }

core/src/main/java/com/linecorp/armeria/server/cors/CorsPolicy.java

@@ -53,6 +53,28 @@ public final class CorsPolicy {
 
     private static final String DELIMITER = ",";
     private static final Joiner HEADER_JOINER = Joiner.on(DELIMITER);
+
+    /**
+     * Returns a new {@link CorsPolicyBuilder}.
+     */
+    public static CorsPolicyBuilder builder() {
+        return new CorsPolicyBuilder();
+    }
+
+    /**
+     * Returns a new {@link CorsPolicyBuilder} with the specified {@code origins}.
+     */
+    public static CorsPolicyBuilder builder(String... origins) {
+        return new CorsPolicyBuilder(origins);
+    }
+
+    /**
+     * Returns a new {@link CorsPolicyBuilder} with the specified {@code origins}.
+     */
+    public static CorsPolicyBuilder builder(Iterable<String> origins) {
+        return new CorsPolicyBuilder(origins);
+    }
+
     private final Set<String> origins;
     private final List<Route> routes;
     private final boolean credentialsAllowed;

core/src/main/java/com/linecorp/armeria/server/cors/CorsPolicyBuilder.java

@@ -21,7 +21,7 @@
  * Builds a new {@link CorsPolicy}.
  * <h2>Example</h2>
  * <pre>{@code
- * CorsPolicyBuilder cb = new CorsPolicyBuilder("http://example.com");
+ * CorsPolicyBuilder cb = CorsPolicy.builder("http://example.com");
  * cb.allowRequestMethods(HttpMethod.POST, HttpMethod.GET)
  *   .allowRequestHeaders("allow_request_header")
  *   .exposeHeaders("expose_header_1", "expose_header_2")
@@ -31,16 +31,31 @@
  *
  */
 public final class CorsPolicyBuilder extends AbstractCorsPolicyBuilder<CorsPolicyBuilder> {
+
+    /**
+     * Creates a new instance {@link CorsPolicyBuilder}.
+     *
+     * @deprecated Use {@link CorsPolicy#builder()}.
+     */
+    @Deprecated
+    public CorsPolicyBuilder() {}
+
     /**
      * Creates a new instance with the specified {@code origins}.
+     *
+     * @deprecated Use {@link CorsPolicy#builder(String...)}.
      */
+    @Deprecated
     public CorsPolicyBuilder(String... origins) {
         super(ImmutableList.copyOf(origins));
     }
 
     /**
      * Creates a new instance with the specified {@code origins}.
+     *
+     * @deprecated Use {@link CorsPolicy#builder(Iterable)}.
      */
+    @Deprecated
     public CorsPolicyBuilder(Iterable<String> origins) {
         super(ImmutableList.copyOf(origins));
     }

core/src/main/java/com/linecorp/armeria/server/docs/DocService.java

@@ -90,6 +90,13 @@ public class DocService extends AbstractCompositeService<HttpService, HttpReques
     static final List<DocServicePlugin> plugins = Streams.stream(ServiceLoader.load(
             DocServicePlugin.class, DocService.class.getClassLoader())).collect(toImmutableList());
 
+    /**
+     * Returns a new {@link DocServiceBuilder}.
+     */
+    public static DocServiceBuilder builder() {
+        return new DocServiceBuilder();
+    }
+
     private final Map<String, ListMultimap<String, HttpHeaders>> exampleHttpHeaders;
     private final Map<String, ListMultimap<String, String>> exampleRequests;
     private final DocServiceFilter filter;

core/src/main/java/com/linecorp/armeria/server/docs/DocServiceBuilder.java

@@ -59,6 +59,14 @@ public final class DocServiceBuilder {
     private final List<BiFunction<ServiceRequestContext, HttpRequest, String>> injectedScriptSuppliers =
             new ArrayList<>();
 
+    /**
+     * Creates a new {@link DocServiceBuilder}.
+     *
+     * @deprecated Use {@link DocService#builder()}.
+     */
+    @Deprecated
+    public DocServiceBuilder() {}
+
     /**
      * Adds the example {@link HttpHeaders} which are applicable to any services.
      */

core/src/main/java/com/linecorp/armeria/server/docs/DocServiceFilter.java

@@ -28,7 +28,7 @@
  *
  * <pre>{@code
  * // Include Thrift and gRPC only.
- * DocServiceBuilder builder = new DocServiceBuilder();
+ * DocServiceBuilder builder = DocService.builder();
  * DocServiceFilter filter = DocServiceFilter.ofThrift().or(DocServiceFilter.ofGrpc());
  * builder.include(filter);
  *

core/src/main/java/com/linecorp/armeria/server/logging/LoggingServiceBuilder.java

@@ -33,6 +33,14 @@ public final class LoggingServiceBuilder extends LoggingDecoratorBuilder<Logging
 
     private Sampler<? super ServiceRequestContext> sampler = Sampler.always();
 
+    /**
+     * Creates a new {@link LoggingServiceBuilder}.
+     *
+     * @deprecated Use {@link LoggingService#builder()}.
+     */
+    @Deprecated
+    public LoggingServiceBuilder() {}
+
     /**
      * Sets the {@link Sampler} that determines which request needs logging.
      */

core/src/test/java/com/linecorp/armeria/internal/annotation/AnnotatedDocServiceTest.java

@@ -75,7 +75,7 @@
 import com.linecorp.armeria.server.annotation.Put;
 import com.linecorp.armeria.server.annotation.ResponseConverter;
 import com.linecorp.armeria.server.annotation.Trace;
-import com.linecorp.armeria.server.docs.DocServiceBuilder;
+import com.linecorp.armeria.server.docs.DocService;
 import com.linecorp.armeria.server.docs.DocServiceFilter;
 import com.linecorp.armeria.server.docs.EndpointInfo;
 import com.linecorp.armeria.server.docs.FieldInfo;
@@ -102,19 +102,19 @@ protected void configure(ServerBuilder sb) throws Exception {
                 sb.http(8080);
             }
             sb.annotatedService("/service", new MyService());
-            sb.serviceUnder("/docs", new DocServiceBuilder()
-                    .exampleHttpHeaders(EXAMPLE_HEADERS_ALL)
-                    .exampleHttpHeaders(MyService.class, EXAMPLE_HEADERS_SERVICE)
-                    .exampleHttpHeaders(MyService.class, "pathParams", EXAMPLE_HEADERS_METHOD)
-                    .exampleRequestForMethod(MyService.class, "pathParams",
-                                             ImmutableList.of(mapper.readTree(
-                                                     "{\"hello\":\"armeria\"}")))
-                    .exclude(DocServiceFilter.ofMethodName(MyService.class.getName(), "exclude1").or(
-                            DocServiceFilter.ofMethodName(MyService.class.getName(), "exclude2")))
-                    .build());
-            sb.serviceUnder("/excludeAll/", new DocServiceBuilder()
-                    .exclude(DocServiceFilter.ofAnnotated())
-                    .build());
+            sb.serviceUnder("/docs",
+                    DocService.builder()
+                              .exampleHttpHeaders(EXAMPLE_HEADERS_ALL)
+                              .exampleHttpHeaders(MyService.class, EXAMPLE_HEADERS_SERVICE)
+                              .exampleHttpHeaders(MyService.class,"pathParams", EXAMPLE_HEADERS_METHOD)
+                              .exampleRequestForMethod(MyService.class, "pathParams",
+                                             ImmutableList.of(mapper.readTree("{\"hello\":\"armeria\"}")))
+                              .exclude(DocServiceFilter.ofMethodName(MyService.class.getName(), "exclude1").or(
+                                       DocServiceFilter.ofMethodName(MyService.class.getName(), "exclude2")))
+                              .build());
+            sb.serviceUnder("/excludeAll/", DocService.builder()
+                                                      .exclude(DocServiceFilter.ofAnnotated())
+                                                      .build());
         }
     };
 

core/src/test/java/com/linecorp/armeria/server/ServerListenerTest.java

@@ -40,20 +40,26 @@ protected void configure(ServerBuilder sb) {
               .service("/", (req, ctx) -> HttpResponse.of("Hello!"));
 
             // Record when the method triggered
-            final ServerListener sl = new ServerListenerBuilder()
-                    // add a callback.
-                    .addStartingCallback((Server server) -> STARTING_AT = System.currentTimeMillis())
-                    // add multiple callbacks, one by one.
-                    .addStartedCallback((Server server) -> STARTED_AT = -1)
-                    .addStartedCallback((Server server) -> STARTED_AT = System.currentTimeMillis())
-                    // add multiple callbacks at once, with vargs api.
-                    .addStoppingCallbacks((Server server) -> STOPPING_AT = System.currentTimeMillis(),
-                                          (Server server) -> STARTING_AT = 0L)
-                    // add multiple callbacks at once, with iterable api.
-                    .addStoppedCallbacks(
-                            Lists.newArrayList((Server server) -> STOPPED_AT = System.currentTimeMillis(),
-                                               (Server server) -> STARTED_AT = 0L))
-                    .build();
+            final ServerListener sl =
+                    ServerListener.builder()
+                                  // add a callback.
+                                  .addStartingCallback((Server server) ->
+                                          STARTING_AT = System.currentTimeMillis())
+                                  // add multiple callbacks, one by one.
+                                  .addStartedCallback((Server server) ->
+                                          STARTED_AT = -1)
+                                  .addStartedCallback((Server server) ->
+                                          STARTED_AT = System.currentTimeMillis())
+                                  // add multiple callbacks at once, with vargs api.
+                                  .addStoppingCallbacks((Server server) ->
+                                                    STOPPING_AT = System.currentTimeMillis(),
+                                                    (Server server) -> STARTING_AT = 0L)
+                                  // add multiple callbacks at once, with iterable api.
+                                  .addStoppedCallbacks(
+                                    Lists.newArrayList((Server server) ->
+                                                    STOPPED_AT = System.currentTimeMillis(),
+                                                    (Server server) -> STARTED_AT = 0L))
+                                  .build();
             sb.serverListener(sl);
         }
     };

examples/grpc-reactor/src/main/java/example/armeria/grpc/reactor/Main.java

@@ -8,7 +8,7 @@
 import com.linecorp.armeria.common.grpc.GrpcSerializationFormats;
 import com.linecorp.armeria.server.HttpServiceWithRoutes;
 import com.linecorp.armeria.server.Server;
-import com.linecorp.armeria.server.docs.DocServiceBuilder;
+import com.linecorp.armeria.server.docs.DocService;
 import com.linecorp.armeria.server.docs.DocServiceFilter;
 import com.linecorp.armeria.server.grpc.GrpcService;
 
@@ -56,15 +56,20 @@ static Server newServer(int httpPort, int httpsPort) throws Exception {
                      .service(grpcService)
                      // You can access the documentation service at http://127.0.0.1:8080/docs.
                      // See https://line.github.io/armeria/server-docservice.html for more information.
-                     .serviceUnder("/docs", new DocServiceBuilder()
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
-                                                  "Hello", exampleRequest)
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
-                                                  "LazyHello", exampleRequest)
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
-                                                  "BlockingHello", exampleRequest)
-                         .exclude(DocServiceFilter.ofServiceName(ServerReflectionGrpc.SERVICE_NAME))
-                         .build())
+                     .serviceUnder("/docs",
+                             DocService.builder()
+                                       .exampleRequestForMethod(
+                                               HelloServiceGrpc.SERVICE_NAME,
+                                               "Hello", exampleRequest)
+                                       .exampleRequestForMethod(
+                                               HelloServiceGrpc.SERVICE_NAME,
+                                               "LazyHello", exampleRequest)
+                                       .exampleRequestForMethod(
+                                               HelloServiceGrpc.SERVICE_NAME,
+                                               "BlockingHello", exampleRequest)
+                                       .exclude(DocServiceFilter.ofServiceName(
+                                               ServerReflectionGrpc.SERVICE_NAME))
+                                       .build())
                      .build();
     }
 

examples/grpc/src/main/java/example/armeria/grpc/Main.java

@@ -8,7 +8,7 @@
 import com.linecorp.armeria.common.grpc.GrpcSerializationFormats;
 import com.linecorp.armeria.server.HttpServiceWithRoutes;
 import com.linecorp.armeria.server.Server;
-import com.linecorp.armeria.server.docs.DocServiceBuilder;
+import com.linecorp.armeria.server.docs.DocService;
 import com.linecorp.armeria.server.docs.DocServiceFilter;
 import com.linecorp.armeria.server.grpc.GrpcService;
 
@@ -56,15 +56,17 @@ static Server newServer(int httpPort, int httpsPort) throws Exception {
                      .service(grpcService)
                      // You can access the documentation service at http://127.0.0.1:8080/docs.
                      // See https://line.github.io/armeria/server-docservice.html for more information.
-                     .serviceUnder("/docs", new DocServiceBuilder()
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
+                     .serviceUnder("/docs",
+                             DocService.builder()
+                                       .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
                                                   "Hello", exampleRequest)
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
+                                       .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
                                                   "LazyHello", exampleRequest)
-                         .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
+                                       .exampleRequestForMethod(HelloServiceGrpc.SERVICE_NAME,
                                                   "BlockingHello", exampleRequest)
-                         .exclude(DocServiceFilter.ofServiceName(ServerReflectionGrpc.SERVICE_NAME))
-                         .build())
+                                       .exclude(DocServiceFilter.ofServiceName(
+                                                    ServerReflectionGrpc.SERVICE_NAME))
+                                       .build())
                      .build();
     }