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 <n...@pivotal.io> Authored: Tue May 9 15:15:59 2017 -0700 Committer: nabarun <n...@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); }