You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geode.apache.org by upthewaterspout <gi...@git.apache.org> on 2017/03/01 01:18:25 UTC
[GitHub] geode pull request #410: Overhauling the javadocs for the LuceneService
GitHub user upthewaterspout opened a pull request:
https://github.com/apache/geode/pull/410
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.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/upthewaterspout/incubator-geode feature/lucene_javadocs
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/geode/pull/410.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #410
----
commit 28ff1174bbfa257b7003e6573c1c6c1022ecdce1
Author: Dan Smith <up...@apache.org>
Date: 2017-02-25T01:58:09Z
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.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] geode issue #410: Overhauling the javadocs for the LuceneService
Posted by upthewaterspout <gi...@git.apache.org>.
Github user upthewaterspout commented on the issue:
https://github.com/apache/geode/pull/410
@jhuynh1 @karensmolermiller @gesterzhou
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] geode pull request #410: Overhauling the javadocs for the LuceneService
Posted by jhuynh1 <gi...@git.apache.org>.
Github user jhuynh1 commented on a diff in the pull request:
https://github.com/apache/geode/pull/410#discussion_r103764691
--- Diff: 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 time, using the {@link #hasNext()}
--- End diff --
at *a time
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] geode pull request #410: Overhauling the javadocs for the LuceneService
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/geode/pull/410
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] geode pull request #410: Overhauling the javadocs for the LuceneService
Posted by jhuynh1 <gi...@git.apache.org>.
Github user jhuynh1 commented on a diff in the pull request:
https://github.com/apache/geode/pull/410#discussion_r103763560
--- Diff: geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneResultStruct.java ---
@@ -17,34 +17,29 @@
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 of the score of the entry matching the query. Scores
--- End diff --
I think you meant "Return score of the entry..."?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] geode pull request #410: Overhauling the javadocs for the LuceneService
Posted by jhuynh1 <gi...@git.apache.org>.
Github user jhuynh1 commented on a diff in the pull request:
https://github.com/apache/geode/pull/410#discussion_r103763944
--- Diff: geode-lucene/src/main/java/org/apache/geode/cache/lucene/LuceneService.java ---
@@ -18,53 +18,77 @@
import java.util.Map;
import java.util.concurrent.TimeUnit;
+import org.apache.geode.cache.DataPolicy;
import org.apache.lucene.analysis.Analyzer;
import org.apache.geode.annotations.Experimental;
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:
+ * {@code
+ * LuceneIndex index = luceneService.createIndex(indexName, regionName, "field1", "field2", "field3");
+ * }
+ * </pre>
+ * <p>
+ * You can also specify what {@link Analyzer} to use for each field.
+ * </p>
+ * <pre>
+ * {@code
* 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
* }
- *
- * The item of the list is either the domain object or instance of {@link LuceneResultStruct}
* </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>
+ * {@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 partitioned, copied, or persisted using the same configuration
--- End diff --
will *be partitioned
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---