SOLR-14637 update CloudSolrClient examples to remove deprecated .Builder() method (#1670)

* update CloudSolrClient examples to remove deprecated .Builder() method

* remove extra method lines that arent specific to what we are explaining.

solr/CHANGES.txt

@@ -150,6 +150,8 @@ Other Changes
 * SOLR-13939: Extract any non-gradle related patches (deprecations, URL fixes, etc.) from gradle effort. NOTE:
   this will be in several separate commits/pushes. (Erick Erickson)
 
+* SOLR-14637: Update CloudSolrClient examples to remove deprecated method. (Andras Salamon via Eric Pugh)
+
 ==================  8.6.0 ==================
 
 Consult the LUCENE_CHANGES.txt file for additional, low level, changes in this release.

solr/solr-ref-guide/src/enabling-ssl.adoc

@@ -404,7 +404,7 @@ System.setProperty("javax.net.ssl.keyStorePassword", "secret");
 System.setProperty("javax.net.ssl.trustStore", "/path/to/solr-ssl.keystore.p12");
 System.setProperty("javax.net.ssl.trustStorePassword", "secret");
 String zkHost = "127.0.0.1:2181";
-CloudSolrClient client = new CloudSolrClient.Builder().withZkHost(zkHost).build();
+CloudSolrClient client = new CloudSolrClient.Builder(Collections.singletonList(zkHost),Optional.empty()).build();
 client.setDefaultCollection("mycollection");
 SolrInputDocument doc = new SolrInputDocument();
 doc.addField("id", "1234");

solr/solr-ref-guide/src/kerberos-authentication-plugin.adoc

@@ -373,8 +373,7 @@ To create a `CloudSolrClient` that uses delegation tokens:
 
 [source,java]
 ----
-CloudSolrClient client = new CloudSolrClient.Builder()
-                .withZkHost("localhost:2181")
+CloudSolrClient client = new CloudSolrClient.Builder(Collections.singletonList("localhost:2181"),Optional.empty())
                 .withLBHttpSolrClientBuilder(new LBHttpSolrClient.Builder()
                     .withResponseParser(client.getParser())
                     .withHttpSolrClientBuilder(

solr/solr-ref-guide/src/using-solrj.adoc

@@ -110,6 +110,29 @@ The `Http2SolrClient` manages connections to different nodes efficiently. `Http2
 does not require a `baseUrl`. In case a `baseUrl` is not provided, then `SolrRequest.basePath` must be set, so
 `Http2SolrClient` knows which nodes to send requests to. If not an `IllegalArgumentException` will be thrown.
 
+==== Base URLs of CloudSolrClient
+
+It is also possible to specify base URLs for `CloudSolrClient`, but URLs are expected to point to the root Solr path (e.g., `\http://hostname:8983/solr`). They should not include any collections, cores, or other path components.
+
+[source,java,indent=0]
+----
+include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-cloudsolrclient-baseurl]
+----
+
+In case a `baseUrl` is not provided, then a list of ZooKeeper hosts (with ports) and ZooKeeper root must be provided.
+If no ZooKeeper root is used then `java.util.Optional.empty()` has to be provided as part of the method.
+
+[source,java,indent=0]
+----
+include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-cloudsolrclient-zookeepernoroot]
+----
+
+[source,java,indent=0]
+----
+include::{example-source-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-cloudsolrclient-zookeeperroot]
+----
+
+
 ==== Timeouts
 All `SolrClient` implementations allow users to specify the connection and read timeouts for communicating with Solr.  These are provided at client creation time, as in the example below:
 

solr/solrj/src/test/org/apache/solr/client/ref_guide_examples/UsingSolrJRefGuideExamplesTest.java

@@ -23,6 +23,7 @@ import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.Queue;
 import java.util.UUID;
 
@@ -31,6 +32,7 @@ import org.apache.solr.client.solrj.SolrQuery;
 import org.apache.solr.client.solrj.SolrQuery.ORDER;
 import org.apache.solr.client.solrj.SolrRequest;
 import org.apache.solr.client.solrj.beans.Field;
+import org.apache.solr.client.solrj.impl.CloudSolrClient;
 import org.apache.solr.client.solrj.impl.HttpSolrClient;
 import org.apache.solr.client.solrj.request.CollectionAdminRequest;
 import org.apache.solr.client.solrj.response.CollectionAdminResponse;
@@ -246,6 +248,38 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     // end::solrj-solrclient-timeouts[]
   }
 
+  private SolrClient getBaseURLCloudSolrClient() {
+    // tag::solrj-cloudsolrclient-baseurl[]
+    final List<String> solrUrls = new ArrayList<>();
+    solrUrls.add("http://solr1:8983/solr");
+    solrUrls.add("http://solr2:8983/solr");
+    return new CloudSolrClient.Builder(solrUrls)
+            .build();
+    // end::solrj-cloudsolrclient-baseurl[]
+  }
+
+  private SolrClient getZookeeperNoRootCloudSolrClient() {
+    // tag::solrj-cloudsolrclient-zookeepernoroot[]
+    final List<String> zkServers = new ArrayList<>();
+    zkServers.add("zookeeper1:2181");
+    zkServers.add("zookeeper2:2181");
+    zkServers.add("zookeeper3:2181");
+    return new CloudSolrClient.Builder(zkServers, Optional.empty())
+            .build();
+    // end::solrj-cloudsolrclient-zookeepernoroot[]
+  }
+
+  private SolrClient getZookeeperRootCloudSolrClient() {
+    // tag::solrj-cloudsolrclient-zookeeperroot[]
+    final List<String> zkServers = new ArrayList<>();
+    zkServers.add("zookeeper1:2181");
+    zkServers.add("zookeeper2:2181");
+    zkServers.add("zookeeper3:2181");
+    return new CloudSolrClient.Builder(zkServers, Optional.of("/solr"))
+            .build();
+    // end::solrj-cloudsolrclient-zookeeperroot[]
+  }
+
   private void assertNumDocuments(int expectedNumResults) throws Exception {
     final QueryResponse queryResponse = getSolrClient().query("techproducts", new SolrQuery("*:*"));
     assertEquals(expectedNumResults, queryResponse.getResults().getNumFound());