geode-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kmil...@apache.org
Subject geode git commit: GEODE-3042: Quick doc of new string-based partition resolver
Date Fri, 09 Jun 2017 22:51:11 GMT
Repository: geode
Updated Branches:
  refs/heads/release/1.2.0 74328d268 -> 29be69be7


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/29be69be
Tree: http://git-wip-us.apache.org/repos/asf/geode/tree/29be69be
Diff: http://git-wip-us.apache.org/repos/asf/geode/diff/29be69be

Branch: refs/heads/release/1.2.0
Commit: 29be69be749c99f9c185dc5a2b06abcdd8d275c7
Parents: 74328d2
Author: Karen Miller <kmiller@pivotal.io>
Authored: Fri Jun 9 14:37:04 2017 -0700
Committer: Karen Miller <kmiller@pivotal.io>
Committed: Fri Jun 9 15:51:06 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/29be69be/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/29be69be/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/29be69be/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>
 


Mime
View raw message