[Proposal] Changes to the experimental cluster configuration API.

[Patrick Rhomberg <pr...@apache.org>]

Hello, all!

  I would like to make a few changes to our experimental
ClusterConfigurationService interface, focusing on better ease-of-use and
matching intuition.  The majority of these can be achieved very simply by
regenerating our configuration objects from the cache XSD and passing a
JAXB bindings file.  Importantly, using a bindings file allows us to
guarantee that we continue to respect the XSD during marshaling and
usmarshaling of the cluster configuration objects, as well as providing
explicit documentation to future developers about the differences between
the Java implementation and the XSD specification.

A) Some fields (mostly port numbers) are specified in the cache XSD to be
String, but are more naturally Integers.
B) The XSD specifies many `xsd:choice' elements, which generate an
ambiguous mixed-type JAX container.  These should be split to be separate
fields with distinct setters and getters in the Java configuration
objects.  (Much of this has already been done manually.)
C) Those `xsd:sequence' elements, which become `List<...>' fields in the
corresponding Java objects, should have field, setter, and getter names
that clearly indicate the plurality of that field (e.g., "List<String>
getValues()" rather than "List<String> getValue()").
D) Those attributes in the XSD with fixed values should, in the Java
configuration object, be represented with `public static final' fields.
E) Every cluster configuration object should be Serializable so that the
objects may be sent from locators to members.

Thoughts?  Anyone who has been using the experimental interface, do you
have other input on how to make it better while still adhering (more or
less) to the specification of the cache XSD?

Also related, please see my other email regarding the intent of
CacheElement.

Imagination is Change.
~Patrick Rhomberg

Re: [Proposal] Changes to the experimental cluster configuration API.

[John Blum <jb...@pivotal.io>]

Perhaps a reference to the "experimental" interface would be helpful.  This
"specification" page (
https://cwiki.apache.org/confluence/display/GEODE/Public+Interface+to+Cluster+Configuration+Service)
contains
no links.

*Main question... again, why should the ClusterConfigurationService
interface have anything to do with XML/XSD, at all, or any other
configuration "format" for that matter?*

It could be stored "under-the-hood" as XML, as JSON, as YML, as a flat
file, in a Database, in Geode itself, in a "Configuration Server", anything.

The point being, you have 1 ClusterConfigurationService implementation and
possibly many ClusterConfigurationRepository (DAO) instances (i.e. XML,
JSON, YML, etc) used by the ClusterConfigurationService to persist and
access the configuration, from whatever data source.  This is the
proper "*Separation
of Concerns*".

As a developer using the ClusterConfigurationService, I don't care what the
underlying format it is stored in.  All I care about is, if I add an
[OQL|Lucene] Index to the *Region* that it gets "recorded/remembered".
Additionally, I am also thinking that by "extension" it also automatically
create the object for me in addition to recording it.

Now, to address some of your other points...


A) Enforcing types at the schema-level is a mixed bag.  My enforcing a port
number to be an Integer, you preclude that element attribute (e.g.
<cache:server
port=11235/>) from using a property placeholder (e.g. <cache:server
port="${geode.cache.server.port:11235}"/>).'

Typically, allowing this type of flexibility in configuration means the
"parser" is responsible for validation, which is not wrong.

This is simply a choice.


B) I would not limit the parser implementation used by the "
ClusterConfigurationRepository" to just JAXB (in the case of XML).

C) Agreed

D) Eh, some seemingly "fixed" values like say Eviction "action" on a
REPLICATE Region (which is just OVERFLOW_TO_DISK) still have a range of
values [1] in other cases.  Perhaps it has a getter, preferably returning
an Enum value, but no setter.

E) No opinion.

-John


[1]
http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/ExpirationAction.html


On Thu, Apr 19, 2018 at 5:04 PM, Patrick Rhomberg <pr...@apache.org>
wrote:

> Hello, all!
>
>   I would like to make a few changes to our experimental
> ClusterConfigurationService interface, focusing on better ease-of-use and
> matching intuition.  The majority of these can be achieved very simply by
> regenerating our configuration objects from the cache XSD and passing a
> JAXB bindings file.  Importantly, using a bindings file allows us to
> guarantee that we continue to respect the XSD during marshaling and
> usmarshaling of the cluster configuration objects, as well as providing
> explicit documentation to future developers about the differences between
> the Java implementation and the XSD specification.
>
> A) Some fields (mostly port numbers) are specified in the cache XSD to be
> String, but are more naturally Integers.
> B) The XSD specifies many `xsd:choice' elements, which generate an
> ambiguous mixed-type JAX container.  These should be split to be separate
> fields with distinct setters and getters in the Java configuration
> objects.  (Much of this has already been done manually.)
> C) Those `xsd:sequence' elements, which become `List<...>' fields in the
> corresponding Java objects, should have field, setter, and getter names
> that clearly indicate the plurality of that field (e.g., "List<String>
> getValues()" rather than "List<String> getValue()").
> D) Those attributes in the XSD with fixed values should, in the Java
> configuration object, be represented with `public static final' fields.
> E) Every cluster configuration object should be Serializable so that the
> objects may be sent from locators to members.
>
> Thoughts?  Anyone who has been using the experimental interface, do you
> have other input on how to make it better while still adhering (more or
> less) to the specification of the cache XSD?
>
> Also related, please see my other email regarding the intent of
> CacheElement.
>
> Imagination is Change.
> ~Patrick Rhomberg
>



-- 
-John
john.blum10101 (skype)

Re: [Proposal] Changes to the experimental cluster configuration API.

[Michael William Dodge <md...@pivotal.io>]

Perhaps org.apache.geode.DataSerializable or org.apache.geode.internal.DataSerializableFixedID instead of java.io.Serializable?

Sarge

> On 19 Apr, 2018, at 17:04, Patrick Rhomberg <pr...@apache.org> wrote:
> 
> E) Every cluster configuration object should be Serializable so that the
> objects may be sent from locators to members.