geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dschnei...@apache.org
Subject [48/51] [abbrv] geode git commit: Overhauling the javadocs for the LuceneService
Date Tue, 07 Mar 2017 19:22:11 GMT
Overhauling the javadocs for the LuceneService

Enhancing the javadocs with more detailed descriptions of what the
classes do, adding links to lucene classes where appropriate, and
removing some cruft that didn't match the current implementation.

This closes #410


Project: http://git-wip-us.apache.org/repos/asf/geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/geode/commit/c0633c8d
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/c0633c8d
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/c0633c8d

Branch: refs/heads/feature/GEM-1195
Commit: c0633c8d612847fc284cd8b3f09a4aac214c8a1f
Parents: 6118d54
Author: Dan Smith <upthewaterspout@apache.org>
Authored: Fri Feb 24 17:58:09 2017 -0800
Committer: Dan Smith <upthewaterspout@apache.org>
Committed: Thu Mar 2 14:46:35 2017 -0800

----------------------------------------------------------------------
 geode-assembly/build.gradle                     |   2 +
 .../apache/geode/cache/lucene/LuceneIndex.java  |  17 ++-
 .../apache/geode/cache/lucene/LuceneQuery.java  |  41 +++++-
 .../cache/lucene/LuceneQueryException.java      |   2 +-
 .../geode/cache/lucene/LuceneQueryFactory.java  |  63 +++++---
 .../geode/cache/lucene/LuceneQueryProvider.java |  24 +--
 .../geode/cache/lucene/LuceneResultStruct.java  |  17 +--
 .../geode/cache/lucene/LuceneService.java       | 145 ++++++++++++-------
 .../cache/lucene/LuceneServiceProvider.java     |   2 +-
 .../lucene/PageableLuceneQueryResults.java      |  22 +--
 .../lucene/internal/LuceneQueryFactoryImpl.java |   8 +
 .../apache/geode/cache/lucene/package-info.java |   8 +-
 12 files changed, 226 insertions(+), 125 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-assembly/build.gradle
