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

[Aslak Knutsen]

Will the same API reach down into Deployments as well? 

Where a Deployments Descriptors are resources and are targets for partial updates?
And will give you information about the content of a deployment(servlets, ejbs, etc)?

-aslak-


----- "Brian Stansberry" <brian.stansberry at redhat.com> 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.
> -- 
> Brian Stansberry
> Principal Software Engineer
> JBoss by Red Hat
> _______________________________________________
> jboss-as7-dev mailing list
> jboss-as7-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-as7-dev