[jboss-as7-dev] Detyped and REST configuration API

[Anil Saldhana]

One potential benefit of having a JSON service is:
a) custom built UIs based on JQuery.
b) Mobile clients such as Android and iPhone talking to the server.

The JSON world is pretty well defined for lightweight clients.

This was my intent behind the push for a JSON service at Antwerp but was 
lost in the airwaves.

On 11/29/2010 07:54 PM, Brian Stansberry wrote:
> Agreed on the priority, although I want to think a bit about how an xml
> representation would work so we don't discover a gotcha when it's too late.
>
> On 11/29/10 6:30 PM, Anil Saldhana wrote:
>> Brian,
>>      I would vote for JSON interface for the API over xml in terms of
>> priority.
>>
>> Regards,
>> Anil
>>
>> On 11/29/2010 05:15 PM, Brian Stansberry wrote:
>>> Apologies in advance for the long message. I want to kick off a
>>> discussion of the detyped and REST API for domain/host/server
>>> configuration. Much of the following will end up in a wiki, but I wanted
>>> some initial discussion first.
>>>
>>> Goals:
>>>
>>> A "detyped" Java version of the configuration API. Detyped in the sense
>>> that the entire model can be represented using a few general usage
>>> classes on the client classpath,
>>> a la the jboss-meta project used in AS 5/6.
>>>
>>> A REST version of the API. Even less strongly typed, since in the end
>>> clients will fundamentally be consuming the model as text (xml or json).
>>>
>>> Concepts:
>>>
>>> "Addressable" Model Elements
>>>
>>> An "addressable" model element is one that can be uniquely identified
>>> within it's overall model.
>>>
>>> It either:
>>> ** is the only element of its type under its parent element (i.e.
>>> maxOccurs=1 in its schema)
>>> ** or has a single attribute whose value is unique among all elements of
>>> its type under it's parent element
>>>
>>> and it is either
>>> ** the child of an addressable model element
>>> ** or is the root element of the model
>>>
>>> An addressable model element can easily be treated as a resource in a
>>> REST interface. A particular element can be represented in a URL path
>>> either via its element name or via a simple combination of its element
>>> name and the single attribute value.
>>>
>>> It's also easy to create a simple java object to represent the element's
>>> address for use in the "detyped" Java API. For a draft see:
>>>
>>> https://github.com/bstansberry/jboss-as/commit/36763f82e6d82631370adcc154193d02ddf4829c#diff-5
>>> https://github.com/bstansberry/jboss-as/commit/36763f82e6d82631370adcc154193d02ddf4829c#diff-3
>>>
>>> We should strive to have the vast majority of elements in the
>>> domain/host/server models be addressable. This makes it easy to have
>>> highly targeted updates; e.g. a REST PUT can specify the values for a
>>> few attributes in a single element rather than needing to describe a
>>> large portion of the model. So far we have largely met this goal.
>>>
>>> Updates via differencing:
>>>
>>> A model update consists of a client sending a detyped representation of
>>> a part of the model. The update will include all of that portion of the
>>> model; both modified and unmodified properties. The server compares that
>>> detyped representation to the current state of the model and generates
>>> the AbstractModelUpdate objects needed to bring the model up to the
>>> desired state.
>>>
>>> See the DetypedModelElement class for a draft detyped representation of
>>> an addressable model element:
>>>
>>> https://github.com/bstansberry/jboss-as/commit/36763f82e6d82631370adcc154193d02ddf4829c#diff-2
>>>
>>> At this point I used the CompositeValue class from AS 5/6 jboss-meta
>>> library for representing the element's properties. That's certainly open
>>> for discussion.
>>>
>>> "Id-Only" Elements
>>>
>>> The detyped representation of a part or all of the model can include
>>> "id-only" elements. These represent addressable elements but only
>>> include the information necessary to determine the element address, plus
>>> a flag indicating the element is "id-only". These serve as placeholders
>>> within a representation of a larger portion of the model. The purpose of
>>> an id-only element is to allow the client to avoid dealing with
>>> uninteresting portions of the model state, while still being aware of
>>> their existence. They also allow the server to distinguish an update
>>> that removes an element from one that doesn't modify it at all, without
>>> forcing the client to send the entire state of the unmodified element.
>>>
>>> How useful this "id-only" concept will be, I'm not sure. The main use
>>> cases I can see are, for reads, being able to read a client-specified
>>> number of levels of the model without having to consume the whole thing
>>> (imagine a huge domain). For writes the main use case would be an update
>>> that touches a few parts of the model (e.g. add an extension, the
>>> subsystem config for it, a new thread pool for it, a new socket binding
>>> for it) without having to specify all the unrelated stuff in between.
>>>
>>>
>>> Issues:
>>>
>>> Meta-information about Configuration Elements:
>>>
>>> Where should this be stored? Basic things like the primitive types of
>>> various properties, plus more complex things like whether changing a
>>> property requires a restart to take effect. The "detyped" Java version
>>> can include a fair amount of meta-information, but this isn't readily
>>> available via REST. Much of this information also can be (and is) stored
>>> in the domain model schemas themselves, but this forces clients to
>>> access and interpret the schemas to obtain the information. Putting
>>> things like whether a property requires restart to take effect in the
>>> various domain model schemas would also create a tighter coupling
>>> between the schemas; i.e. they should all use the same mechanism to
>>> indicate this, which would imply some common included schema that
>>> defines that mechanism.
>>>
>>> Obtaining a DetypedModelElement
>>>
>>> This seems fairly straightforward. Any AbstractModelElement that is
>>> addressable should be able to expose its state as a DetypedModelElement.
>>> See AbstractAddressableModelElement for an rough implementation of that:
>>>
>>> https://github.com/bstansberry/jboss-as/commit/36763f82e6d82631370adcc154193d02ddf4829c#diff-1
>>>
>>> Determining differences and generating AbstractModelUpdate objects
>>>
>>> If the client passes back a DetypedModelElement to the domain
>>> controller, we need logic to determine the difference between that
>>> detyped representation and the current model and then generate the
>>> needed update objects. A possibility is to have each
>>> AbstractAddressableModelElement be responsible for doing that. A problem
>>> I've seen with that is the class hierarchy for the update classes versus
>>> the model element classes is not clean.
>>> For example, a method like this in AbstractAddressableModelElement won't
>>> work:
>>>
>>> protected abstract void addUpdatesToMatchView(DetypedModelElement
>>> updatedView, List<AbstractModelElementUpdate<?>>    updates);
>>>
>>> It won't work because not all model elements are updated via
>>> AbstractModelElementUpdate; some are done via AbstractDomainModelUpdate,
>>> some via AbstractHostModelUpdate etc.
>>>
>>> Marshalling to from XML/JSON
>>>
>>> The REST API requires the ability to marshall to/from whatever XML and
>>> JSON formats we use for exchanging data with clients. JSON of course is
>>> going to be different from anything we have right now. We need to think
>>> about the XML format. We could just provide and receive snippets that
>>> follow the same schema we use in the domain/host/standalone.xml
>>> documents themselves. However, there are problems with that. The
>>> "id-only" notion described  above is not part of those schemas. Any Atom
>>> links we include in response documents (see Chapter 9 in Bill Burke's
>>> RESTful Java book) will violate the schema as well. As will any metadata
>>> we decide to include. We may be better off with a more generic
>>> representation that more directly maps to something like
>>> DetypedModelElement.
>>>
>>>
>>> Any and all comments on this are appreciated.