Apache
/
lucene
mirror of https://github.com/apache/lucene.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SOLR-12856: Small improvements to SolrJ javadocs

This commit is contained in:
Jason Gerlowski 2018-10-17 15:58:48 -04:00
parent 4b2136eb3c
commit e6f6f352cf
4 changed files with 71 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
solr/solrj/src/java/org/apache/solr/client/solrj/SolrClient.java
View File

@ -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

21
solr/solrj/src/java/org/apache/solr/client/solrj/impl/CloudSolrClient.java
View File

@ -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;

10
solr/solrj/src/java/org/apache/solr/client/solrj/impl/ConcurrentUpdateSolrClient.java
View File

@ -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;

6
solr/solrj/src/java/org/apache/solr/client/solrj/impl/HttpSolrClient.java
View File

@ -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!");