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

[Brian Stansberry]

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.
> _______________________________________________
> jboss-as7-dev mailing list
> jboss-as7-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev


-- 
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat