geode-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Darrel Schneider (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (GEODE-3063) Improve docs on default string-based partition resolver
Date Mon, 12 Jun 2017 18:59:00 GMT

    [ 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)

Mime
View raw message