SOLR-10851: SolrClients should clarify expectations for solrServerUrl parameter

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

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
 

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
+   *          use of the these URLs to fetch the list of live nodes for this Solr cluster.  URL's must point to the
-   *          one of solrUrls or zkHosts.
+   *          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<String> solrUrls) {
       this.solrUrls.addAll(solrUrls);

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
+     * <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;

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
- * <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 {
 
@@ -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
+   * <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;
   }
@@ -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
+     * <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;
@@ -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
+     * <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.
+     * 
+     * By default, compression is not enabled on created HttpSolrClient objects.
      */
     public Builder(String baseSolrUrl) {
       this.baseSolrUrl = baseSolrUrl;

solr/solrj/src/java/org/apache/solr/client/solrj/impl/LBHttpSolrClient.java

@@ -867,6 +867,24 @@ 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);
@@ -877,6 +895,24 @@ public class LBHttpSolrClient extends SolrClient {
      * 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) {