----------------------------------------------------------------------
diff --git a/geode-assembly/build.gradle b/geode-assembly/build.gradle
index cce5245..1900896 100755
--- a/geode-assembly/build.gradle
+++ b/geode-assembly/build.gradle
@@ -214,6 +214,8 @@ task gfshDepsJar (type: Jar, dependsOn: ':geode-core:classes') {
 def docsDir = file("$buildDir/javadocs")
 task docs(type: Javadoc) {
     options.addStringOption('Xdoclint:none', '-quiet')
+    options.links("https://lucene.apache.org/core/6_4_1/core/")
+    options.links("https://lucene.apache.org/core/6_4_1/queryparser/")
     options.encoding='UTF-8'
     source parent.subprojects*.javadoc*.source
     classpath = files(parent.subprojects*.javadoc*.classpath)

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndex.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndex.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndex.java
index 1069f74..f13c8b3 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndex.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndex.java
@@ -23,34 +23,35 @@ import org.apache.geode.annotations.Experimental;
 
 
 /**
- * An lucene index is built over the data stored in a GemFire Region.
  * <p>
- * An index is specified using a index name, field names, region name.
- * <p>
- * The index name and region name together uniquely identifies the lucene index.
+ * An Lucene index is built over the data stored in a GemFire Region.
+ * </p>
  * <p>
+ * An index is specified using a index name, field names, region name.
+ * </p>
+ * The index name and region name together uniquely identifies the Lucene index.
  * 
  */
 @Experimental
 public interface LuceneIndex {
 
   /**
-   * @return the index name of this index
+   * @return the name of this index
    */
   public String getName();
 
   /**
-   * @return the region name for this index
+   * @return the name of the region that is being indexed
    */
   public String getRegionPath();
 
   /**
-   * @return the indexed field names in a Set
+   * @return the indexed field names
    */
   public String[] getFieldNames();
 
   /**
-   * @return the field to analyzer map
+   * @return a map of what {@link Analyzer} is being used for each indexed field.
    */
   public Map<String, Analyzer> getFieldAnalyzers();
 

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQuery.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQuery.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQuery.java
index 1afb35a..1218dcc 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQuery.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQuery.java
@@ -20,30 +20,57 @@ import java.util.List;
 import org.apache.geode.annotations.Experimental;
 
 /**
- * Provides wrapper object of Lucene's Query object and execute the search.
  * <p>
- * Instances of this interface are created using {@link LuceneQueryFactory#create}.
- * 
+ * A query on a Lucene index. Instances of this interface are created using
+ * {@link LuceneQueryFactory#create}. Once this query is constructed, use one of the find
methods to
+ * find region entries that match this query.
+ * </p>
+ * <p>
+ * Instances obtained from {@link LuceneQueryFactory} are immutable, so they are safe for
reuse and
+ * can be shared by multiple threads.
+ * </p>
+ * <p>
+ * Because Lucene indexes are maintained asynchronously, results returned from the find methods
may
+ * not reflect the most recent updates to the region.
+ * </p>
+ * <p>
+ * Results are returned in order of their score with respect to this query. See
+ * {@link org.apache.lucene.search} for details on how Lucene scores entries.
+ * </p>
  */
 @Experimental
 public interface LuceneQuery<K, V> {
   /**
-   * Execute search and return keys.
+   * Execute the query and return the region keys that match this query, up to the limit
specified
+   * by {@link #getLimit()}.
+   * 
+   * @throws LuceneQueryException if the query could not be parsed or executed.
    */
   public Collection<K> findKeys() throws LuceneQueryException;
 
   /**
-   * Execute search and return values.
+   * Execute the query and return the region values that match this query, up to the limit
specified
+   * by {@link #getLimit()}
+   * 
+   * @throws LuceneQueryException if the query could not be parsed or executed.
    */
   public Collection<V> findValues() throws LuceneQueryException;
 
   /**
-   * Execute search and return list of LuceneResultStruct.
+   * Execute the query and return a list of {@link LuceneResultStruct}s that match this query,
up to
+   * the limit specified by {@link #getLimit()} A {@link LuceneResultStruct} contains the
region
+   * key, value, and a score for that entry.
+   *
+   * @throws LuceneQueryException if the query could not be parsed or executed.
    */
   public List<LuceneResultStruct<K, V>> findResults() throws LuceneQueryException;
 
   /**
-   * Execute the search and get results.
+   * Execute the query and get a {@link PageableLuceneQueryResults}. The
+   * {@link PageableLuceneQueryResults} provides the ability to fetch a page of results at
a time,
+   * as specified by {@link #getPageSize()}
+   *
+   * @throws LuceneQueryException if the query could not be parsed or executed.
    */
   public PageableLuceneQueryResults<K, V> findPages() throws LuceneQueryException;
 

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryException.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryException.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryException.java
index 98c313e..dde8f9a 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryException.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryException.java
@@ -18,7 +18,7 @@ package org.apache.geode.cache.lucene;
 import org.apache.geode.GemFireCheckedException;
 
 /**
- * Thrown when a lucene query fails.
+ * Thrown when a Lucene query fails.
  */
 public class LuceneQueryException extends GemFireCheckedException {
 

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryFactory.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryFactory.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryFactory.java
index 174e7e1..f4bd21c 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryFactory.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryFactory.java
@@ -14,17 +14,22 @@
  */
 package org.apache.geode.cache.lucene;
 
+import org.apache.geode.cache.query.Query;
 import org.apache.lucene.queryparser.classic.ParseException;
 
 import org.apache.geode.annotations.Experimental;
+import org.apache.lucene.queryparser.flexible.standard.StandardQueryParser;
 
 /**
- * Factory for creating instances of {@link LuceneQuery}. To get an instance of this factory
call
+ * Factory for configuring a Lucene query. Use this factory to set parameters of the query
such as
+ * page size, result limit, and query expression. To get an instance of this factory call
  * {@link LuceneService#createLuceneQueryFactory}.
  * <P>
- * To use this factory configure it with the <code>set</code> methods and then
call {@link #create}
- * to produce a {@link LuceneQuery} instance.
- * 
+ * To use this factory configure it with the <code>set</code> methods and then
call one of the
+ * create methods on this class. {@link #create(String, String, String, String)} creates
a query by
+ * parsing a query string. {@link #create(String, String, LuceneQueryProvider)} creates a
query
+ * based on a custom Lucene {@link Query} object.
+ *
  */
 @Experimental
 public interface LuceneQueryFactory {
@@ -40,32 +45,34 @@ public interface LuceneQueryFactory {
   public static final int DEFAULT_PAGESIZE = 0;
 
   /**
-   * Set page size for a query result. The default page size is 0 which means no pagination.
If
-   * specified negative value, throw IllegalArgumentException
-   * 
+   * Set page size for a query result. The default page size is 0 which means no pagination.
+   *
    * @param pageSize
    * @return itself
+   * @throws IllegalArgumentException if the value is less than 0
    */
   LuceneQueryFactory setPageSize(int pageSize);
 
   /**
-   * Set max limit of result for a query If specified limit is less or equal to zero, throw
-   * IllegalArgumentException
-   * 
+   * Set maximum number of results for a query. By default, the limit is set to
+   * {@link #DEFAULT_LIMIT} which is 100.
+   *
    * @param limit
    * @return itself
+   * @throws IllegalArgumentException if the value is less than or equal to zero.
    */
   LuceneQueryFactory setResultLimit(int limit);
 
   /**
-   * Create wrapper object for lucene's QueryParser object using default standard analyzer.
The
-   * queryString is using lucene QueryParser's syntax. QueryParser is for easy-to-use with
human
-   * understandable syntax.
-   * 
+   * Creates a query based on a query string which is parsed by Lucene's
+   * {@link StandardQueryParser}. See the javadocs for {@link StandardQueryParser} for details
on
+   * the syntax of the query string. The query string and default field as passed as is to
+   * {@link StandardQueryParser#parse(String, String)}
+   *
    * @param regionName region name
    * @param indexName index name
-   * @param queryString query string in lucene QueryParser's syntax
-   * @param defaultField default field used by the Lucene Query Parser
+   * @param queryString Query string parsed by Lucene's StandardQueryParser
+   * @param defaultField default field used by the Lucene's StandardQueryParser
    * @param <K> the key type in the query results
    * @param <V> the value type in the query results
    * @return LuceneQuery object
@@ -74,13 +81,29 @@ public interface LuceneQueryFactory {
       String defaultField);
 
   /**
-   * Creates a wrapper object for Lucene's Query object. This {@link LuceneQuery} builder
method
-   * could be used in advanced cases, such as cases where Lucene's Query object construction
needs
-   * Lucene's API over query string.
+   * <p>
+   * Create a query based on a programatically constructed Lucene {@link Query}. This can
be used
+   * for queries that are not covered by {@link StandardQueryParser}, such as range queries.
+   * </p>
+   * <p>
+   * Because Geode may execute the Lucene query on multiple nodes in parallel and {@link
Query} is
+   * not serializable, this method requires a serializable {@link LuceneQueryProvider} that
can
+   * create a {@link Query} on the nodes hosting the Lucene index.
+   * </p>
+   * <p>
+   * Here's an example of using this method to create a range query on an integer field called
+   * "age."
+   * </p>
    * 
+   * <pre>
+   * {@code
+   *   LuceneQuery query = factory.create("index", "region", index -> IntPoint.newRangeQuery("age",
20, 30))
+   * }
+   * </pre>
+   *
    * @param indexName index name
    * @param regionName region name
-   * @param provider constructs and provides a Lucene Query object
+   * @param provider constructs and provides a Lucene {@link Query}.
    * @param <K> the key type in the query results
    * @param <V> the value type in the query results
    * @return LuceneQuery object

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryProvider.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryProvider.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryProvider.java
index 8b1064e..2611293 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryProvider.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneQueryProvider.java
@@ -15,28 +15,32 @@
 
 package org.apache.geode.cache.lucene;
 
+import java.io.DataOutput;
 import java.io.Serializable;
 
+import org.apache.geode.DataSerializer;
 import org.apache.lucene.search.Query;
 
 import org.apache.geode.annotations.Experimental;
 import org.apache.geode.cache.query.QueryException;
 
 /**
- * The instances of this class will be used for distributing Lucene Query objects and
- * re-constructing the Query object. If necessary the implementation needs to take care of
- * serializing and de-serializing Lucene Query object. Geode respects the DataSerializable
contract
- * to provide optimal object serialization. For instance, {@link LuceneQueryProvider}'s toData
- * method will be used to serialize it when it is sent to another member of the distributed
system.
- * Implementation of DataSerializable can provide a zero-argument constructor that will be
invoked
- * when they are read with DataSerializer.readObject.
+ * <p>
+ * A factory for {@link Query} objects. An implementation of this interface is required by
+ * {@link LuceneQueryFactory#create(String, String, LuceneQueryProvider)} so that a query
can be
+ * serialized and distributed to multiple nodes.
+ * </p>
+ * Instances of this interface are serialized using the standard
+ * {@link DataSerializer#writeObject(Object, DataOutput)},
  */
 @Experimental
+@FunctionalInterface
 public interface LuceneQueryProvider extends Serializable {
   /**
-   * @return A Lucene Query object which could be used for executing Lucene Search on indexed
data
-   * @param index local lucene index the query is being constructed against.
-   * @throws LuceneQueryException if the provider fails to construct the query object
+   * @return A {@link Query} which will be executed against a Lucene index.
+   * @param index The {@link LuceneIndex} the query is being executed against.
+   * @throws LuceneQueryException if the provider fails to construct the query object. This
will be
+   *         propagated to callers of the {@link LuceneQuery} find methods.
    */
 
   public Query getQuery(LuceneIndex index) throws LuceneQueryException;

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java
index b922185..4a6481f 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java
@@ -17,34 +17,29 @@ package org.apache.geode.cache.lucene;
 import org.apache.geode.annotations.Experimental;
 
 /**
- * <p>
- * Abstract data structure for one item in query result.
+ * A single result of a Lucene query.
  * 
  */
 @Experimental
 public interface LuceneResultStruct<K, V> {
 
   /**
-   * Return key of the entry
+   * @return The region key of the entry matching the query
    *
-   * @return key
-   * @throws IllegalArgumentException If this struct does not contain key
    */
   public K getKey();
 
   /**
-   * Return value of the entry
+   * @return the region value of the entry matching the query.
    *
-   * @return value the whole domain object
-   * @throws IllegalArgumentException If this struct does not contain value
    */
   public V getValue();
 
   /**
-   * Return score of the query
+   * Return score the score of the entry matching the query. Scores are computed by Lucene
based on
+   * how closely documents match the query. See {@link org.apache.lucene.search} for details
on how
+   * scores are computed.
    *
-   * @return score
-   * @throws IllegalArgumentException If this struct does not contain score
    */
   public float getScore();
 }

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java
index 704abcd..f035442 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java
@@ -19,6 +19,7 @@ import java.util.Map;
 import java.util.concurrent.TimeUnit;
 
 import org.apache.geode.cache.Cache;
+import org.apache.geode.cache.DataPolicy;
 import org.apache.lucene.analysis.Analyzer;
 
 import org.apache.geode.annotations.Experimental;
@@ -26,82 +27,110 @@ import org.apache.geode.cache.GemFireCache;
 import org.apache.geode.cache.lucene.internal.LuceneIndexCreationProfile;
 
 /**
- * LuceneService instance is a singleton for each cache.
- * 
- * It provides handle for managing the {@link LuceneIndex} and create the {@link LuceneQuery}
via
- * {@link LuceneQueryFactory}
- * 
+ *
+ * The LuceneService provides the capability to create Lucene indexes and execute lucene
queries on
+ * data stored in Geode regions. The Lucene indexes are automatically maintained by Geode
whenever
+ * entries are updated in the associated regions.
+ *
+ * <p>
+ * To obtain an instance of LuceneService, use {@link LuceneServiceProvider#get(GemFireCache)}.
+ * </p>
+ * <p>
+ * Lucene indexes can be created using gfsh, xml, or the java API. Below is an example of
creating a
+ * Lucene index with the java API. The Lucene index created on each member that will host
data for
+ * the region.
  * </p>
- * Example: <br>
  * 
  * <pre>
- * At client and server JVM, initializing cache will create the LuceneServiceImpl object,

- * which is a singleton at each JVM. 
- * 
- * At each server JVM, for data region to create index, create the index on fields with default
analyzer:
- * LuceneIndex index = luceneService.createIndex(indexName, regionName, "field1", "field2",
"field3"); 
- * or create index on fields with specified analyzer:
- * LuceneIndex index = luceneService.createIndex(indexName, regionName, analyzerPerField);
- * 
- * We can also create index via cache.xml or gfsh.
- * 
- * At client side, create query and run the search:
- * 
- * LuceneQuery query = luceneService.createLuceneQueryFactory().setLimit(200).setPageSize(20)
- * .setResultTypes(SCORE, VALUE, KEY).setFieldProjection("field1", "field2")
- * .create(indexName, regionName, querystring, analyzer);
- * 
- * The querystring is using lucene's queryparser syntax, such as "field1:zhou* AND field2:gzhou@pivotal.io"
- *  
- * PageableLuceneQueryResults results = query.search();
- * 
- * If pagination is not specified:
- * List list = results.getNextPage(); // return all results in one getNextPage() call
- * or if paging is specified:
- * if (results.hasNextPage()) {
- *   List page = results.nextPage(); // return resules page by page
+ * {
+ *   &#64;code
+ *   LuceneIndex index =
+ *       luceneService.createIndex(indexName, regionName, "field1", "field2", "field3");
  * }
- * 
- * The item of the list is either the domain object or instance of {@link LuceneResultStruct}
  * </pre>
+ * <p>
+ * You can also specify what {@link Analyzer} to use for each field.
+ * </p>
  * 
+ * <pre>
+ * {
+ *   &#64;code
+ *   LuceneIndex index = luceneService.createIndex(indexName, regionName, analyzerPerField);
+ * }
+ * </pre>
+ *
+ * Indexes should be created on all peers that host the region being indexed. Clients do
not need to
+ * define the index, they can directly execute queries using this service.
+ *
+ * <p>
+ * Queries on this service can return either the region keys, values, or both that match
a Lucene
+ * query expression. To execute a query, start with the {@link #createLuceneQueryFactory()}
method.
+ * </p>
  *
+ * <pre>
+ * {
+ *   &#64;code
+ *   LuceneQuery query = luceneService.createLuceneQueryFactory().setLimit(200).create(indexName,
+ *       regionName, "name:John AND zipcode:97006", defaultField);
+ *   Collection<Object> results = query.findValues();
+ * }
+ * </pre>
+ *
+ * <p>
+ * The Lucene index data is colocated with the region that is indexed. This means that the
index
+ * data will be partitioned, copied, or persisted using the same configuration options you
provide
+ * for the region that is indexed. Queries will automatically be distributed in parallel
to cover
+ * all partitions of a partitioned region.
+ * </p>
+ * <p>
+ * Indexes are maintained asynchronously, so changes to regions may not be immediately reflected
in
+ * the index. This means that queries executed using this service may return stale results.
Use the
+ * {@link #waitUntilFlushed(String, String, long, TimeUnit)} method if you need to wait for
your
+ * changes to be indexed before executing a query, however this method should be used sparingly
+ * because it is an expensive operation.
+ * </p>
+ *
+ * <p>
+ * Currently, only partitioned regions are supported. Creating an index on a region with
+ * {@link DataPolicy#REPLICATE} will fail.
+ * </p>
+ * 
  */
 @Experimental
 public interface LuceneService {
 
   /**
    * A special field name that indicates that the entire region value should be indexed.
This will
-   * only work if the region value is a String or Number, in which case a lucene document
will be
+   * only work if the region value is a String or Number, in which case a Lucene document
will be
    * created with a single field with this name.
    */
-  String REGION_VALUE_FIELD = "__REGION_VALUE_FIELD";
+  public String REGION_VALUE_FIELD = "__REGION_VALUE_FIELD";
 
   /**
-   * Create a lucene index using default analyzer.
+   * Create a Lucene index using default analyzer.
    * 
    * @param fields The fields of the object to index. Only fields listed here will be stored
in the
    *        index. Fields should map to PDX fieldNames if the object is serialized with PDX,
or to
-   *        java fields on the object otherwise. The special field name
-   *        {{@link #REGION_VALUE_FIELD}} indicates that the entire value should be stored
as a
-   *        single field in the index.
+   *        java fields on the object otherwise. The special field name {@link #REGION_VALUE_FIELD}
+   *        indicates that the entire value should be stored as a single field in the index.
    */
   public void createIndex(String indexName, String regionPath, String... fields);
 
   /**
-   * Create a lucene index using specified analyzer per field
+   * Create a Lucene index using specified {@link Analyzer} per field. Analyzers are used
by Lucene
+   * to tokenize your field into individual words.
    * 
    * @param indexName index name
    * @param regionPath region name
    * @param analyzerPerField A map of fields to analyzers. See
-   *        {{@link #createIndex(String, String, String...)}} for details on valid values
for
-   *        fields. Each field will be tokenized using the provided Analyzer.
+   *        {@link #createIndex(String, String, String...)} for details on valid values for
fields.
+   *        Each field will be tokenized using the provided Analyzer.
    */
   public void createIndex(String indexName, String regionPath,
       Map<String, Analyzer> analyzerPerField);
 
   /**
-   * Destroy the lucene index
+   * Destroy the Lucene index
    *
    * @param indexName the name of the index to destroy
    * @param regionPath the path of the region whose index to destroy
@@ -109,14 +138,14 @@ public interface LuceneService {
   public void destroyIndex(String indexName, String regionPath);
 
   /**
-   * Destroy all the lucene indexes for the region
+   * Destroy all the Lucene indexes for the region
    *
    * @param regionPath The path of the region on which to destroy the indexes
    */
   public void destroyIndexes(String regionPath);
 
   /**
-   * Get the lucene index object specified by region name and index name
+   * Get the Lucene index object specified by region name and index name
    * 
    * @param indexName index name
    * @param regionPath region name
@@ -125,16 +154,14 @@ public interface LuceneService {
   public LuceneIndex getIndex(String indexName, String regionPath);
 
   /**
-   * get all the lucene indexes.
+   * get all the Lucene indexes.
    * 
    * @return all index objects in a Collection
    */
   public Collection<LuceneIndex> getAllIndexes();
 
   /**
-   * create LuceneQueryFactory
-   * 
-   * @return LuceneQueryFactory object
+   * Create a factory for building a Lucene query.
    */
   public LuceneQueryFactory createLuceneQueryFactory();
 
@@ -146,14 +173,24 @@ public interface LuceneService {
   public Cache getCache();
 
 
-  /**
-   * wait until the current entries in cache are indexed
-   * 
+  /*
+   * Wait until the current entries in cache are indexed.
+   *
+   * Lucene indexes are maintained asynchronously. This means that updates to the region
will not be
+   * immediately reflected in the Lucene index. This method will either timeout or wait until
any
+   * data put into the region before this method call is flushed to the lucene index.
+   *
+   * This method is an expensive operation, so using it before every query is highly discouraged.
+   *
    * @param indexName index name
+   * 
    * @param regionPath region name
+   * 
    * @param timeout max wait time
-   * @param unit granularity of the timeout
-   * @return if entries are flushed within timeout
+   * 
+   * @param unit Time unit associated with the max wait time
+   * 
+   * @return true if entries are flushed within timeout, false if the timeout has elapsed
    */
   public boolean waitUntilFlushed(String indexName, String regionPath, long timeout, TimeUnit
unit)
       throws InterruptedException;

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneServiceProvider.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneServiceProvider.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneServiceProvider.java
index a1f73da..798b5c3 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneServiceProvider.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneServiceProvider.java
@@ -27,7 +27,7 @@ import org.apache.geode.internal.cache.InternalCache;
 @Experimental
 public class LuceneServiceProvider {
   /**
-   * Retrieve or create the lucene service for this cache
+   * Retrieve or create the Lucene service for this cache
    */
   public static LuceneService get(GemFireCache cache) {
     InternalCache internalCache = (InternalCache) cache;

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/PageableLuceneQueryResults.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/PageableLuceneQueryResults.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/PageableLuceneQueryResults.java
index da04d01..9c68ce4 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/PageableLuceneQueryResults.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/PageableLuceneQueryResults.java
@@ -15,30 +15,34 @@
 
 package org.apache.geode.cache.lucene;
 
+import org.apache.geode.annotations.Experimental;
+
 import java.util.Iterator;
 import java.util.List;
 
-import org.apache.geode.annotations.Experimental;
-
 /**
  * <p>
- * Defines the interface for a container of lucene query result collected from function
- * execution.<br>
- * 
- * 
+ * This interface allows you to retrieve a page of query results at a time, using the
+ * {@link #hasNext()} and {@link #next()} methods.
+ * </p>
+ *
+ * Each page is fetched individually from the server, so {@link PageableLuceneQueryResults}
cannot
+ * be serialized and sent to other members.
+ *
+ * @see LuceneQuery#findPages()
+ *
  * @param <K> The type of the key
  * @param <V> The type of the value
  */
 @Experimental
 public interface PageableLuceneQueryResults<K, V> extends Iterator<List<LuceneResultStruct<K,
V>>> {
   /**
-   * @return total number of hits for this query
+   * @return total number of hits for this query across all pages.
    */
   public int size();
 
   /**
-   * Returns the maximum score value encountered. Note that in case scores are not tracked,
this
-   * returns {@link Float#NaN}.
+   * Returns the maximum score value across all pages.
    */
   public float getMaxScore();
 

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/LuceneQueryFactoryImpl.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/LuceneQueryFactoryImpl.java
b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/LuceneQueryFactoryImpl.java
index b798e30..5c088dc 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/LuceneQueryFactoryImpl.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/LuceneQueryFactoryImpl.java
@@ -32,12 +32,20 @@ public class LuceneQueryFactoryImpl implements LuceneQueryFactory {
 
   @Override
   public LuceneQueryFactory setPageSize(int pageSize) {
+    if (pageSize < 0) {
+      throw new IllegalArgumentException("Page size is negative: " + pageSize);
+    }
+
     this.pageSize = pageSize;
     return this;
   }
 
   @Override
   public LuceneQueryFactory setResultLimit(int limit) {
+    if (limit <= 0) {
+      throw new IllegalArgumentException("Limit is <= 0: " + limit);
+    }
+
     this.limit = limit;
     return this;
   }

http://git-wip-us.apache.org/repos/asf/geode/blob/c0633c8d/geode-lucene/src/main/java/org/apache/geode/cache/lucene/package-info.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/package-info.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/package-info.java
index 9541fee..3c2becb 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/package-info.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/package-info.java
@@ -18,14 +18,14 @@
  * <p>
  * All indexing and query operations are performed through the
  * {@link org.apache.geode.cache.lucene.LuceneService} class. See
- * {@link org.apache.geode.cache.lucene.LuceneService} for an example of how to add a lucene
index
- * to a geode region.
+ * {@link org.apache.geode.cache.lucene.LuceneService} for an example of how to add a Lucene
index
+ * to a Geode region.
  * <p>
  *
- * The Lucene indexes created using this API are stored in geode and colocated with the indexed
+ * The Lucene indexes created using this API are stored in Geode and colocated with the indexed
  * region, which means they have the same availability guarantees as the underlying region.
The
  * indexes are maintained asynchronously, so changes to the region may not be immediately
visible in
- * the lucene index.
+ * the Lucene index.
  */
 
 package org.apache.geode.cache.lucene;


Mime
View raw message