You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ge...@apache.org on 2018/10/17 23:11:01 UTC
lucene-solr:master: SOLR-12856: Small improvements to SolrJ javadocs
Repository: lucene-solr
Updated Branches:
refs/heads/master 4b2136eb3 -> e6f6f352c
SOLR-12856: Small improvements to SolrJ javadocs
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/e6f6f352
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/e6f6f352
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/e6f6f352
Branch: refs/heads/master
Commit: e6f6f352cfc30517235822b3deed83df1ee144c6
Parents: 4b2136e
Author: Jason Gerlowski <ge...@apache.org>
Authored: Wed Oct 17 15:58:48 2018 -0400
Committer: Jason Gerlowski <ge...@apache.org>
Committed: Wed Oct 17 19:10:56 2018 -0400
----------------------------------------------------------------------
.../apache/solr/client/solrj/SolrClient.java | 38 ++++++++++++++++++++
.../solr/client/solrj/impl/CloudSolrClient.java | 21 +++++++++--
.../solrj/impl/ConcurrentUpdateSolrClient.java | 10 +++++-
.../solr/client/solrj/impl/HttpSolrClient.java | 6 ++++
4 files changed, 71 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/e6f6f352/solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java
----------------------------------------------------------------------
diff --git a/solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java b/solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java
index 1c79efe..f435150 100644
--- a/solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java
+++ b/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
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/e6f6f352/solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java
----------------------------------------------------------------------
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 006d6bd..193555a 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.
+ * <p>
+ * If not set, this defaults to 'true' and sends sub-requests in parallel.
+ */
public Builder withParallelUpdates(boolean parallelUpdates) {
this.parallelUpdates = parallelUpdates;
return this;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/e6f6f352/solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java
----------------------------------------------------------------------
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 26af757..e19d278 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.
+ * <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;
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/e6f6f352/solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java
----------------------------------------------------------------------
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 2b60e33..ad845e8 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!");