[jboss-as7-dev] Detyped and REST configuration API

[David M. Lloyd]

On 11/30/2010 11:24 AM, Brian Stansberry wrote:
> Continuing my reply from last night...
>
> On 11/29/10 10:18 PM, David M. Lloyd wrote:
>> For updates at least, there is a logical "place" for it: whatever
>> registers the ability to handle a specific kind of update could also be
>> required to specify the exact description for the operation (which could
>> possibly even be used for validation purposes, though past experience
>> demonstrates that it is unlikely that we'd be able to provide a truly
>> comprehensive description language for validation).  In my earlier vein,
>> non-CRUD updates could easily contain info about whether it requires an
>> update.  CRUD is trickier.  I'm not sure we can say, "changing this
>> field requires a restart", especially if a field cannot be independently
>> changed without changes to an adjacent related field.  And we can't
>> really say "changing _any_ field on this element requires a restart",
>> because that's just lame if only one field really does require a restart
>> when changed.
>>
>
> This basically means much of the metadata is duplicated -- it's in the
> xsd, and in whatever code provides it as part of this registration
> process. I think that's the way to go though; the detyped API really
> needs to make this information available to clients (i.e. no forcing
> them to interpret xsd), plus a lot of the information (e.g. metrics and
> management operations) isn't rightly part of the xsd.

Yeah there's some duplication here which is inevitable, but I'm not 
going to lose a lot of sleep over it.

> If we're slick we can generate our xsd from whatever Java code registers
> this description to the runtime. I believe Infinispan has done that. I
> believe they use annotations though; if we did something similar we'd
> need to be sure we had a fast mechanism for a subsystem to register this
> information with the runtime.

Yeah this is possible, but not essential.  And JAXB/JBossXB has taught 
me that it's really, really hard to generate a sensible XSD from any 
kind of annotations; it gets worse when your constraints are 
substantially different from the ones JAXB imposes (and ours are).

>> For model elements, I think there's two parts to this.
>>
>> The first part is a sort of implicit contract for common fields.  For
>> example, if we have a common field called "name", we should always treat
>> that field similarly regardless of where it appears as a matter of
>> convention.  In this way, if there is no description available for a
>> given model element and all you have is its data, then you can still do
>> something reasonably intelligent with the field contents.
>>
>
> I agree with the gist of what you are saying, but who is "we" here? "We"
> as writers of consoles and CLIs that consume this API?
>
> Ok, I gotcha, we as model designers need to make sure a "name" has
> consistent semantics in all parts of the model (e.g. is an immutable key.)

Right.  Basically when we use a field name, we should use it in the same 
way at all of its usage sites as a matter of principle.

>> Secondly, we're really dealing with two "kinds" of model elements.  The
>> first "kind" is a model element which is inherent in the core structure
>> of the model, be it host, domain, or server.  The model description for
>> these things should also be inherent in the bootstrap code somehow, i.e.
>> not dynamic.
>>
>> The second "kind" is subsystem configuration.  It would be reasonable to
>> require the model description to be registered at the time the subsystem
>> is initialized.
>
> We need that to be fast and lightweight though. E.g. no scanning of
> subsystem classes for @ManagedProperty. :-)

Definitely.  I'm thinking it can be part of the API for registering 
subsystems - you register your XML handler, and also your update 
handlers (and specify the information about the updates you can handle 
at the same time).

>>> Obtaining a DetypedModelElement
>>>
>>> This seems fairly straightforward. Any AbstractModelElement that is
>>> addressable should be able to expose its state as a DetypedModelElement.
>>> See AbstractAddressableModelElement for an rough implementation of that:
>>
>> I see your addressable model element and raise you... to the base class.
>>     All elements should be addressable.
>>
>> Take the next logical step though: what reason is there to even have a
>> typed model element class?  The only thing you'd ever use it for is
>> getting a detyped representation of it.  So why have so much duplication
>> of code and data spread all over the place.  You could represent each
>> model in a single class of logic plus a detyped element data blob just
>> as effectively, and save the headache of conversion when someone
>> requests a hunk of it.
>
> Assuming the underlying model data were all contained in a detyped data
> structure, the model element classes would really be doing two things:
>
> 1) Type conversion for readers.
> 2) Encapsulation; controlling write access to the detyped data structure.
>
> The former is pretty minor. The latter is pretty important.
>
> We could put all that logic in a single model class (plus one per
> subsystem, since the core model is clueless about subsystems) but that
> will be one monster class.
>
> Ok, concerns duly noted, now I'll think harder about what you are
> saying. :-)
>
> What would this single class do (in the case of writes)? It gets some
> detyped representation of the write, which would include:
>
> 1) the address being updated
> 2) some identifier of the operation being performed
> 3) detyped representation of the parameters
>
> So the model class finds the registered handler for the
> address+operation and passes it the affected DetypedModelElement and the
> parameters?

Again I don't think writes as a generic thing are something we should 
deal with.  I'll revisit this point on the other subthread though, with 
new and exciting insights and arguments.

The class itself wouldn't be too much of a monster.  To be more specific 
about what its responsibilities are:

1) Marshalling to XML - the whole model though, not just piecemeal
2) Providing access to the raw model for the core domain update handlers 
(this is functionally equivalent to the level of encapsulation we do today)
3) Providing access to *copies* of the model or a submodel (this can be 
on a base class - AbstractModel perhaps - the basic query API in essence)

If we did provide a generic update mechanism then it would live here as 
well, but it's not clear to me how we could make that generic without 
adding a lot of complexity.

-- 
- DML