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

[Brian Stansberry]

On 11/30/10 4:41 AM, Aslak Knutsen wrote:
> Will the same API reach down into Deployments as well?
>
> Where a Deployments Descriptors are resources and are targets for partial updates?

Short answer: I hope so.

Long answer: Thomas Diesler is looking into providing an implementation 
of the OSGi Configuration Admin service[1] that integrates into the 
domain model (persists configuration via the domain and exposes it via 
the domain model, and hence via this API). He'd like to implement it in 
such a way that it's not an OSGi-bundle only thing, but rather could be 
utilized by any deployment. This would then be the hook that allows 
deployment descriptor information to be made available via the domain 
and for overrides to deployment descriptors to be stored in and applied 
via the domain.

> And will give you information about the content of a deployment(servlets, ejbs, etc)?
>

If the deployers are able to make such information available, I'd like 
to expose it, yes.

[1] 
http://www.osgi.org/javadoc/r4v42/org/osgi/service/cm/ConfigurationAdmin.html
> -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


-- 
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat