GEODE-3042: Quick doc of new string-based partition resolver
This closes #572
Project: http://git-wip-us.apache.org/repos/asf/geode/repo
Commit: http://git-wip-us.apache.org/repos/asf/geode/commit/8c41fd32
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/8c41fd32
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/8c41fd32
Branch: refs/heads/feature/GEM-1483
Commit: 8c41fd32c4fea2ed3b682ab5c2fdf9d49f58abe9
Parents: d55ef2e
Author: Karen Miller <kmil...@pivotal.io>
Authored: Fri Jun 9 14:37:04 2017 -0700
Committer: Karen Miller <kmil...@pivotal.io>
Committed: Fri Jun 9 15:48:13 2017 -0700
----------------------------------------------------------------------
...partitioning_and_data_colocation.html.md.erb | 13 ++-
...using_custom_partition_resolvers.html.md.erb | 106 +++++++++++++------
.../gfsh/command-pages/create.html.md.erb | 5 +
3 files changed, 89 insertions(+), 35 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/geode/blob/8c41fd32/geode-docs/developing/partitioned_regions/custom_partitioning_and_data_colocation.html.md.erb
----------------------------------------------------------------------
diff --git
a/geode-docs/developing/partitioned_regions/custom_partitioning_and_data_colocation.html.md.erb
b/geode-docs/developing/partitioned_regions/custom_partitioning_and_data_colocation.html.md.erb
index 3e4f185..0876613 100644
---
a/geode-docs/developing/partitioned_regions/custom_partitioning_and_data_colocation.html.md.erb
+++
b/geode-docs/developing/partitioned_regions/custom_partitioning_and_data_colocation.html.md.erb
@@ -31,8 +31,15 @@ This figure shows a region with customer data that is
grouped into buckets by cu
<img src="../../images_svg/custom_partitioned.svg"
id="custom_partitioning_and_data_colocation__image_1D37D547D3244171BB9CADAEC88E7649"
class="image" />
-With custom partitioning, you have two choices:
-
+With custom partitioning, you have three choices:
+
+- **Default string-based partition resolver**. A default partition
+resolver at `org.apache.geode.cache.util.StringPrefixPartitionResolver`
+groups entries into buckets based on a string portion of the key.
+All keys must be strings, specified with a syntax that includes
+a '|' character that delimits the string.
+The substring that precedes the '|' delimiter within the key
+partitions the entry.
- **Standard custom partitioning**. With standard partitioning, you group
entries into buckets, but you do not specify where the buckets reside. Geode
always keeps the entries in the buckets you have specified, but may move the
buckets around for load balancing.
- **Fixed custom partitioning**. With fixed partitioning, you provide
standard partitioning plus you specify the exact member where each data entry
resides. You do this by assigning the data entry to a bucket and to a partition
and by naming specific members as primary and secondary hosts of each partition.
@@ -53,6 +60,6 @@ This figure shows two regions with data colocation where the
data is partitioned
<img src="../../images_svg/colocated_partitioned_regions.svg"
id="custom_partitioning_and_data_colocation__image_525AC474950F473ABCDE8E372583C5DF"
class="image" />
-Data colocation requires the same data partitioning mechanism for all of the
colocated regions. You can use the default partitioning provided by Geode or
custom partitioning.
+Data colocation requires the same data partitioning mechanism for all of the
colocated regions. You can use the default partitioning provided by Geode or
any of the custom partitioning strategies.
You must use the same high availability settings across your colocated regions.
http://git-wip-us.apache.org/repos/asf/geode/blob/8c41fd32/geode-docs/developing/partitioned_regions/using_custom_partition_resolvers.html.md.erb
----------------------------------------------------------------------
diff --git
a/geode-docs/developing/partitioned_regions/using_custom_partition_resolvers.html.md.erb
b/geode-docs/developing/partitioned_regions/using_custom_partition_resolvers.html.md.erb
index 61a0e36..40b2237 100644
---
a/geode-docs/developing/partitioned_regions/using_custom_partition_resolvers.html.md.erb
+++
b/geode-docs/developing/partitioned_regions/using_custom_partition_resolvers.html.md.erb
@@ -27,6 +27,7 @@ If you are colocating data between regions and custom
partitioning the data in t
<a
id="custom_partition_region_data__section_1D7043815DF24308ABE4C78BFDFEE686"></a>
+For the default implementation of string-based partitioning, use
`org.apache.geode.cache.util.StringPrefixPartitionResolver`.
For standard partitioning, use `org.apache.geode.cache.PartitionResolver`. To
implement fixed partitioning, use
`org.apache.geode.cache.FixedPartitionResolver`.
<a
id="custom_partition_region_data__section_5A8D752F02834146A37D9430F1CA32DA"></a>
@@ -34,18 +35,26 @@ For standard partitioning, use
`org.apache.geode.cache.PartitionResolver`. To im
**Prerequisites**
- Create partitioned regions. See [Understanding
Partitioning](how_partitioning_works.html) and [Configuring Partitioned
Regions](managing_partitioned_regions.html#configure_partitioned_regions).
-- Decide whether to use standard custom partitioning or fixed custom
partitioning. See [Understanding Custom Partitioning and Data
Colocation](custom_partitioning_and_data_colocation.html#custom_partitioning_and_data_colocation).
+- Decide whether to use the default implementation of the string-based
partitioning, standard custom partitioning, or fixed custom partitioning. See
[Understanding Custom Partitioning and Data
Colocation](custom_partitioning_and_data_colocation.html#custom_partitioning_and_data_colocation).
- If you also want to colocate data from multiple regions, understand how to
colocate. See [Colocate Data from Different Partitioned
Regions](colocating_partitioned_region_data.html#colocating_partitioned_region_data).
**Procedure**
-1. Using `org.apache.geode.cache.PartitionResolver` (standard partitioning)
or `org.apache.geode.cache.FixedPartitionResolver` (fixed partitioning),
implement the standard partitioning resolver or the fixed partitioning resolver
in one of the following locations, listed here in the search order used by
Geode:
+1. If using `org.apache.geode.cache.PartitionResolver` (standard
partitioning) or `org.apache.geode.cache.FixedPartitionResolver` (fixed
partitioning), implement the standard partitioning resolver or the fixed
partitioning resolver in one of the following locations, listed here in the
search order used by Geode:
- **Custom class**. You provide this class as the partition resolver to
the region creation.
- **Entry key**. You use the implementing key object for every operation
on the region entries.
- **Cache callback argument**. This implementation restricts you to
using methods that accept a cache callback argument to manage the region
entries. For a full list of the methods that take a callback argument, see the
`Region` Javadocs.
+ If using the default implementation of the string-based
+partition resolver,
`org.apache.geode.cache.util.StringPrefixPartitionResolver`,
+specify all keys with the required syntax.
+Keys are strings, and contain the '|' character as a delimiter.
+The substring that precedes the '|' delimiter will used in the hash
+function that partitions the entry.
2. If you need the resolver's `getName` method, program that.
-3. Program the resolver's `getRoutingObject` method to return the routing
object for each entry, based on how you want to group the entries. Give the
same routing object to entries you want to group together. Geode will place the
entries in the same bucket.
+3. If *not* using the default implementation of the string-based
+partition resolver,
+program the resolver's `getRoutingObject` method to return the routing object
for each entry, based on how you want to group the entries. Give the same
routing object to entries you want to group together. Geode will place the
entries in the same bucket.
**Note:**
Only fields on the key should be used when creating the routing object. Do
not use the value or additional metadata for this purpose.
@@ -180,42 +189,75 @@ For standard partitioning, use
`org.apache.geode.cache.PartitionResolver`. To im
```
5. Configure or program the region so Geode finds your resolver for every
operation that you perform on the region's entries. How you do this depends on
where you chose to program your custom partitioning implementation (step 1).
- 1. **Custom class**. Define the class for the region at creation. The
resolver will be used for every entry operation. Use one of these methods:
- - XML:
+ - **Custom class**. Define the class for the region at creation. The
resolver will be used for every entry operation. Use one of these methods:
- ``` pre
- <region name="trades">
- <region-attributes>
- <partition-attributes>
- <partition-resolver name="TradesPartitionResolver">
- <class-name>myPackage.TradesPartitionResolver
- </class-name>
- </partition-resolver>
- <partition-attributes>
- </region-attributes>
- </region>
- ```
- - Java:
+ **XML:**
+ ``` pre
+ <region name="trades">
+ <region-attributes>
+ <partition-attributes>
+ <partition-resolver name="TradesPartitionResolver">
+ <class-name>myPackage.TradesPartitionResolver
+ </class-name>
+ </partition-resolver>
+ <partition-attributes>
+ </region-attributes>
+ </region>
+ ```
+ **Java API:**
- ``` pre
- PartitionResolver resolver = new TradesPartitionResolver();
- PartitionAttributes attrs =
- new PartitionAttributesFactory()
- .setPartitionResolver(resolver).create();
- Cache c = new CacheFactory().create();
+ ``` pre
+ PartitionResolver resolver = new TradesPartitionResolver();
+ PartitionAttributes attrs =
+ new PartitionAttributesFactory()
+ .setPartitionResolver(resolver).create();
- Region r = c.createRegionFactory()
- .setPartitionAttributes(attrs)
- .create("trades");
- ```
- - gfsh:
+ Cache c = new CacheFactory().create();
- You cannot specify a partition resolver using gfsh.
+ Region r = c.createRegionFactory()
+ .setPartitionAttributes(attrs)
+ .create("trades");
+ ```
+ **gfsh:**
+
+ Add the option `--partition-resolver` to the `gfsh create region`
command, specifying the package and class name of the custom partition resolver.
+ - **Entry key**. Use the key object with the resolver implementation for
every entry operation.
+ - **Cache callback argument**. Provide the argument to every call that
accesses an entry. This restricts you to calls that take a callback argument.
+
+ If using the default implementation of the string-based partition
resolver, configure with one of:
+
+ **XML:**
+
+ ``` pre
+ <region name="customers">
+ <region-attributes>
+ <partition-attributes>
+ <partition-resolver name="StringPrefixPartitionResolver">
+
<class-name>org.apache.geode.cache.util.StringPrefixPartitionResolver
+ </class-name>
+ </partition-resolver>
+ <partition-attributes>
+ </region-attributes>
+ </region>
+ ```
+ **Java API:**
+
+ ``` pre
+ PartitionAttributes attrs =
+ new PartitionAttributesFactory()
+ .setPartitionResolver("StringPrefixPartitionResolver").create();
+
+ Cache c = new CacheFactory().create();
+
+ Region r = c.createRegionFactory()
+ .setPartitionAttributes(attrs)
+ .create("customers");
+ ```
+ **gfsh:**
- 2. **Entry key**. Use the key object with the resolver implementation for
every entry operation.
- 3. **Cache callback argument**. Provide the argument to every call that
accesses an entry. This restricts you to calls that take a callback argument.
+ Add the option
`--partition-resolver=org.apache.geode.cache.util.StringPrefixPartitionResolver`
to the `gfsh create region` command.
6. If your colocated data is in a server system, add the `PartitionResolver`
implementation class to the `CLASSPATH` of your Java clients. The resolver is
used for single hop access to partitioned region data in the servers.
http://git-wip-us.apache.org/repos/asf/geode/blob/8c41fd32/geode-docs/tools_modules/gfsh/command-pages/create.html.md.erb
----------------------------------------------------------------------
diff --git a/geode-docs/tools_modules/gfsh/command-pages/create.html.md.erb
b/geode-docs/tools_modules/gfsh/command-pages/create.html.md.erb
index 1f63ead..b23ca56 100644
--- a/geode-docs/tools_modules/gfsh/command-pages/create.html.md.erb
+++ b/geode-docs/tools_modules/gfsh/command-pages/create.html.md.erb
@@ -745,6 +745,7 @@ See [Region Data Storage and
Distribution](../../../developing/region_options/ch
[--recovery-delay=value] [--redundant-copies=value]
[--startup-recovery-delay=value] [--total-max-memory=value]
[--total-num-buckets=value] [--compressor=value] [--off-heap(=value)]
+ [--partition-resolver=value]
```
**Parameters, create region:**
@@ -949,6 +950,10 @@ See [Region Data Storage and
Distribution](../../../developing/region_options/ch
<td>Specifies whether the region values are stored in heap memory or off-heap
memory. When true, region values are in off-heap memory. If the parameter is
specified without a value, the value of true is used.</td>
<td>false</td>
</tr>
+<tr class="even">
+<td><span class="keyword parmname">\-\-partition-resolver</span></td>
+<td>Specifies the full path to a custom partition resolver. To use the
provided default partition resolver, specify <code class="ph
codeph">org.apache.geode.cache.util.StringPrefixPartitionResolver</code>.</td>
+<td></td>
</tbody>
</table>
