SOLR-17994: SolrClientCustomizer (#3876)

dsmiley · web-flow · commit d7941818b495 · 2025-12-01T10:14:30.000-05:00
* Rename HttpClientBuilderFactory to SolrClientCustomizer, generalizing it.  
* Rename property solr.httpclient.builder.factory to solr.solrj.http.jetty.customizer
* Rename PreemptiveBasicAuthClientBuilderFactory to PreemptiveBasicAuthClientCustomizer
diff --git a/changelog/unreleased/SOLR-17994-SolrClientCustomizer.yml b/changelog/unreleased/SOLR-17994-SolrClientCustomizer.yml
@@ -0,0 +1,8 @@
+# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc
+title: Rename HttpClientBuilderFactory to SolrClientCustomizer, and property solr.httpclient.builder.factory to solr.solrj.http.jetty.customizer
+type: other # added, changed, fixed, deprecated, removed, dependency_update, security, other
+authors:
+  - name: David Smiley
+links:
+  - name: SOLR-17994
+    url: https://issues.apache.org/jira/browse/SOLR-17994
diff --git a/solr/bin/solr b/solr/bin/solr
@@ -342,7 +342,7 @@ fi
 if [ -n "${SOLR_AUTH_TYPE:-}" ]; then
   case "$(echo "$SOLR_AUTH_TYPE" | awk '{print tolower($0)}')" in
     basic)
-      SOLR_AUTHENTICATION_CLIENT_BUILDER="org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientBuilderFactory"
+      SOLR_AUTHENTICATION_CLIENT_BUILDER="org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer"
       ;;
     *)
       echo "ERROR: Value specified for SOLR_AUTH_TYPE environment variable is invalid."
@@ -355,7 +355,7 @@ if [ -n "${SOLR_AUTHENTICATION_CLIENT_CONFIGURER:-}" ]; then
   echo "         Please start using SOLR_AUTH_TYPE instead"
 fi
 if [ -n "${SOLR_AUTHENTICATION_CLIENT_BUILDER:-}" ]; then
-  AUTHC_CLIENT_BUILDER_ARG="-Dsolr.httpclient.builder.factory=$SOLR_AUTHENTICATION_CLIENT_BUILDER"
+  AUTHC_CLIENT_BUILDER_ARG="-Dsolr.solrj.http.jetty.customizer=$SOLR_AUTHENTICATION_CLIENT_BUILDER"
   AUTHC_OPTS="${AUTHC_CLIENT_BUILDER_ARG:-}"
 fi
 # This looks strange, but it is to avoid extra spaces when we have only one of the values set
diff --git a/solr/bin/solr.cmd b/solr/bin/solr.cmd
@@ -227,7 +227,7 @@ IF DEFINED SOLR_AUTH_TYPE (
 
 IF DEFINED SOLR_AUTH_TYPE (
   IF /I "%SOLR_AUTH_TYPE%" == "basic" (
-    set SOLR_AUTHENTICATION_CLIENT_BUILDER="org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientBuilderFactory"
+    set SOLR_AUTHENTICATION_CLIENT_BUILDER="org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer"
   ) ELSE (
     echo ERROR: Value specified for SOLR_AUTH_TYPE configuration variable is invalid.
     goto err
@@ -239,7 +239,7 @@ IF DEFINED SOLR_AUTHENTICATION_CLIENT_CONFIGURER (
   echo          Please start using SOLR_AUTH_TYPE instead
 )
 IF DEFINED SOLR_AUTHENTICATION_CLIENT_BUILDER (
-  set AUTHC_CLIENT_BUILDER_ARG="-Dsolr.httpclient.builder.factory=%SOLR_AUTHENTICATION_CLIENT_BUILDER%"
+  set AUTHC_CLIENT_BUILDER_ARG="-Dsolr.solrj.http.jetty.customizer=%SOLR_AUTHENTICATION_CLIENT_BUILDER%"
 )
 set "AUTHC_OPTS=%AUTHC_CLIENT_BUILDER_ARG% %SOLR_AUTHENTICATION_OPTS%"
 
diff --git a/solr/bin/solr.in.cmd b/solr/bin/solr.in.cmd
@@ -173,7 +173,7 @@ REM set SOLR_SSL_CLIENT_TRUST_STORE_TYPE=
 
 REM Settings for authentication
 REM Please configure only one of SOLR_AUTHENTICATION_CLIENT_BUILDER or SOLR_AUTH_TYPE parameters
-REM set SOLR_AUTHENTICATION_CLIENT_BUILDER=org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientBuilderFactory
+REM set SOLR_AUTHENTICATION_CLIENT_BUILDER=org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer
 REM set SOLR_AUTH_TYPE=basic
 REM set SOLR_AUTHENTICATION_OPTS=-Dsolr.security.auth.basicauth.credentials=solr:SolrRocks
 
diff --git a/solr/core/src/test/org/apache/solr/cloud/RecoveryZkTestWithAuth.java b/solr/core/src/test/org/apache/solr/cloud/RecoveryZkTestWithAuth.java
@@ -27,8 +27,8 @@
 import org.apache.solr.client.solrj.SolrServerException;
 import org.apache.solr.client.solrj.apache.CloudLegacySolrClient;
 import org.apache.solr.client.solrj.apache.HttpSolrClient;
-import org.apache.solr.client.solrj.impl.SolrHttpConstants;
-import org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientBuilderFactory;
+import org.apache.solr.client.solrj.jetty.HttpJettySolrClient;
+import org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer;
 import org.apache.solr.client.solrj.request.CollectionAdminRequest;
 import org.apache.solr.client.solrj.request.QueryRequest;
 import org.apache.solr.client.solrj.request.SolrQuery;
@@ -49,8 +49,8 @@ public static void setupCluster() throws Exception {
     // for context)
     if (rarely()) {
       System.setProperty(
-          SolrHttpConstants.SYS_PROP_HTTP_CLIENT_BUILDER_FACTORY,
-          PreemptiveBasicAuthClientBuilderFactory.class.getName());
+          HttpJettySolrClient.CLIENT_CUSTOMIZER_SYSPROP,
+          PreemptiveBasicAuthClientCustomizer.class.getName());
       System.setProperty("solr.security.auth.basicauth.credentials", SecurityJson.USER_PASS);
     }
 
diff --git a/solr/solr-ref-guide/modules/configuration-guide/pages/solr-properties.adoc b/solr/solr-ref-guide/modules/configuration-guide/pages/solr-properties.adoc
@@ -102,14 +102,16 @@ NOTE: Properties marked with "!" indicate inverted meaning between pre Solr 10 a
 
 |solr.security.allow.urls|solr.allowUrls||A comma seperated list of urls for reading from.
 
-|solr.security.allow.urls.enabled|!solr.disable.allow.urls|false|If using an allow list of accessible urls is enabled. 
+|solr.security.allow.urls.enabled|!solr.disable.allow.urls|false|If using an allow list of accessible urls is enabled.
 
 |solr.security.auth.plugin|authenticationPlugin||Specifies the authentication plugin to use.
 
 |solr.solrj.cloud.max.stale.retries|cloudSolrClientMaxStaleRetries|5|Sets the maximum number of retries for stale connection attempts in SolrJ cloud client.
 
 |solr.solrj.http.cookies.enabled|!solr.http.disableCookies| false |If Http2SolrClient should support cookies.
 
+|solr.solrj.http.jetty.customizer|solr.httpclient.builder.factory||A class loaded to customize HttpJettySolrClient upon creation.
+
 |solr.streamingexpressions.facet.tiered.enabled|solr.facet.stream.tiered|true|Controls whether tiered faceting is enabled for streaming expressions.
 
 |solr.streamingexpressions.macros.enabled|StreamingExpressionMacros|false|Controls whether to expand URL parameters inside of the `expr` parameter.
@@ -163,8 +165,8 @@ System properties can be set in several ways:
 2. In `solr.in.sh` (Unix) or `solr.in.cmd` (Windows) using environment variables
 3. Through environment variables (with appropriate naming conventions)
 
-Environment variables can also be used to set these properties.  
-You may find this useful in environments such as Docker.  
+Environment variables can also be used to set these properties.
+You may find this useful in environments such as Docker.
 Environment variables should be uppercase with dot notations equivalents, e.g. `SOLR_API_V2_ENABLED` for the property `solr.api.v2.enabled`.
 
 == See Also
diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/basic-authentication-plugin.adoc
@@ -358,9 +358,9 @@ QueryResponse rsp = req.process(client);
 
 === Global (JVM) Basic Auth Credentials
 
-Alternatively, users can use SolrJ's `PreemptiveBasicAuthClientBuilderFactory` to add basic authentication credentials to _all_ requests automatically.
-To enable this feature, users should set the following system property `-Dsolr.httpclient.builder.factory=org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientBuilderFactory`.
-`PreemptiveBasicAuthClientBuilderFactory` allows applications to provide credentials in two different ways:
+Alternatively, users can use SolrJ's `PreemptiveBasicAuthClientCustomizer` to add basic authentication credentials to _all_ requests automatically.
+To enable this feature, users should set the following system property `-Dsolr.solrj.http.jetty.customizer=org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer`.
+`PreemptiveBasicAuthClientCustomizer` allows applications to provide credentials in two different ways:
 
 . The `solr.security.auth.basicauth.credentials` system property can be passed, containing the credentials directly (e.g., `-Dsolr.security.auth.basicauth.credentials=username:password`).
 This option is straightforward, but may expose the credentials in the command line, depending on how they're set.
diff --git a/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-10.adoc b/solr/solr-ref-guide/modules/upgrade-notes/pages/major-changes-in-solr-10.adoc
@@ -78,6 +78,8 @@ The following classes were renamed with some refactorings: `Http2SolrClient` to
 `CloudHttp2SolrClient.Builder` has moved to `CloudSolrClient`; users should generally have no need to refer to `CloudHttp2SolrClient` or any class/member with "http2" in it.
 The builder will check if Jetty `HttpClient` is available and use that, otherwise fallback on a JDK based `HttpClient`.
 `CloudJettySolrClient` is new, proving an explicit option.
+The system property `solr.solrj.http.jetty.customizer` (formerly `solr.httpclient.builder.factory`) can configure a `HttpJettySolrClient`.
+The only built-in implementation is `org.apache.solr.client.solrj.jetty.PreemptiveBasicAuthClientCustomizer`, renamed from `PreemptiveBasicAuthClientCustomizer`.
 
 * `SolrClient` implementations that rely on "base URL" strings now only accept "root" URL paths (i.e. URLs that end in "/solr").
 Users who previously relied on collection-specific URLs to avoid including the collection name with each request can instead achieve this by specifying a "default collection" using the `withDefaultCollection` method available on most `SolrClient` Builders.
@@ -90,7 +92,6 @@ Users who previously relied on collection-specific URLs to avoid including the c
 This makes it clear that they pertain specifically to “JavaBin” rather than binary in general.
 
 * The deprecated SolrClient implementations based on Apache HttpClient are removed from Solrj,  thus the related dependencies are no longer present.
-The system property `solr.httpclient.builder.factory` now only configures SolrClients using a Jetty based HttpClient.
 
 * A number of classes moved to different packages to be better organized:
 ShardTerms, DelegatingClusterStateProvider, JavaBinRequestWriter, RoutedAliasTypes, SolrQuery, XMLRequestWriter, JacksonContentWriter, FastStreamingDocsCallback, InputStreamResponse, InputStreamResponseParser, JavaBinResponseParser, ResponseParser, StreamingJavaBinResponseParser, StreamingResponseCallback, XMLResponseParser, JacksonDataBindResponseParser, JsonMapResponseParser, SocketProxy
diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/SolrClientCustomizer.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/SolrClientCustomizer.java
@@ -16,15 +16,17 @@
  */
 package org.apache.solr.client.solrj.impl;
 
-import java.io.Closeable;
-import org.apache.solr.client.solrj.jetty.HttpJettySolrClient;
+import org.apache.solr.client.solrj.SolrClient;
 
 /**
- * A config hook for post-configuration of a {@linkplain HttpJettySolrClient} by its builder.
+ * A config hook for post-configuration of a {@linkplain SolrClient} by its builder. It is not
+ * supported by all builders.
  *
- * @see SolrHttpConstants#SYS_PROP_HTTP_CLIENT_BUILDER_FACTORY
+ * @param <T> type of SolrClient this customizer targets
+ * @see org.apache.solr.client.solrj.jetty.HttpJettySolrClient#CLIENT_CUSTOMIZER_SYSPROP
  * @lucene.experimental
  */
-public interface HttpClientBuilderFactory extends Closeable {
-  default void setup(HttpJettySolrClient client) {}
+public interface SolrClientCustomizer<T extends SolrClient> {
+
+  void setup(T client);
 }
diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/SolrHttpConstants.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/SolrHttpConstants.java
@@ -42,12 +42,6 @@ public interface SolrHttpConstants {
   /** Maximum total connections allowed */
   String PROP_MAX_CONNECTIONS = "maxConnections";
 
-  /**
-   * A Java system property to select the {@linkplain HttpClientBuilderFactory} used for configuring
-   * HTTP based SolrClients.
-   */
-  String SYS_PROP_HTTP_CLIENT_BUILDER_FACTORY = "solr.httpclient.builder.factory";
-
   /**
    * System property consulted to determine if HTTP based SolrClients will require hostname
    * validation of SSL Certificates. The default behavior is to enforce peer name validation.
diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/jetty/HttpJettySolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/jetty/HttpJettySolrClient.java
@@ -41,10 +41,10 @@
 import org.apache.solr.client.solrj.SolrClient;
 import org.apache.solr.client.solrj.SolrRequest;
 import org.apache.solr.client.solrj.SolrServerException;
-import org.apache.solr.client.solrj.impl.HttpClientBuilderFactory;
 import org.apache.solr.client.solrj.impl.HttpSolrClientBase;
 import org.apache.solr.client.solrj.impl.HttpSolrClientBuilderBase;
 import org.apache.solr.client.solrj.impl.LBSolrClient;
+import org.apache.solr.client.solrj.impl.SolrClientCustomizer;
 import org.apache.solr.client.solrj.impl.SolrHttpConstants;
 import org.apache.solr.client.solrj.jetty.HttpListenerFactory.RequestResponseListener;
 import org.apache.solr.client.solrj.request.RequestWriter;
@@ -101,7 +101,15 @@
  */
 public class HttpJettySolrClient extends HttpSolrClientBase {
   // formerly known at Http2SolrClient
+
   private static final Logger log = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
+
+  /**
+   * A Java system property to select the {@linkplain SolrClientCustomizer} used for configuring
+   * this client.
+   */
+  public static final String CLIENT_CUSTOMIZER_SYSPROP = "solr.solrj.http.jetty.customizer";
+
   public static final String REQ_PRINCIPAL_KEY = "solr-req-principal";
   private static final String USER_AGENT =
       "Solr[" + MethodHandles.lookup().lookupClass().getName() + "] " + SolrVersion.LATEST_STRING;
@@ -156,7 +164,7 @@ protected HttpJettySolrClient(String serverBaseUrl, Builder builder) {
     this.idleTimeoutMillis = builder.getIdleTimeoutMillis();
 
     try {
-      applyHttpClientBuilderFactory();
+      applyClientCustomizer();
     } catch (RuntimeException e) {
       try {
         this.close();
@@ -177,16 +185,16 @@ private void initAuthStoreFromExistingClient(HttpClient httpClient) {
     this.authenticationStore = (AuthenticationStoreHolder) httpClient.getAuthenticationStore();
   }
 
-  private void applyHttpClientBuilderFactory() {
-    String factoryClassName =
-        System.getProperty(SolrHttpConstants.SYS_PROP_HTTP_CLIENT_BUILDER_FACTORY);
+  @SuppressWarnings("unchecked")
+  private void applyClientCustomizer() {
+    String factoryClassName = EnvUtils.getProperty(CLIENT_CUSTOMIZER_SYSPROP);
     if (factoryClassName != null) {
-      log.debug("Using Http Builder Factory: {}", factoryClassName);
-      HttpClientBuilderFactory factory;
+      log.debug("Using {}", factoryClassName);
+      SolrClientCustomizer<HttpJettySolrClient> instance;
       try {
-        factory =
+        instance =
             Class.forName(factoryClassName)
-                .asSubclass(HttpClientBuilderFactory.class)
+                .asSubclass(SolrClientCustomizer.class)
                 .getDeclaredConstructor()
                 .newInstance();
       } catch (InstantiationException
@@ -197,7 +205,7 @@ private void applyHttpClientBuilderFactory() {
         throw new RuntimeException(
             "Unable to instantiate " + HttpJettySolrClient.class.getName(), e);
       }
-      factory.setup(this);
+      instance.setup(this);
     }
   }
 
diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/jetty/PreemptiveBasicAuthClientCustomizer.java b/solr/solrj/src/java/org/apache/solr/client/solrj/jetty/PreemptiveBasicAuthClientCustomizer.java
@@ -26,7 +26,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Properties;
-import org.apache.solr.client.solrj.impl.HttpClientBuilderFactory;
+import org.apache.solr.client.solrj.impl.SolrClientCustomizer;
 import org.apache.solr.client.solrj.impl.SolrHttpConstants;
 import org.apache.solr.common.params.MapSolrParams;
 import org.apache.solr.common.params.SolrParams;
@@ -36,10 +36,13 @@
 import org.eclipse.jetty.client.internal.HttpAuthenticationStore;
 
 /**
- * HttpClientConfigurer implementation providing support for preemptive Http Basic authentication
- * scheme.
+ * A {@link HttpJettySolrClient} {@link SolrClientCustomizer} supporting a preemptive Http Basic
+ * authentication scheme.
+ *
+ * @see HttpJettySolrClient#CLIENT_CUSTOMIZER_SYSPROP
  */
-public class PreemptiveBasicAuthClientBuilderFactory implements HttpClientBuilderFactory {
+public class PreemptiveBasicAuthClientCustomizer
+    implements SolrClientCustomizer<HttpJettySolrClient> {
   /**
    * A system property used to specify a properties file containing default parameters used for
    * creating an HTTP client. This is specifically useful for configuring the HTTP basic auth
@@ -66,9 +69,6 @@ public static void setDefaultSolrParams(SolrParams params) {
     CREDENTIAL_RESOLVER.defaultParams = params;
   }
 
-  @Override
-  public void close() throws IOException {}
-
   @Override
   public void setup(HttpJettySolrClient client) {
     final String basicAuthUser =
@@ -99,10 +99,9 @@ static class CredentialsResolver {
 
     public CredentialsResolver() {
       String credentials =
-          System.getProperty(
-              PreemptiveBasicAuthClientBuilderFactory.SYS_PROP_BASIC_AUTH_CREDENTIALS);
+          System.getProperty(PreemptiveBasicAuthClientCustomizer.SYS_PROP_BASIC_AUTH_CREDENTIALS);
       String configFile =
-          System.getProperty(PreemptiveBasicAuthClientBuilderFactory.SYS_PROP_HTTP_CLIENT_CONFIG);
+          System.getProperty(PreemptiveBasicAuthClientCustomizer.SYS_PROP_HTTP_CLIENT_CONFIG);
 
       if (credentials != null && configFile != null) {
         throw new IllegalArgumentException(
diff --git a/solr/solrj/src/test/org/apache/solr/client/solrj/impl/HttpSolrClientTestBase.java b/solr/solrj/src/test/org/apache/solr/client/solrj/impl/HttpSolrClientTestBase.java
@@ -39,7 +39,7 @@
 import org.apache.solr.client.solrj.SolrClient;
 import org.apache.solr.client.solrj.SolrRequest;
 import org.apache.solr.client.solrj.SolrServerException;
-import org.apache.solr.client.solrj.apache.HttpClientUtil;
+import org.apache.solr.client.solrj.jetty.HttpJettySolrClient;
 import org.apache.solr.client.solrj.request.QueryRequest;
 import org.apache.solr.client.solrj.request.SolrQuery;
 import org.apache.solr.client.solrj.request.UpdateRequest;
@@ -92,7 +92,7 @@ public static void beforeTest() throws Exception {
   @Override
   public void tearDown() throws Exception {
     System.clearProperty("solr.security.auth.basicauth.credentials");
-    System.clearProperty(HttpClientUtil.SYS_PROP_HTTP_CLIENT_BUILDER_FACTORY);
+    System.clearProperty(HttpJettySolrClient.CLIENT_CUSTOMIZER_SYSPROP);
     DebugServlet.clear();
     super.tearDown();
   }
diff --git a/solr/solrj/src/test/org/apache/solr/client/solrj/impl/PreemptiveBasicAuthClientCustomizerTest.java b/solr/solrj/src/test/org/apache/solr/client/solrj/impl/PreemptiveBasicAuthClientCustomizerTest.java
diff --git a/solr/solrj/src/test/org/apache/solr/client/solrj/jetty/HttpJettySolrClientTest.java b/solr/solrj/src/test/org/apache/solr/client/solrj/jetty/HttpJettySolrClientTest.java
