[jira] [Commented] (GEODE-3063) Improve docs on default string-based partition resolver

["Darrel Schneider (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/GEODE-3063?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16046944#comment-16046944 ] 

Darrel Schneider commented on GEODE-3063:
-----------------------------------------

StringPrefixPartitionResolver is just implementation of PartitionResolver included with the product.
So everything the docs say about should be in the context of it being a PartitionResolver.

So I think the new docs are wrong with they say: "With custom partitioning, you have three choices"
You still just have two choices: use a PartitionResolver or FixedPartitionResolver.

Since the StringPrefixPartitionResolver is not used by default I would change the new docs to not say "default" in reference to it.

On the docs page titled: "Custom-Partition Your Region Data" I recommend you split the "Procedure" section. The current steps 1-4 are all about implementation and are not needed if you are using StringPrefixPartitionResolver which is already implemented . I would change "program" in this section to "implement". The current step 2 "If you need the resolver’s getName method, program that" is confusing because you currently are forced to implement getName and close (which the docs do not mention) when implementing a resolver. Step 2 make is seem optional. We should tell them that usually the can just implement it to return the name of their class like so: "return getClass().getName();".

Once implemented you can then proceed to configuration. Note that configuration is only needed if you are not specifying the resolver using the key or callback-argument. For StringPrefixPartitionResolver you must use the region configuration (i.e. neither key nor callback-arg can be used).
In the XML examples of configuring a resolver get rid of the name="xxxx" part you have right after "<partition-resolver ". This "name" attributes should never have even been added. The product does not use it and since it is optional there is no reason to clutter up the docs with it.

In discussion of the StringPrefixPartitionResolver the docs say: "The substring that precedes the '|' delimiter will used in the hash function that partitions the entry." I recommend changing this to: "The substring that precedes the '|' delimiter will be returned by "getRoutingObject"." Talking about "the hash function that partitions the entry" is about product internals that means nothing to the user. "getRoutingObject" is documented to they can refer to the PartitionResolver docs on this method to find out what it means.

Step 6 also applies to configuration/deployment and not implementation. It should be changed to also say:
  For java single hop access to work the resolver class needs to have a zero-arg constructor and have no state on it (including any state from the 
  Declarable "init" method). The StringPrefixPartitionResolver will work with java single hop clients.


> Improve docs on default string-based partition resolver
> -------------------------------------------------------
>
>                 Key: GEODE-3063
>                 URL: https://issues.apache.org/jira/browse/GEODE-3063
>             Project: Geode
>          Issue Type: Bug
>          Components: docs
>            Reporter: Karen Smoler Miller
>
> The new default partition resolver at
> org.apache.geode.cache.util.StringPrefixPartitionResolver
> needs more detailed documentation.
> - An example of a string specifying a key in a region operation when this partition resolver is used.
> - What happens if the string specifying a key doesn't have a '|' delimiter.
> - An example of using this partition resolver to colocate two regions.



--
This message was sent by Atlassian JIRA
(v6.4.14#64029)