You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by tf...@apache.org on 2017/06/12 22:49:37 UTC
lucene-solr:branch_6x: SOLR-10851: SolrClients should clarify
expectations for solrServerUrl parameter
Repository: lucene-solr
Updated Branches:
refs/heads/branch_6x db91fb792 -> 519146204
SOLR-10851: SolrClients should clarify expectations for solrServerUrl parameter
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/51914620
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/51914620
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/51914620
Branch: refs/heads/branch_6x
Commit: 5191462046c3db29acf6bb814d12577dd66d250f
Parents: db91fb7
Author: Tomas Fernandez Lobbe <tf...@apache.org>
Authored: Mon Jun 12 15:46:13 2017 -0700
Committer: Tomas Fernandez Lobbe <tf...@apache.org>
Committed: Mon Jun 12 15:48:58 2017 -0700
----------------------------------------------------------------------
solr/CHANGES.txt | 3 +
solr/solr-ref-guide/src/using-solrj.adoc | 8 ++
.../solr/client/solrj/impl/CloudSolrClient.java | 10 ++-
.../solrj/impl/ConcurrentUpdateSolrClient.java | 18 ++++-
.../solr/client/solrj/impl/HttpSolrClient.java | 80 +++++++++++++++-----
.../client/solrj/impl/LBHttpSolrClient.java | 38 +++++++++-
6 files changed, 133 insertions(+), 24 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/CHANGES.txt
----------------------------------------------------------------------
diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt
index 53e2d29..568353e 100644
--- a/solr/CHANGES.txt
+++ b/solr/CHANGES.txt
@@ -164,6 +164,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
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/solr-ref-guide/src/using-solrj.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/using-solrj.adoc b/solr/solr-ref-guide/src/using-solrj.adoc
index fb92bd9..b619aed 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
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java
----------------------------------------------------------------------
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 82255a4..2f75ca0 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
@@ -412,8 +412,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.
@@ -1652,6 +1652,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);
@@ -1662,6 +1665,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<String> solrUrls) {
this.solrUrls.addAll(solrUrls);
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java
----------------------------------------------------------------------
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 c549709..18ca981 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
@@ -622,7 +622,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
+ * <pre>
+ * SolrClient client = new ConcurrentUpdateSolrClient.Builder("http://my-solr-server:8983/solr/core1").build();
+ * QueryResponse resp = client.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * SolrClient client = new ConcurrentUpdateSolrClient.Builder("http://my-solr-server:8983/solr").build();
+ * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java
----------------------------------------------------------------------
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 e0bd3ea..84e89a5 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
@@ -82,24 +82,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
- * <pre>
- * SolrClient client = new HttpSolrClient("http://my-solr-server:8983/solr/core1");
- * QueryResponse resp = client.query(new SolrQuery("*:*"));
- * </pre>
- * 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
- * <pre>
- * SolrClient client = new HttpSolrClient("http://my-solr-server:8983/solr");
- * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
- * </pre>
- * 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 {
@@ -648,6 +630,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
+ * <pre>
+ * httpSolrClient.setBaseURL("http://my-solr-server:8983/solr/core1");
+ * QueryResponse resp = httpSolrClient.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * httpSolrClient.setBaseURL("http://my-solr-server:8983/solr");
+ * QueryResponse resp = httpSolrClient.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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;
}
@@ -807,6 +810,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
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr/core1").build();
+ * QueryResponse resp = client.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr").build();
+ * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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;
@@ -815,9 +839,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:
+ *
+ * 1) A path pointing directly at a particular core
+ * <pre>
+ * SolrClient client = new HttpSolrClient.Builder("http://my-solr-server:8983/solr/core1").build();
+ * QueryResponse resp = client.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * SolrClient client = new HttpSolrClient.Builder("http://my-solr-server:8983/solr").build();
+ * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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.
*
- * @param baseSolrUrl the base URL of the Solr server that will be targeted by any created clients.
+ * By default, compression is not enabled on created HttpSolrClient objects.
*/
public Builder(String baseSolrUrl) {
this.baseSolrUrl = baseSolrUrl;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/51914620/solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java
----------------------------------------------------------------------
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 2229695..126b188 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
@@ -865,16 +865,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
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr/core1").build();
+ * QueryResponse resp = client.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrl("http://my-solr-server:8983/solr").build();
+ * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrls("http://my-solr-server:8983/solr/core1").build();
+ * QueryResponse resp = client.query(new SolrQuery("*:*"));
+ * </pre>
+ * 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")
+ * <pre>
+ * SolrClient client = builder.withBaseSolrUrls("http://my-solr-server:8983/solr").build();
+ * QueryResponse resp = client.query("core1", new SolrQuery("*:*"));
+ * </pre>
+ * 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) {