[jboss-as7-dev] AS7 management model descr and CLI

[Alexey Loubyansky]

Sorry for the long email, it's very unlike me but I'm on PTO and kind of 
bored.

Following the call we had, I was going to write about what the CLI needs 
from the managed resources to provide easy ways to add resource-specific 
commands that would allow to add new and modify/remove existing resources.

In a few words, every resource interested in a proper representation in 
management tools has to provide its accurate model description.

Awhile ago quite some were missing even the basic description, e.g. 
supported attributes, operations, etc. Now it looks much better. So, 
thanks for fixing this!

I'd like to explain once again why this is important and how the model 
description is used, so you understand the effects of you put into it.

On the example of [xa-]data-source commands. Each command can add, 
remove or modify a resource. These commands work off of the model 
description. Even the help content is pulled out from the model 
description. So, whatever you put in the resource, attribute or 
operation description will appear as help to your users.

Then the tab-completion for argument names. Some resources expose a lot 
of operations and attributes and remembering all of them is impossible. 
These commands turn operation and attribute names into command arguments 
and allow to tab-complete them, given that they are available in the 
model description, of course.

Further, there could be alternative configurations for some resources, 
e.g. driver-name and driver-class or group-address and socket-binding, 
or local-bind-address and socket-binding, i.e. these are choices, the 
presence of one attribute (or command argument) excludes the presence of 
the other. These relationships between the attributes have to be 
available in the model description too. It'll still work if they aren't 
but, e.g. the tab-completion will suggest all of them at the same time, 
which is confusing and can be considered by the users as a bug. And as a 
bug in the CLI, which I don't want to accept :)
Similar thing with some attributes requiring the presence of other 
attributes, e.g. exception-sorter-properties shouldn't be present unless 
exception-sorter-class is.
There are "alternatives" and "requires" properties in the model 
description to express these things.

To help tab-complete values (e.g. of enum types, like tx isolation) 
would be nice to extend the model description with allowed values.


Commands like [xa-]data-source are not coded in the CLI specifically for 
datasources. They are examples of generic commands. Any subsystem or 
resource can have commands like these, given the model description is 
complete. You can actually add/remove them at runtime, see Managing 
commands at the bottom of 
http://community.jboss.org/wiki/GenericTypeCLICommands

At the end, I'd like to mention once again, I'd like to avoid having 
commands coded specifically to manage some specific resource. The 
advantages for generic commands are:
- avoid duplicated description of resources, their attributes and 
operations;
- any changes to the model (attributes, operations, etc) will be 
immediately available in the CLI w/o additional changes anywhere;
- and just less code to test and maintain.

There will still be other commands like deploy/undeploy that will have 
to be maintained in the CLI itself, though.

Any suggestions or questions, please, let me know.


Alexey