SOLR-12856: Small improvements to SolrJ javadocs

solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java

@@ -141,6 +141,10 @@ public abstract class SolrClient implements Serializable, Closeable {
   /**
    * Adds a single document
    *
+   * Many {@link SolrClient} implementations have drastically slower indexing performance when documents are added
+   * individually.  Document batching generally leads to better indexing performance and should be used whenever
+   * possible.
+   *
    * @param doc  the input document
    *
    * @return an {@link org.apache.solr.client.solrj.response.UpdateResponse} from the server
@@ -229,6 +233,10 @@ public abstract class SolrClient implements Serializable, Closeable {
    *
    * The bean is converted to a {@link SolrInputDocument} by the client's
    * {@link org.apache.solr.client.solrj.beans.DocumentObjectBinder}
+   * <p>
+   * Many {@link SolrClient} implementations have drastically slower indexing performance when documents are added
+   * individually.  Document batching generally leads to better indexing performance and should be used whenever
+   * possible.
    *
    * @param collection to Solr collection to add documents to
    * @param obj  the input bean
@@ -435,6 +443,10 @@ public abstract class SolrClient implements Serializable, Closeable {
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
    * waitFlush=true and waitSearcher=true to be inline with the defaults for plain HTTP access
+   * <p>
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
    *
    * @param collection the Solr collection to send the commit to
    *
@@ -452,6 +464,10 @@ public abstract class SolrClient implements Serializable, Closeable {
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
    * waitFlush=true and waitSearcher=true to be inline with the defaults for plain HTTP access
+   * <p>
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
    *
    * @return an {@link org.apache.solr.client.solrj.response.UpdateResponse} containing the response
    *         from the server
@@ -466,6 +482,10 @@ public abstract class SolrClient implements Serializable, Closeable {
   /**
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
+   *
    * @param collection the Solr collection to send the commit to
    * @param waitFlush  block until index changes are flushed to disk
    * @param waitSearcher  block until a new searcher is opened and registered as the
@@ -487,6 +507,10 @@ public abstract class SolrClient implements Serializable, Closeable {
   /**
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
+   *
    * @param waitFlush  block until index changes are flushed to disk
    * @param waitSearcher  block until a new searcher is opened and registered as the
    *                      main query searcher, making the changes visible
@@ -504,6 +528,10 @@ public abstract class SolrClient implements Serializable, Closeable {
   /**
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
+   *
    * @param collection the Solr collection to send the commit to
    * @param waitFlush  block until index changes are flushed to disk
    * @param waitSearcher  block until a new searcher is opened and registered as the
@@ -527,6 +555,10 @@ public abstract class SolrClient implements Serializable, Closeable {
   /**
    * Performs an explicit commit, causing pending documents to be committed for indexing
    *
+   * Be very careful when triggering commits from the client side.  Commits are heavy operations and WILL impact Solr
+   * performance when executed too often or too close together.  Instead, consider using 'commitWithin' when adding documents
+   * or rely on your core's/collection's 'autoCommit' settings.
+   *
    * @param waitFlush  block until index changes are flushed to disk
    * @param waitSearcher  block until a new searcher is opened and registered as the
    *                      main query searcher, making the changes visible
@@ -670,6 +702,9 @@ public abstract class SolrClient implements Serializable, Closeable {
    * Note that this is not a true rollback as in databases. Content you have previously
    * added may have been committed due to autoCommit, buffer full, other client performing
    * a commit etc.
+   * <p>
+   * Also note that rollbacks reset changes made by <i>all</i> clients.  Use this method carefully when multiple clients,
+   * or multithreaded clients are in use.
    *
    * @param collection the Solr collection to send the rollback to
    *
@@ -689,6 +724,9 @@ public abstract class SolrClient implements Serializable, Closeable {
    * Note that this is not a true rollback as in databases. Content you have previously
    * added may have been committed due to autoCommit, buffer full, other client performing
    * a commit etc.
+   * <p>
+   * Also note that rollbacks reset changes made by <i>all</i> clients.  Use this method carefully when multiple clients,
+   * or multithreaded clients are in use.
    *
    * @return an {@link org.apache.solr.client.solrj.response.UpdateResponse} containing the response
    *         from the server

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

@@ -1510,6 +1510,8 @@ public class CloudSolrClient extends SolrClient {
 
     /**
      * Tells {@link Builder} that created clients should send updates only to shard leaders.
+     *
+     * WARNING: This method currently has no effect.  See SOLR-6312 for more information.
      */
     public Builder sendUpdatesOnlyToShardLeaders() {
       shardLeadersOnly = true;
@@ -1518,6 +1520,8 @@ public class CloudSolrClient extends SolrClient {
     
     /**
      * Tells {@link Builder} that created clients should send updates to all replicas for a shard.
+     *
+     * WARNING: This method currently has no effect.  See SOLR-6312 for more information.
      */
     public Builder sendUpdatesToAllReplicasInShard() {
       shardLeadersOnly = false;
@@ -1526,6 +1530,8 @@ public class CloudSolrClient extends SolrClient {
 
     /**
      * Tells {@link Builder} that created clients should send direct updates to shard leaders only.
+     *
+     * UpdateRequests whose leaders cannot be found will "fail fast" on the client side with a {@link SolrException}
      */
     public Builder sendDirectUpdatesToShardLeadersOnly() {
       directUpdatesToLeadersOnly = true;
@@ -1533,15 +1539,24 @@ public class CloudSolrClient extends SolrClient {
     }
 
     /**
-     * Tells {@link Builder} that created clients can send updates
+     * Tells {@link Builder} that created clients can send updates to any shard replica (shard leaders and non-leaders).
-     * to any shard replica (shard leaders and non-leaders).
+     *
+     * Shard leaders are still preferred, but the created clients will fallback to using other replicas if a leader
+     * cannot be found.
      */
     public Builder sendDirectUpdatesToAnyShardReplica() {
       directUpdatesToLeadersOnly = false;
       return this;
     }
 
-    /** Should direct updates to shards be done in parallel (the default) or if not then synchronously? */
+    /**
+     * Tells {@link Builder} whether created clients should send shard updates serially or in parallel
+     *
+     * When an {@link UpdateRequest} affects multiple shards, {@link CloudSolrClient} splits it up and sends a request
+     * to each affected shard.  This setting chooses whether those sub-requests are sent serially or in parallel.
+     * <p>
+     * If not set, this defaults to 'true' and sends sub-requests in parallel.
+     */
     public Builder withParallelUpdates(boolean parallelUpdates) {
       this.parallelUpdates = parallelUpdates;
       return this;

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

@@ -826,6 +826,9 @@ public class ConcurrentUpdateSolrClient extends SolrClient {
     /**
      * The maximum number of threads used to empty {@link ConcurrentUpdateSolrClient}s queue.
      *
+     * Threads are created when documents are added to the client's internal queue and exit when no updates remain in
+     * the queue.
+     * <p>
      * This value should be carefully paired with the maximum queue capacity.  A client with too few threads may suffer
      * decreased throughput as the queue fills up and {@link ConcurrentUpdateSolrClient#request(SolrRequest)} calls
      * block waiting to add requests to the queue.
@@ -840,7 +843,7 @@ public class ConcurrentUpdateSolrClient extends SolrClient {
     }
     
     /**
-     * Provides the {@link ExecutorService} for clients to use when servicing requests.
+     * Provides the {@link ExecutorService} for the created client to use when servicing the update-request queue.
      */
     public Builder withExecutorService(ExecutorService executorService) {
       this.executorService = executorService;
@@ -849,6 +852,8 @@ public class ConcurrentUpdateSolrClient extends SolrClient {
     
     /**
      * Configures created clients to always stream delete requests.
+     *
+     * Streamed deletes are put into the update-queue and executed like any other update request.
      */
     public Builder alwaysStreamDeletes() {
       this.streamDeletes = true;
@@ -857,6 +862,9 @@ public class ConcurrentUpdateSolrClient extends SolrClient {
     
     /**
      * Configures created clients to not stream delete requests.
+     *
+     * With this option set when the created ConcurrentUpdateSolrClient sents a delete request it will first will lock
+     * the queue and block until all queued updates have been sent, and then send the delete request.
      */
     public Builder neverStreamDeletes() {
       this.streamDeletes = false;

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

@@ -926,6 +926,12 @@ s   * @deprecated since 7.0  Use {@link Builder} methods instead.
       return this;
     }
 
+    /**
+     * Adds to the set of params that the created {@link HttpSolrClient} will add on all requests
+     *
+     * @param params a set of parameters to add to the invariant-params list.  These params must be unique and may not
+     *               duplicate a param already in the invariant list.
+     */
     public Builder withInvariantParams(ModifiableSolrParams params) {
       Objects.requireNonNull(params, "params must be non null!");