subject:"\[GitHub\] geode pull request #518\: GEODE\-2913 Update Lucene index documentation"

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-19 Thread karensmolermiller

Github user karensmolermiller commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117567599
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -219,7 +219,7 @@ at TestClient.main(TestClient.java:59)
 ```
 - If the Lucene index is not created prior to creating the region,
 an exception will be thrown while attempting to create the region,
--- End diff --

Thanks.  I've made the correction.


---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-18 Thread dihardman

Github user dihardman commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117387903
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -219,7 +219,7 @@ at TestClient.main(TestClient.java:59)
 ```
 - If the Lucene index is not created prior to creating the region,
 an exception will be thrown while attempting to create the region,
--- End diff --

Please change 'create the region' to 'create a Lucene index'


---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117123398
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
+
+``` pre

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117123228
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
+
+``` pre

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117122942
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
--- End diff --

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117122734
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
+
+``` pre

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117122540
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
+
+``` pre

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117122461
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
+
+1. Export all region data
+2. Destroy the Lucene index
+3. Destroy the region
+4. Create a new index
+5. Create a new region without the user-defined business logic callbacks
+6. Import the region data with the option to turn on callbacks. 
+The callbacks will be to invoke a Lucene async event listener to index
+the data.
+7. Alter the region to add the user-defined business logic callbacks
+
+## Additional Gfsh Commands
+
+See the [gfsh describe lucene 
index](gfsh/command-pages/describe.html#describe_lucene_index") command 
reference page for the command that prints details about
+a specific index.
+
+See the [gfsh list lucene 
index](gfsh/command-pages/list.html#list_lucene_index") command reference page
+for the command that prints details about the 
+Lucene indexes created for all members.
+
+# Requirements and Caveats
+
+- Join queries between regions are not supported.
+- Nested objects are not supported.
+- Lucene indexes will not be stored within off-heap memory.
+- Lucene queries from within transactions are not supported.
+On an attempt to query from within a transaction,
+a `LuceneQueryException` is thrown, issuing an error message
+on the client (accessor) similar to:
+
+``` pre
+Exception in thread "main" 
org.apache.geode.cache.lucene.LuceneQueryException:
+ Lucene Query cannot be executed within a transaction
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findTopEntries(LuceneQueryImpl.java:124)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:98)
+at 
org.apache.geode.cache.lucene.internal.LuceneQueryImpl.findPages(LuceneQueryImpl.java:94)
+at TestClient.executeQuerySingleMethod(TestClient.java:196)
+at TestClient.main(TestClient.java:59)
+```
+- If the Lucene index is not created prior to creating the region,
+an exception will be thrown while attempting to create the region,
+issuing an error message simlar to:
+
+``` pre

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117121920
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -135,4 +117,164 @@ gfsh> lucene search --regionName=/orders 
-queryStrings="John*" --defaultField=fi
 
 
 ```
+## Queries
 
+### Gfsh Example to 
Query using a Lucene Index
+
+For details, see the [gfsh search 
lucene](gfsh/command-pages/search.html#search_lucene") command reference page.
+
+``` pre
+gfsh> lucene search --regionName=/orders -queryStrings="John*" 
--defaultField=field1 --limit=100
+```
+
+### Java API Example 
to Query using a Lucene Index
+
+``` pre
+LuceneQuery query = 
luceneService.createLuceneQueryFactory()
+  .setResultLimit(10)
+  .create(indexName, regionName, "name:John AND zipcode:97006", 
defaultField);
+
+Collection results = query.findValues();
+```
+
+## Destroying an 
Index
+
+Since a region destroy operation does not cause the destruction
+of any Lucene indexes,
+destroy any Lucene indexes prior to destroying the associated region.
+
+### Java API Example 
to Destroy a Lucene Index
+
+``` pre
+luceneService.destroyIndex(indexName, regionName);
+```
+An attempt to destroy a region with a Lucene index will result in
+an `IllegalStateException`,
+issuing an error message similar to:
+
+``` pre
+java.lang.IllegalStateException: The parent region [/orders] in colocation 
chain cannot be destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+at 
org.apache.geode.internal.cache.PartitionedRegion.checkForColocatedChildren(PartitionedRegion.java:7231)
+at 
org.apache.geode.internal.cache.PartitionedRegion.destroyRegion(PartitionedRegion.java:7243)
+at 
org.apache.geode.internal.cache.AbstractRegion.destroyRegion(AbstractRegion.java:308)
+at 
DestroyLuceneIndexesAndRegionFunction.destroyRegion(DestroyLuceneIndexesAndRegionFunction.java:46)
+```
+### Gfsh Example to 
Destroy a Lucene Index
+
+For details, see the [gfsh destroy lucene 
index](gfsh/command-pages/destroy.html#destroy_lucene_index") command reference 
page.
+
+The error message that results from an attempt to destroy a region
+prior to destroying its associated Lucene index
+issues an error message similar to:
+
+``` pre
+Error occurred while destroying region "orders".
+ Reason: The parent region [/orders] in colocation chain cannot be 
destroyed,
+ unless all its children [[/indexName#_orders.files]] are destroyed
+```
+
+## Changing an Index
+
+Changing an index requires rebuilding it.
+Implement these steps in `gfsh` to change an index.
--- End diff --

Change period to colon after "index."


---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread joeymcallister

Github user joeymcallister commented on a diff in the pull request:

https://github.com/apache/geode/pull/518#discussion_r117119685
  
--- Diff: geode-docs/tools_modules/lucene_integration.html.md.erb ---
@@ -35,85 +35,67 @@ The Apache Lucene integration:
 For more details, see Javadocs for the classes and interfaces that 
implement Apache Lucene indexes and searches, including
 `LuceneService`, `LuceneQueryFactory`, `LuceneQuery`, and 
`LuceneResultStruct`.
 
-## Using the Apache Lucene Integration
+# Using the Apache Lucene Integration
 
-You can create Apache Lucene indexes through a Java API, through the 
`gfsh` command-line utility, or by means of
-the `cache.xml` configuration file.
+You can interact with Apache Lucene indexes through a Java API,
+through the `gfsh` command-line utility,
+or by means of the `cache.xml` configuration file.
 
-To use Apache Lucene Integration, you will need two pieces of information:
+To use Apache Lucene to create and uses indexes,
+you will need two pieces of information:
 
 1.  The name of the region to be indexed or searched
 2.  The names of the fields you wish to index
 
+## Key Points ###
 
-### Key Points ###
-
+- Apache Lucene indexes are supported only on partitioned regions.
+Replicated region types are *not* supported.
+- Lucene indexes reside on servers.
+There is no way to create a Lucene index on a client.
 - Only top level fields of objects stored in the region can be indexed.
-- Apache Lucene indexes are supported only on Partitioned regions.
 - A single index supports a single region. Indexes do not support multiple 
regions.
 - Heterogeneous objects in single region are supported.
--- End diff --

in "a" single region?


---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

2017-05-17 Thread karensmolermiller

GitHub user karensmolermiller opened a pull request:

https://github.com/apache/geode/pull/518

GEODE-2913 Update Lucene index documentation

This update needs detailed reviews.  Is the information now correct?  And, 
is there any missing documentation for Lucene indexes?
@joeymcallister @davebarnes97 @upthewaterspout @jhuynh1 @nabarunnag 
@boglesby @dihardman  The more the merrier.  Please review. . .

You can merge this pull request into a Git repository by running:

$ git pull https://github.com/karensmolermiller/geode feature/GEODE-2913

Alternatively you can review and apply these changes as the patch at:

https://github.com/apache/geode/pull/518.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 #518


commit 065b2ccbec3853bcd072240b72ff4e5b9e4fc881
Author: Karen Miller 
Date:   2017-05-17T21:10:42Z

GEODE-2913 Update Lucene index documentation




---
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 infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

[GitHub] geode pull request #518: GEODE-2913 Update Lucene index documentation

11 matches

Site Navigation

Mail list logo

Footer information