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

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/36763f82e6d82631370adcc154... https://github.com/bstansberry/jboss-as/commit/36763f82e6d82631370adcc154... 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/36763f82e6d82631370adcc154... 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/36763f82e6d82631370adcc154... 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