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

[Anil Saldhana]

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.