+ * 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 + *
+ * 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 + *
+ * 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. + *
+ * Also note that rollbacks reset changes made by all 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. + *
+ * Also note that rollbacks reset changes made by all 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 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 006d6bdc9b3..193555a25a3 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 @@ -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 - * to any shard replica (shard leaders and non-leaders). + * Tells {@link Builder} that created clients can send updates 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. + *
+ * If not set, this defaults to 'true' and sends sub-requests in parallel. + */ public Builder withParallelUpdates(boolean parallelUpdates) { this.parallelUpdates = parallelUpdates; return this; 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 26af7571187..e19d2783e0e 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 @@ -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. + *
* 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; 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 2b60e337e4a..ad845e828fe 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 @@ -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!");