[jboss-as7-dev] Detyped API document feedback

[David M. Lloyd]

On 01/04/2011 04:38 PM, Brian Stansberry wrote:
> On 1/4/11 3:29 PM, David M. Lloyd wrote:
>> 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.

Yeah, that's a good point.  I think that something would have to provide 
some indication as to whether a property of an entity is indeed an 
attribute or a sub-element (a side-effect of my dynamic model idea).

As an example, take this hypothetical model segment (hoping you're 
following my ad-hoc syntax here):

{
     "subsystem" => {
         "remoting" => {
             "endpoint-name" => "${jboss.node.name}",
             "server" => {
                 "ssl" => {
                     "socket-binding" => "Remoting-SSL",
                     "authentication-handler" => "MyAuthHandler",
                     "thread-pool-size" => {
                         "count" => 1,
                         "per-cpu" => 1.5f
                     }
                 }
             }
         }
     }
}

I can get the remoting subsystem model element via:

     [("subsystem" => "remoting")]

Assuming we follow the "dangling last item" principle, I can then get 
the endpoint-name attribute then via:

     [("subsystem" => "remoting"), "endpoint-name"]

Now "server" represents a submodel, so to get at the "ssl" server model 
element it's:

     [("subsystem" => "remoting"), ("server" => "ssl")]

To get at the non-simple thread-pool-size attribute then:

     [("subsystem" => "remoting"), ("server" => "ssl"), "thread-pool-size"]

Now to get into weird territory, I can do this:

     [("subsystem" => "remoting"), "server"]

Should I get all the servers as a giant "attribute"?  I think not.  On 
the opposite note, does this:

     [("subsystem" => "remoting"), ("server" => "ssl"), 
("thread-pool-size" => "count")]

...return a simple-valued "model element"?  Again I'd say not.

Probably the best course of action (which you probably have already 
taken) is to have subsystems register their model element subschema in 
some form so that query and update operations can validate that the 
address path at least makes sense.

-- 
- DML