You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@geode.apache.org by ja...@apache.org on 2017/05/13 00:35:58 UTC
[16/26] geode git commit: GEODE-2907: Removed @Experimental tag from
the Lucene module
GEODE-2907: Removed @Experimental tag from the Lucene module
* Removed the @experimental tag fromt the files in Lucene module.
* Improve on the javadocs for the interfaces present in the Lucene module.
This closes #503
Project: http://git-wip-us.apache.org/repos/asf/geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/geode/commit/e98606d4
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/e98606d4
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/e98606d4
Branch: refs/heads/feature/GEODE-2900
Commit: e98606d43b69fa0e9aa6ea89fcdfdac9133222a4
Parents: c270756
Author: nabarun <nn...@pivotal.io>
Authored: Tue May 9 15:15:59 2017 -0700
Committer: nabarun <nn...@pivotal.io>
Committed: Thu May 11 10:17:25 2017 -0700
----------------------------------------------------------------------
.../apache/geode/cache/lucene/LuceneIndex.java | 45 ++++++++++++-----
.../geode/cache/lucene/LuceneIndexFactory.java | 2 -
.../apache/geode/cache/lucene/LuceneQuery.java | 51 +++++++++++++++++---
.../geode/cache/lucene/LuceneQueryFactory.java | 4 --
.../geode/cache/lucene/LuceneQueryProvider.java | 3 --
.../geode/cache/lucene/LuceneResultStruct.java | 12 +++--
.../geode/cache/lucene/LuceneService.java | 4 --
.../cache/lucene/LuceneServiceProvider.java | 9 ++--
.../lucene/PageableLuceneQueryResults.java | 13 +++--
.../internal/distributed/CollectorManager.java | 10 ++--
.../repository/IndexResultCollector.java | 24 ++++++---
11 files changed, 123 insertions(+), 54 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 f13c8b3..07b5c89 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
@@ -19,39 +19,62 @@ import java.util.Map;
import org.apache.lucene.analysis.Analyzer;
-import org.apache.geode.annotations.Experimental;
-
/**
* <p>
- * An Lucene index is built over the data stored in a GemFire Region.
+ * LuceneIndex represents the Lucene index created over the data stored in Apache Geode regions. The
+ * Lucene indexes are maintained automatically by Apache Geode whenever the entries are updated in
+ * the associated regions. Lucene Indexes are created using {@link LuceneService#createIndexFactory}
+ * by specifying the Lucene index name, the region associated with the Lucene index and the fields
+ * on which the Lucene index is to be created.
* </p>
+ *
+ * <p>
+ * Every Lucene index is uniquely identified by the index name and the name of the region associated
+ * with it. To obtain the LuceneIndex created over a region use
+ * {@link LuceneService#getIndex(String, String)}
+ * </p>
+ *
* <p>
- * An index is specified using a index name, field names, region name.
+ * LuceneIndexes are created using gfsh, xml, or the Java API using LuceneService
+ * {@link LuceneService#createIndexFactory}. More information about LuceneIndex can be found at
+ * {@link LuceneService}
* </p>
- * The index name and region name together uniquely identifies the Lucene index.
- *
*/
-@Experimental
public interface LuceneIndex {
/**
- * @return the name of this index
+ * Returns the name of the LuceneIndex object. This name is provided while creating the
+ * LuceneIndex using {@link LuceneService#createIndexFactory()} create method
+ *
+ * @return Name of the LuceneIndex
*/
public String getName();
/**
- * @return the name of the region that is being indexed
+ * Returns the path of the region on which the LuceneIndex was created. The region name is
+ * provided while creating the LuceneIndex using {@link LuceneService#createIndexFactory()}
+ *
+ * @return Path of the region
*/
public String getRegionPath();
/**
- * @return the indexed field names
+ * Returns a string array containing the fields on which the LuceneIndex was created. These fields
+ * are assigned using the addField method while creating the LuceneIndex using
+ * {@link LuceneService#createIndexFactory()}
+ *
+ * @return String array containing the field names
*/
public String[] getFieldNames();
/**
- * @return a map of what {@link Analyzer} is being used for each indexed field.
+ * Returns a map containing the field name and the {@link Analyzer} used to tokenize the field.
+ * The analyzer to be used on a particular field is set in the addField method while creating the
+ * LuceneIndex using {@link LuceneService#createIndexFactory()}
+ *
+ * @return a map containing pairs of the indexed field name and the corresponding {@link Analyzer}
+ * being used on each indexed field.
*/
public Map<String, Analyzer> getFieldAnalyzers();
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndexFactory.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndexFactory.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndexFactory.java
index 2472ec0..a737cbe 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndexFactory.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneIndexFactory.java
@@ -14,7 +14,6 @@
*/
package org.apache.geode.cache.lucene;
-import org.apache.geode.annotations.Experimental;
import org.apache.lucene.analysis.Analyzer;
import java.util.Map;
@@ -26,7 +25,6 @@ import java.util.Map;
* Configure the index using the add methods, and then call {@link #create(String, String)} to
* create the index.
*/
-@Experimental
public interface LuceneIndexFactory {
/**
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 3318c97..cbee23f 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
@@ -17,7 +17,12 @@ package org.apache.geode.cache.lucene;
import java.util.Collection;
import java.util.List;
-import org.apache.geode.annotations.Experimental;
+import org.apache.geode.CancelException;
+import org.apache.geode.cache.CacheClosedException;
+import org.apache.geode.cache.execute.FunctionException;
+import org.apache.geode.cache.lucene.internal.LuceneQueryImpl;
+import org.apache.geode.cache.persistence.PartitionOfflineException;
+import org.apache.geode.internal.cache.PrimaryBucketException;
/**
* <p>
@@ -37,21 +42,34 @@ import org.apache.geode.annotations.Experimental;
* Results are returned in order of their score with respect to this query.
* </p>
*/
-@Experimental
public interface LuceneQuery<K, V> {
/**
* Execute the query and return the region keys that match this query, up to the limit specified
* by {@link #getLimit()}.
- *
+ *
+ * @return Collection of Apache Geode region keys that satisfy the Lucene query.
* @throws LuceneQueryException if the query could not be parsed or executed.
+ * @throws CacheClosedException if the cache was closed while the Lucene query was being executed.
+ * @throws FunctionException if the function execution mechanism encounters an error while
+ * executing the Lucene query.
+ * @throws PartitionOfflineException if the node containing the buckets required to execute the
+ * Lucene query goes offline.
+ * @throws CancelException if a cancel is in progress while the Lucene query was being executed.
*/
public Collection<K> findKeys() throws LuceneQueryException;
/**
* Execute the query and return the region values that match this query, up to the limit specified
* by {@link #getLimit()}
- *
+ *
+ * @return a Collection of Apache Geode region values that satisfy the Lucene query.
* @throws LuceneQueryException if the query could not be parsed or executed.
+ * @throws CacheClosedException if the cache was closed while the Lucene query was being executed.
+ * @throws FunctionException if the function execution mechanism encounters an error while
+ * executing the Lucene query.
+ * @throws PartitionOfflineException if the node containing the buckets required to execute the
+ * Lucene query goes offline.
+ * @throws CancelException if a cancel is in progress while the Lucene query was being executed.
*/
public Collection<V> findValues() throws LuceneQueryException;
@@ -60,7 +78,14 @@ public interface LuceneQuery<K, V> {
* the limit specified by {@link #getLimit()} A {@link LuceneResultStruct} contains the region
* key, value, and a score for that entry.
*
+ * @return a List of LuceneResultStruct that match the Lucene query
* @throws LuceneQueryException if the query could not be parsed or executed.
+ * @throws CacheClosedException if the cache was closed while the Lucene query was being executed.
+ * @throws FunctionException if the function execution mechanism encounters an error while
+ * executing the Lucene query.
+ * @throws PartitionOfflineException if the node containing the buckets required to execute the
+ * Lucene query goes offline.
+ * @throws CancelException if a cancel is in progress while the Lucene query was being executed.
*/
public List<LuceneResultStruct<K, V>> findResults() throws LuceneQueryException;
@@ -69,17 +94,31 @@ public interface LuceneQuery<K, V> {
* {@link PageableLuceneQueryResults} provides the ability to fetch a page of results at a time,
* as specified by {@link #getPageSize()}
*
+ * @return a PageableLuceneQuery that can be used to fetch one page of result at a time.
* @throws LuceneQueryException if the query could not be parsed or executed.
+ * @throws CacheClosedException if the cache was closed while the Lucene query was being executed.
+ * @throws FunctionException if the function execution mechanism encounters an error while
+ * executing the Lucene query.
+ * @throws PartitionOfflineException if the node containing the buckets required to execute the
+ * Lucene query goes offline.
+ * @throws CancelException if a cancel is in progress while the Lucene query was being executed.
*/
public PageableLuceneQueryResults<K, V> findPages() throws LuceneQueryException;
/**
- * Get page size setting of current query.
+ * Gets the page size setting of current query. This page size is set while creating
+ * {@link LuceneQueryImpl} object
+ *
+ * @return int value representing the page size of the current query
*/
public int getPageSize();
/**
- * Get limit size setting of current query.
+ * Get limit size setting of current query. This value is the maximum number of results that can
+ * be returned by the Lucene query. This value is set while creating the {@link LuceneQueryImpl}
+ * object
+ *
+ * @return int value representing the limit of the current query
*/
public int getLimit();
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 f4bd21c..5cf794a 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
@@ -15,9 +15,6 @@
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;
/**
@@ -31,7 +28,6 @@ import org.apache.lucene.queryparser.flexible.standard.StandardQueryParser;
* based on a custom Lucene {@link Query} object.
*
*/
-@Experimental
public interface LuceneQueryFactory {
/**
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 2611293..2f8a1ed 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
@@ -21,8 +21,6 @@ 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;
/**
* <p>
@@ -33,7 +31,6 @@ import org.apache.geode.cache.query.QueryException;
* Instances of this interface are serialized using the standard
* {@link DataSerializer#writeObject(Object, DataOutput)},
*/
-@Experimental
@FunctionalInterface
public interface LuceneQueryProvider extends Serializable {
/**
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 303acb9..dfb8162 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
@@ -14,22 +14,24 @@
*/
package org.apache.geode.cache.lucene;
-import org.apache.geode.annotations.Experimental;
/**
- * A single result of a Lucene query.
+ * An interface which stores a single result obtained by executing a Lucene query.
*
*/
-@Experimental
public interface LuceneResultStruct<K, V> {
/**
+ * Returns the Apache Geode region key of the result matching the Lucene Query
+ *
* @return The region key of the entry matching the query
*
*/
public K getKey();
/**
+ * Returns the Apache Geode region key of the result matching the Lucene Query
+ *
* @return the region value of the entry matching the query.
*
*/
@@ -37,8 +39,10 @@ public interface LuceneResultStruct<K, V> {
/**
* Return score the score of the entry matching the query. Scores are computed by Lucene based on
- * how closely documents match the query.
+ * how closely the entry matches the query.
*
+ * @return float value representing the score of the entry obtained as a result of executing the
+ * Lucene query.
*/
public float getScore();
}
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 976ab22..e3968e6 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
@@ -14,16 +14,13 @@
*/
package org.apache.geode.cache.lucene;
-import org.apache.geode.annotations.Experimental;
import org.apache.geode.cache.Cache;
import org.apache.geode.cache.DataPolicy;
import org.apache.geode.cache.GemFireCache;
-import org.apache.geode.cache.lucene.LuceneIndexFactory;
import org.apache.lucene.analysis.Analyzer;
import org.apache.lucene.analysis.standard.StandardAnalyzer;
import java.util.Collection;
-import java.util.Map;
import java.util.concurrent.TimeUnit;
/**
@@ -95,7 +92,6 @@ import java.util.concurrent.TimeUnit;
* </p>
*
*/
-@Experimental
public interface LuceneService {
/**
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 798b5c3..3334e73 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
@@ -15,19 +15,22 @@
package org.apache.geode.cache.lucene;
-import org.apache.geode.annotations.Experimental;
import org.apache.geode.cache.GemFireCache;
import org.apache.geode.cache.lucene.internal.InternalLuceneService;
import org.apache.geode.internal.cache.InternalCache;
/**
- * Class for retrieving or creating the currently running instance of the LuceneService.
+ * Class for retrieving or creating the currently running instance of the LuceneService. For more
+ * information about LuceneService see {@link LuceneService}
*
*/
-@Experimental
public class LuceneServiceProvider {
/**
* Retrieve or create the Lucene service for this cache
+ *
+ * @param cache - the Apache Geode cache on which the LuceneService instance is created or already
+ * running.
+ * @return the LuceneService instance
*/
public static LuceneService get(GemFireCache cache) {
InternalCache internalCache = (InternalCache) cache;
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/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 9c68ce4..2d4ea8c 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,8 +15,6 @@
package org.apache.geode.cache.lucene;
-import org.apache.geode.annotations.Experimental;
-
import java.util.Iterator;
import java.util.List;
@@ -34,15 +32,18 @@ import java.util.List;
* @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 across all pages.
+ * Total number of hits matching the Lucene query across all pages.
+ *
+ * @return int value representing total number of hits for this query across all pages.
*/
public int size();
/**
* Returns the maximum score value across all pages.
+ *
+ * @return float value representing the maximum score across all the Lucene result pages.
*/
public float getMaxScore();
@@ -54,7 +55,9 @@ public interface PageableLuceneQueryResults<K, V> extends Iterator<List<LuceneRe
public List<LuceneResultStruct<K, V>> next();
/**
- * True if there another page of results.
+ * True if there is another page of results in PageableLuceneQueryResults.
+ *
+ * @return boolean value, true if another Lucene result page is present, false otherwise.
*/
public boolean hasNext();
}
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/distributed/CollectorManager.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/distributed/CollectorManager.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/distributed/CollectorManager.java
index 8335f7d..81f2eae 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/distributed/CollectorManager.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/distributed/CollectorManager.java
@@ -15,10 +15,8 @@
package org.apache.geode.cache.lucene.internal.distributed;
-import java.io.IOException;
import java.util.Collection;
-import org.apache.geode.annotations.Experimental;
import org.apache.geode.cache.lucene.internal.repository.IndexRepository;
import org.apache.geode.cache.lucene.internal.repository.IndexResultCollector;
@@ -34,10 +32,11 @@ import org.apache.geode.cache.lucene.internal.repository.IndexResultCollector;
*
* @param <C> Type of IndexResultCollector created by this manager
*/
-@Experimental
public interface CollectorManager<C extends IndexResultCollector> {
/**
- * @param name Name/Identifier for this collector. For e.g. region/bucketId.
+ * Creates a new collector to store the results of a Lucene query.
+ *
+ * @param name Name/Identifier for this collector. For e.g. region name/bucketId.
* @return a new {@link IndexResultCollector}. This must return a different instance on each call.
* A new collector would be created for each bucket on a member node.
*/
@@ -46,6 +45,9 @@ public interface CollectorManager<C extends IndexResultCollector> {
/**
* Reduce the results of individual collectors into a meaningful result. This method must be
* called after collection is finished on all provided collectors.
+ *
+ * @param results - Collection of the results of a Lucene query execution.
+ * @return IndexResultCollector containing a reduced set of the results of the Lucene query.
*
*/
C reduce(Collection<C> results);
http://git-wip-us.apache.org/repos/asf/geode/blob/e98606d4/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/repository/IndexResultCollector.java
----------------------------------------------------------------------
diff --git a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/repository/IndexResultCollector.java b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/repository/IndexResultCollector.java
index 56c8627..05b0eda 100644
--- a/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/repository/IndexResultCollector.java
+++ b/geode-lucene/src/main/java/org/apache/geode/cache/lucene/internal/repository/IndexResultCollector.java
@@ -15,29 +15,37 @@
package org.apache.geode.cache.lucene.internal.repository;
-import org.apache.geode.annotations.Experimental;
+import org.apache.geode.cache.lucene.internal.distributed.CollectorManager;
/**
- * Interface for collection results of a query on an IndexRepository. See
- * {@link IndexRepository#query(org.apache.lucene.search.Query, int, IndexResultCollector)}
+ * Interface for the collection that stores the results of a Lucene query executed on an
+ * IndexRepository. See
+ * {@link IndexRepository#query(org.apache.lucene.search.Query, int, IndexResultCollector)} to
+ * understand how Lucene Queries are executed.
*/
-@Experimental
public interface IndexResultCollector {
/**
+ * Returns the name of the Lucene IndexResultCollector that will store the results of the Lucene
+ * query executed on the IndexRepository. The name is set while creating the IndexResultCollector
+ * using {@link CollectorManager#newCollector(String)}
+ *
* @return Name/identifier of this collector
*/
public String getName();
/**
- * @return Number of results collected by this collector
+ * Returns the number of Lucene query results that are being stored in the IndexResultCollector
+ *
+ * @return number of results collected by this collector
*/
public int size();
/**
- * Collect a single document
+ * Collects a corresponding pair of Apache Geode key and Lucene score assigned to the document
+ * which is returned by execution of a Lucene query. This is stored in the IndexResultCollector.
*
- * @param key the gemfire key of the object
- * @param score the lucene score of this object
+ * @param key - Apache Geode key of the object stored in the region
+ * @param score the score of this result document assigned by Lucene
*/
void collect(Object key, float score);
}