[wildfly-dev] Management model attribute groups

[Brian Stansberry]

Off and on we've had discussions around the idea of "attribute groups". 
We've got some use cases that are crying out for such a thing[1], so I'd 
like to propose doing something concrete but simple for these for WF 9, 
ideally in the next month.

A big part of my goal here is to ensure that whatever we do doesn't 
preclude something more advanced in any next generation management 
stuff, e.g. David's stuff.

PART I Concepts

1) What is an attribute group?

The "attribute group" concept I propose is simply a collection of 
attributes associated with the same resource type that are independently 
configurable but are statically declared to be conceptually related. The 
group has a name, and members. The name provides a brief indication of 
the nature of the relationship.

The goal is to provide information to the user to help them better 
understand the relationship between attributes. In particular, 
management tools could use this information to visually present related 
attributes together, e.g. in a tab or other grouping widget in the web 
console.

2) What isn't an attribute group?

Something relevant to writes.

3) Why would I use a child resource instead of an attribute group?

Because the attributes control a discrete piece of functionality and you 
need to be able to turn that on or off as a unit. So you add/remove the 
resource.

4) Why would I use a complex attribute with a bunch of fields instead of 
n>1 simple attributes in a group.

a) Because the attributes control a discrete piece of functionality and 
you need to be able to turn that off as a unit. So users can undefine 
the complex attribute.

b) Because it's a common use case that modifications to n>1 of the 
fields should be done atomically and you don't want to force users to 
use a CLI batch. So you let them use write-attribute and specify the 
value of all the fields.

5) Why would I use an attribute group instead of a child resource?

Because requiring users to add a child resource just to set a bunch of 
values that are really part of the config of the parent resource forces 
them to use a CLI batch to correctly configure the parent resource.

6) Why would I use an attribute group instead a complex attribute?

Because the various attributes should be independently configurable. In 
particular, wiping out the config for all of them by simply undefining 
the complex attribute isn't appropriate.

PART II Proposed Work

1) The basics

We add a piece of metadata to the read-resource-description output for 
an attribute. Name is 'attribute-group', value type is ModelType.STRING, 
value is the name of the group, with 'undefined' allowed.

The group is simply the set of attributes that share the same string.

To implement this, we add public String 
AttributeDefinition.getAttributeGroup() and add support for setting it 
to the relevant Builder. ReadResourceDescriptionHandler outputs the value.

2) XML parsing/marshalling

Modify PersistentResourceXMLDescription such that attributes in an 
attribute group get persisted in their own child element, whose name is 
the name of the group.

PersistentResourceXMLBuilder exposes a setter to allow users to turn 
this on/off for that resource. Turning it off will allow the addition of 
attribute group settings for a resource without requiring an immediate 
corresponding xsd change.

3) Web console

HAL can make use of the additional metadata at its leisure, and as it 
becomes available.

4) Low level management API

The output of read-resource and read-resource-description is modified 
such that attributes are sorted by group name and then by attribute name.

5) CLI

I'm not clear on exactly what to do here, but my instinct is the output 
of the 'ls -l' command should be modified. Probably add a GROUP column 
to the right and sort the order of attributes by group and then by 
attribute name.

PART III Other possible things to do

A :read-attribute-group(name=<groupname>) operation or an 
"attribute-groups=[<groupname>*]" param to :read-resource, to make it 
convenient to read a set of attributes without needing to read the 
entire resource.

We could also consider adding an "attribute-groups" section to the 
read-resource-description output, where a fuller i18n text description 
of the meaning of the group could be written. If we do this we should 
probably do it in WF 9 as it will likely add some sort of requirement to 
subsystem authors that we expose right from the start.


If you're still awake, comments as always are appreciated.

-- 
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat

[1] For example, the JDKORB pull request at 
https://github.com/wildfly/wildfly/pull/7008 uses child resources in a 
number of places where it seems like attribute groups are a better fit.