From 833a6f3ffbed729869dafeebe5a3c4aa14c113f8 Mon Sep 17 00:00:00 2001 From: Tomas Fernandez Lobbe Date: Mon, 12 Jun 2017 15:46:13 -0700 Subject: [PATCH] SOLR-10851: SolrClients should clarify expectations for solrServerUrl parameter --- solr/CHANGES.txt | 3 + solr/solr-ref-guide/src/using-solrj.adoc | 8 ++ .../client/solrj/impl/CloudSolrClient.java | 10 ++- .../impl/ConcurrentUpdateSolrClient.java | 18 ++++- .../client/solrj/impl/HttpSolrClient.java | 80 ++++++++++++++----- .../client/solrj/impl/LBHttpSolrClient.java | 38 ++++++++- 6 files changed, 133 insertions(+), 24 deletions(-) diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt index 51d2d5335fa..153ed8207d6 100644 --- a/solr/CHANGES.txt +++ b/solr/CHANGES.txt @@ -406,6 +406,9 @@ Other Changes * SOLR-10761: Switch trie numeric/date fields to points in data-driven-enabled example and test schemas. (Steve Rowe) +* SOLR-10851: SolrClients should clarify expectations for solrServerUrl parameter (Jason Gerlowski + via Tomás Fernández Löbbe) + ================== 6.6.1 ================== Bug Fixes diff --git a/solr/solr-ref-guide/src/using-solrj.adoc b/solr/solr-ref-guide/src/using-solrj.adoc index fb92bd9453e..b619aedbaf7 100644 --- a/solr/solr-ref-guide/src/using-solrj.adoc +++ b/solr/solr-ref-guide/src/using-solrj.adoc @@ -69,6 +69,14 @@ You can sidestep a lot of the messing around with the JAR files by using Maven i If you are worried about the SolrJ libraries expanding the size of your client application, you can use a code obfuscator like http://proguard.sourceforge.net/[ProGuard] to remove APIs that you are not using. +[[UsingSolrJ-SpecifyingSolrUrl]] +== Specifying Solr Base URLs + +Most `SolrClient` implementations (with the notable exception of `CloudSolrClient`) require users to specify one or more Solr base URLs, which the client then uses to send HTTP requests to Solr. The path users include on the base URL they provide has an effect on the behavior of the created client from that point on. + +. A URL with a path pointing to a specific core or collection (e.g. `http://hostname:8983/solr/core1`). When a core or collection is specified in the base URL, subsequent requests made with that client are not required to re-specify the affected collection. However, the client is limited to sending requests to that core/collection, and can not send requests to any others. +. A URL with a generic path pointing to the root Solr path (e.g. `http://hostname:8983/solr`). When no core or collection is specified in the base URL, requests can be made to any core/collection, but the affected core/collection must be specified on all requests. + [[UsingSolrJ-SettingXMLResponseParser]] == Setting XMLResponseParser diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java index 11f6b2644fe..10ea590f4a1 100644 --- a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java +++ b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java @@ -250,8 +250,8 @@ public class CloudSolrClient extends SolrClient { * chroot is required, use null. * @param solrUrls * A list of Solr URLs to configure the underlying {@link HttpClusterStateProvider}, which will - * use of the these URLs to fetch the list of live nodes for this Solr cluster. Provide only - * one of solrUrls or zkHosts. + * use of the these URLs to fetch the list of live nodes for this Solr cluster. URL's must point to the + * root Solr path ("/solr"). Provide only one of solrUrls or zkHosts. * @param httpClient * the {@link HttpClient} instance to be used for all requests. The provided httpClient should use a * multi-threaded connection manager. If null, a default HttpClient will be used. @@ -1403,6 +1403,9 @@ public class CloudSolrClient extends SolrClient { * * Method may be called multiple times. One of the provided values will be used to fetch * the list of live Solr nodes that the underlying {@link HttpClusterStateProvider} would be maintaining. + * + * Provided Solr URL is expected to point to the root Solr path ("http://hostname:8983/solr"); it should not + * include any collections, cores, or other path components. */ public Builder withSolrUrl(String solrUrl) { this.solrUrls.add(solrUrl); @@ -1413,6 +1416,9 @@ public class CloudSolrClient extends SolrClient { * Provide a list of Solr URL to be used when configuring {@link CloudSolrClient} instances. * One of the provided values will be used to fetch the list of live Solr * nodes that the underlying {@link HttpClusterStateProvider} would be maintaining. + * + * Provided Solr URLs are expected to point to the root Solr path ("http://hostname:8983/solr"); they should not + * include any collections, cores, or other path components. */ public Builder withSolrUrl(Collection solrUrls) { this.solrUrls.addAll(solrUrls); diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java index d6675f284ea..f169a605217 100644 --- a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java +++ b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java @@ -753,7 +753,23 @@ public class ConcurrentUpdateSolrClient extends SolrClient { /** * Create a Builder object, based on the provided Solr URL. * - * @param baseSolrUrl the base URL of the Solr server that will be targeted by any created clients. + * Two different paths can be specified as a part of this URL: + * + * 1) A path pointing directly at a particular core + * 
+     *   SolrClient client = new ConcurrentUpdateSolrClient.Builder("http://my-solr-server:8983/solr/core1").build();
+     *   QueryResponse resp = client.query(new SolrQuery("*:*"));
+     *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+     *   SolrClient client = new ConcurrentUpdateSolrClient.Builder("http://my-solr-server:8983/solr").build();
+     *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+     *
+ * In this case the client is more flexible and can be used to send requests to any cores. This flexibility though + * requires that the core be specified on all requests. */ public Builder(String baseSolrUrl) { this.baseSolrUrl = baseSolrUrl; diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java index c1e95763ea1..1ba08bfcae1 100644 --- a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java +++ b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java @@ -83,24 +83,6 @@ import org.slf4j.MDC; /** * A SolrClient implementation that talks directly to a Solr server via HTTP - * - * There are two ways to use an HttpSolrClient: - * - * 1) Pass a URL to the constructor that points directly at a particular core - * 
- *   SolrClient client = new HttpSolrClient("http://my-solr-server:8983/solr/core1");
- *   QueryResponse resp = client.query(new SolrQuery("*:*"));
- *
- * In this case, you can query the given core directly, but you cannot query any other - * cores or issue CoreAdmin requests with this client. - * - * 2) Pass the base URL of the node to the constructor - * 
- *   SolrClient client = new HttpSolrClient("http://my-solr-server:8983/solr");
- *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
- *
- * In this case, you must pass the name of the required core for all queries and updates, - * but you may use the same client for all cores, and for CoreAdmin requests. */ public class HttpSolrClient extends SolrClient { @@ -646,6 +628,27 @@ public class HttpSolrClient extends SolrClient { return baseUrl; } + /** + * Change the base-url used when sending requests to Solr. + * + * Two different paths can be specified as a part of this URL: + * + * 1) A path pointing directly at a particular core + * 
+   *   httpSolrClient.setBaseURL("http://my-solr-server:8983/solr/core1");
+   *   QueryResponse resp = httpSolrClient.query(new SolrQuery("*:*"));
+   *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+   *   httpSolrClient.setBaseURL("http://my-solr-server:8983/solr");
+   *   QueryResponse resp = httpSolrClient.query("core1", new SolrQuery("*:*"));
+   *
+ * In this case the client is more flexible and can be used to send requests to any cores. The cost of this is that + * the core must be specified on each request. + */ public void setBaseURL(String baseURL) { this.baseUrl = baseURL; } @@ -762,6 +765,27 @@ public class HttpSolrClient extends SolrClient { this.responseParser = new BinaryResponseParser(); } + /** + * Specify the base-url for the created client to use when sending requests to Solr. + * + * Two different paths can be specified as a part of this URL: + * + * 1) A path pointing directly at a particular core + * 
+     *   SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr/core1").build();
+     *   QueryResponse resp = client.query(new SolrQuery("*:*"));
+     *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+     *   SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr").build();
+     *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+     *
+ * In this case the client is more flexible and can be used to send requests to any cores. This flexibility though + * requires that the core is specified on all requests. + */ public Builder withBaseSolrUrl(String baseSolrUrl) { this.baseSolrUrl = baseSolrUrl; return this; @@ -770,9 +794,25 @@ public class HttpSolrClient extends SolrClient { /** * Create a Builder object, based on the provided Solr URL. * - * By default, compression is not enabled in created HttpSolrClient objects. + * Two different paths can be specified as a part of this URL: * - * @param baseSolrUrl the base URL of the Solr server that will be targeted by any created clients. + * 1) A path pointing directly at a particular core + * 
+     *   SolrClient client = new HttpSolrClient.Builder("http://my-solr-server:8983/solr/core1").build();
+     *   QueryResponse resp = client.query(new SolrQuery("*:*"));
+     *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+     *   SolrClient client = new HttpSolrClient.Builder("http://my-solr-server:8983/solr").build();
+     *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+     *
+ * In this case the client is more flexible and can be used to send requests to any cores. This flexibility though + * requires that the core be specified on all requests. + * + * By default, compression is not enabled on created HttpSolrClient objects. */ public Builder(String baseSolrUrl) { this.baseSolrUrl = baseSolrUrl; diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java index 7706bf6c930..21816bb04a9 100644 --- a/solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java +++ b/solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java @@ -867,16 +867,52 @@ public class LBHttpSolrClient extends SolrClient { * Provide a Solr endpoint to be used when configuring {@link LBHttpSolrClient} instances. * * Method may be called multiple times. All provided values will be used. + * + * Two different paths can be specified as a part of the URL: + * + * 1) A path pointing directly at a particular core + * 
+     *   SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr/core1").build();
+     *   QueryResponse resp = client.query(new SolrQuery("*:*"));
+     *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+     *   SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr").build();
+     *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+     *
+ * In this case the client is more flexible and can be used to send requests to any cores. This flexibility though + * requires that the core is specified on all requests. */ public Builder withBaseSolrUrl(String baseSolrUrl) { this.baseSolrUrls.add(baseSolrUrl); return this; } - + /** * Provide Solr endpoints to be used when configuring {@link LBHttpSolrClient} instances. * * Method may be called multiple times. All provided values will be used. + * + * Two different paths can be specified as a part of each URL: + * + * 1) A path pointing directly at a particular core + * 
+     *   SolrClient client = builder.withBaseSolrUrls("http://my-solr-server:8983/solr/core1").build();
+     *   QueryResponse resp = client.query(new SolrQuery("*:*"));
+     *
+ * Note that when a core is provided in the base URL, queries and other requests can be made without mentioning the + * core explicitly. However, the client can only send requests to that core. + * + * 2) The path of the root Solr path ("/solr") + * 
+     *   SolrClient client = builder.withBaseSolrUrls("http://my-solr-server:8983/solr").build();
+     *   QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+     *
+ * In this case the client is more flexible and can be used to send requests to any cores. This flexibility though + * requires that the core is specified on all requests. */ public Builder withBaseSolrUrls(String... solrUrls) { for (String baseSolrUrl : solrUrls) {