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

@@ -117,7 +117,7 @@ Improvements
 
 * SOLR-14537: Improve performance of ExportWriter. (ab, Joel Bernstein)
 
-* SOLR-14566: Request ID's ('rid') are now added by default to distributed search requests, and can be used to correlate 
+* SOLR-14566: Request ID's ('rid') are now added by default to distributed search requests, and can be used to correlate
   logs from the receiving coordinator node with those from downstream shard requests.  This can be disabled by providing a
   disableRequestId=true request parameter. (Jason Gerlowski)
 
@@ -144,12 +144,14 @@ Other Changes
 
 * SOLR-14592: Upgrade Zookeeper to 3.6.1. NOTE: this required upgrading netty to 4.1.50 (Erick Erickson)
 
-* SOLR-10742: SolrCores.getNamesForCore is quite inefficient and blocks other core operations. 
+* SOLR-10742: SolrCores.getNamesForCore is quite inefficient and blocks other core operations.
   NOTE: this experimental method has been removed (Erick Erickson)
 
 * 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;
@@ -57,7 +59,7 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
 
   private static final int NUM_INDEXED_DOCUMENTS = 3;
   private static final int NUM_LIVE_NODES = 1;
-  
+
   private Queue<String> expectedLines = new ArrayDeque<>();
 
   @BeforeClass
@@ -104,7 +106,7 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     expectLine("id: 1; name: Fitbit Alta");
     expectLine("id: 2; name: Sony Walkman");
     expectLine("id: 3; name: Garmin GPS");
-    
+
     // tag::solrj-query-with-raw-solrparams[]
     final SolrClient client = getSolrClient();
 
@@ -121,7 +123,7 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     for(SolrDocument document : documents) {
       final String id = (String) document.getFirstValue("id");
       final String name = (String) document.getFirstValue("name");
-      
+
       print("id: " + id + "; name: " + name);
     }
     // end::solrj-query-with-raw-solrparams[]
@@ -152,7 +154,7 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     for(SolrDocument document : documents) {
       final String id = (String) document.getFirstValue("id");
       final String name = (String) document.getFirstValue("name");
-      
+
       print("id: "+ id + "; name: " + name);
     }
   }
@@ -194,7 +196,7 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     expectLine("id: 1; name: Fitbit Alta");
     expectLine("id: 2; name: Sony Walkman");
     expectLine("id: 3; name: Garmin GPS");
-    
+
     // tag::solrj-query-bean-value-type[]
     final SolrClient client = getSolrClient();
 
@@ -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());
@@ -263,23 +297,23 @@ public class UsingSolrJRefGuideExamplesTest extends SolrCloudTestCase {
     public TechProduct() {}
   }
   // end::solrj-techproduct-value-type[]
-  
+
   private void expectLine(String expectedLine) {
     expectedLines.add(expectedLine);
   }
-  
+
   private void print(String actualOutput) {
     final String nextExpectedLine = expectedLines.poll();
     assertNotNull("No more output expected, but was asked to print: " + actualOutput, nextExpectedLine);
-    
+
     final String unexpectedOutputMessage = "Expected line containing " + nextExpectedLine + ", but printed line was: "
         + actualOutput;
     assertTrue(unexpectedOutputMessage, actualOutput.contains(nextExpectedLine));
   }
-  
+
   private void ensureNoLeftoverOutputExpectations() {
     if (expectedLines.isEmpty()) return;
-    
+
     final StringBuilder builder = new StringBuilder();
     builder.append("Leftover output was expected but not printed:");
     for (String expectedLine : expectedLines) {