[jboss-as7-dev] Detyped API document feedback

[Brian Stansberry]

On 1/4/11 3:29 PM, David M. Lloyd wrote:
> On 01/04/2011 03:17 PM, Heiko W.Rupp wrote:
>>> The registry of operations should be external to the model itself; it
>>> would be a map with a key that corresponds to the operation name plus a
>>> "path" specification to the applicable node type.
>>
>> Did I understand you correctly that the path is not in the key?
>> I think it is also important to be able to navigate to model elements
>> over this path (think xpath expresssion) and to be able to directly
>> address an element /domain1/server14/hornetq/queue1/queue_lenght
>
> Yeah we'd definitely have some sort of direct mapping.  Take my
> operation example:
>
> node = new ModelNode();
> node.get("operation").set("change-bind-port"); // string
> node.get("address").add("base, "domain"); // a list
> node.get("address").add("profile", "web");
> node.get("address").add("subsystem", "web");
> node.get("address").add("connector", "ssl");
> node.get("bind-port").set(8433); // int
> result = connection.execute(node); // goes over remoting
>
> This would map to JMX probably like this:
>
>      jboss.as:base=domain,profile=web,subsystem=web,connector=ssl
>
> And would map to HTTP like this:
>
>
> http://myserver.foo.com/management/base/domain/profile/web/subsystem/web/connector/ssl
>
> ...where http://myserver.foo.com/management/ is the context root of the
> servlet (or com.sun.httpserver.Context or whatever) which acts as the
> REST API endpoint.
>
> Whether we want to go REST-pure and extend this address format to actual
> attributes is something I'm not sure about.
>

It's simple enough to do if it's clear that the attribute name is the 
last segment in the URL. Addresses are composed of pairs; if there's 
something left after the last pair, that's an attribute name.

>>> {
>>>       "operation-name" =>   "change-bind-port",
>>>       "address" =>   [
>>>           ("base"=>"domain"),
>>>           ("profile"=>"*"),
>>>           ("subsystem"=>"web"),
>>>           ("connector"=>"*"),
>>>       ],
>>>       "request-properties" =>   {
>>>           "bind-port" =>   {
>>>               type =>   INTEGER,
>>>               required =>   true,
>>>               min-value =>   0,
>>>               max-value =>   65535,
>>>           }
>>>       },
>>>       "reply-properties" =>   {}
>>> }
>
> To answer your earlier commentary about un-annotated MBeans, we'd want
> to use information like the above to fill out the MBean descriptors as
> fully as possible when (if?) we dynamically generate them.
>

That should be pretty easy to do. The hard part creating the information 
in the first place. But not doing that is not an option.


-- 
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat