[jboss-as7-dev] Detyped model descriptions

[Brian Stansberry]

On 1/8/11 12:14 PM, David M. Lloyd wrote:
> On 01/08/2011 11:28 AM, Brian Stansberry wrote:
>> David,
>>
>> On the detyped2 branch I pushed out the guts of handling generation of
>> detyped model descriptions (fka meta-information fka metadata).
>
> Great!
>
>> https://github.com/bstansberry/jboss-as/commit/22183b15bbdf1236ad5a8eb5d7f420f40ca216a7
>>
>
> I think your initial impression was right though, we can and should find
> a way to combine the operation and model description registries. I just
> ran out of hours last week.
>

No problem; you did a ton last week. Yes, they need to be combined. 
Instead of storing OperationHandler or ModelDescriptionProvider, the 
registry can just store some type that encapsulates everything we want 
to track about an address.

>> Next steps:
>
> 0) Create & agree upon a complete example doman, host, and server model
> so we have a good idea of what we're describing.
>

Agreed.

>> 1) Post the structure of the model descriptions on the wiki.
>>
>> 2) The generic logic Domain/Host/ServerControllers can use to respond to
>> requests for model description data, accessing the above.
>>
>> 3 or 4) When I want some mindless work, create the model descriptions
>> for the core (i.e. excluding subsystems) model.
>>
>> 4 or 3) The generic logic Domain/Host/ServerControllers can use to
>> respond to "read" requests (i.e. reads of the actual model data, not the
>> description of the model.)
>
> Sounds good.
>
>> I'm sorely tempted to have
>> ModelDescriptionProvider.getModelDescription(boolean recursive) also
>> take a Locale param. If it's added there, it should also be added to
>> OperationHandler.getOperationDescription().
>
> Definitely. Like I said though I can merge these two on Monday though if
> you have no objections.
>

That's fine.

> I still think that we should however break apart the general description
> provider concept. When an operation is registered, its description
> provider should be registered too.
>

They are separated. E.g. the structure of the ModelNode returned by 
CommonProviders.NAMED_PATH_PROVIDER will not included any operations; 
the assumption was those would be available via the relevant 
OperationHandlers.

> Either way we also need to decide whether it's OK to have operations on
> an address which doesn't "exist" as far as the general model description
> provider for that element goes, because that will shape the API as well.
>

Any address is an ordered list of key/value pairs. Addresses provided by 
subsystems are going to be relative to the root of the subsystem (are 
proposing otherwise??). So the addresses are going to form a tree.  For 
any node in that tree, we'd have:

1) Optional, but desirable, text description of that node. Even if the 
node only had operations, its likely there's some reasonable text 
description about why those operations are aggregated at that address.

2) Flag indicating whether the node supports storage of head comments 
and tail comments (for persistence back to xml.) Yuck.

3) Information about attributes. Can be none if there are no attributes.

4) Information about parent/child relationships.
a) Some text description of the relationship. Not sure how useful this is.
b) Information about cardinality. Although I think this is always going 
to be 1 | 0..n or 1 | 1..n.

5) Theoretically, information about relationships to other nodes, 
besides the parent/child relationship.


Looking at that, if some address is registered without a model 
description provider, it's simple to use a default one.

1) No description
2) Storage of head/tail comments not supported
3) No attributes
4a) No text description
4b) Cardinality is 1 | 0..n
5) No information about relationships to other nodes


> If we do not, we could do something like have a model node registration
> akin to SubsystemRegistration where you register the model node with a
> description provider, then the returned registration can be used to
> register operations on that same node.
>
> If we do allow operations on arbitrary addresses then we'd just make
> both be top-level methods: registerAddress() vs registerOperation().
>

In the end, isn't what any extension writer going to want to do come 
down to going through a list of addresses, and for each registering a 
ModelDescriptionProvider and a Map<String operationName, 
OperationHandler> ?

-- 
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat