[Embedlets-dev] [Arch] Management wire syntax/XML vocabulary

[Andrzej J. T. <an...@ch...>]

Charles pipes up:

> Sounds like we are very much in sync (see following excerpt).

Pretty close.

> Not to get hung up on the syntax, but I would like to point out that
> passing around the XML serialized object itself as the response has one or
> two advantages:
> 
> 1. Multiple attributes can be returned in one request, as opposed to
> multiple requests required for an RPC/SOAP based scheme.

My example was for a single property.....but is easily extended to support 
multiple requests/responses.  How about this:

<requests target="embedlet"
   <request type="light"
 	id="30212"
 	operation="getProperty"
	property="CB_OUTPUT_1" />
   <request type="switch"
          operation="getProperties" />
</requests>
 	
 and the response could be more like:

<responses target="embedlet">
   <response type="light"
	<attribute id="30212" property="CB_OUTPUT_1" value="On" />
   <response type="switch"
	<attribute id="666" property="SW_STATE_1" value="On" />
	<attribute id="666" property="SW_STATE_2" value="Off" />
	<attribute id="999" property="SW_STATE_1 value="Off" />
	<attribute id="1024" property="SW_STATE_3 value="On" />
   <response>
</requests>

Single request (over HTTP/SOAP)...single response.  But multiple operations 
and values.  My prior example was to illustrate the difference/benefits between 
a more generic syntax and an application specific one, specifically for 
Management functions, as is the above example.  Now that I think more about 
it....it's not so much that it's a generic syntax, it's one that is more specific to a 
Management domain than a Persistence one.

The above example is NOT intended to be used for Persistence (serialization), 
that should have it's own vocabulary as I'll discuss below.

In fact, if we use SOAP RPC semantics (as I was intending to all along), then it 
makes sense to use the SOAP schema for this kind of thing where the 
operations are defined by the method called and parameters that are passed 
to it and documented in a WSDL definition.  If you look at SOAP RPC and a 
typical WSDL definition, it does use app-specific element names for the 
methods and parameters and return values, very much like your example.

Given that JMX Management invocations are RPC in nature, and so 
SOAP/HTTP makes a lot of sense, I was thinking that the best way to 
generate this "management vocabulary" would be to take a Web Services 
approach. Take your favourite Java->WSDL generator (Apache Axis has one), 
and point it at the JMX methods we want to be able to support.  Press the 
button....and voila....a WSDL definition appears by magic, and exposes an 
interface that any Web Services capable application can use to call our 
management functions.  At the Outpost Container end, we write a very 
lightweight Protocol Adapter that translates between the WSDL syntax and our 
internal Embedlet Management Service API's (I would suggest that we hand 
code this mapping, since it will be more efficient this way, and we can use very 
small footprint XML libraries like kXML and kSOAP).  Since we will be using 
known (and more or less fixed) JMX API's this approach is a very desireable 
way of implementing the remote management protocols.

It may or may not make sense to use the SOAP RPC approach to 
Persistence.  I think we need to design a good Persistence Service API 
first.....and then under the covers, if the persisted objects will be sent/retrieved 
remotely, it may also make sense to just use the SOAP encoding paradigm 
(through an adapter), but still allow lighter weight, non-XML storage on board 
the device itself when local storage is called for.

> 2. The object packet is self documenting. The requester needs to know only
> the id of the object and not every attribute. This decouples the
> requester/responder very effectively. 

A well designed generic management vocabulary can do the same thing, but 
makes it much easier to write a generic service at the container end that can 
handle all the grunt work for any/all application domains. For a fairly static 
interface definition like JMX, you don't need dynamic/generic parsing that is 
implied by self-documenting syntax.  SOAP/RPC semantics will do just fine.

3. The ability to 'turn-around' the
> packet with modifications forms the basis for Embedlet update. 

This presumes that Persistence and Management should be more tightly 
coupled.  Something I disagree with.

4. The
> 'object packet' scheme supports persistence in any form (flash, file,
> database etc.) based on the provider, without additional code or XML
> vocabulary.

True enough.  However, the issue here is that you have assumed that we 
should use a single vocabulary/schema for both Management and 
Persistence. These two "services" are orthogonal to each other, thus should 
be decoipled and each should probably have it's own underlying 
representation.  If you are persisting a config (for instance) on the remote 
device, then why would you store it in XML format?  It would be much easier to 
store the config object (post-parsing) itself.  By decoupling Management from 
Persistence, this could be done more easily.

Decoupling Persistence and Management provides some very compelling 
benefits:

1) Each can be specialized and optimized for it's own purposes.
2) Easier to implement them as pluggable/optional services without having to 
worry about dependencies.
3) Easier implementation/cleaner of both.  For instance, the Management 
schema would be structured to make the mapping to JMX API's easier (in fact, 
it would be generated by a Java->WSDL Web Services tool).  The Persistence 
mapping would be structured to make storage/retrieval easier.
4) Each schema would be easier to understand in the context of what the 
service is doing, and thus debugging and extension would be easier due to the 
decoupling.  
5) You wouldn't need serialization capability for Management if your app didn't 
need the optional Persistence.
6) It's a best practice to not over-generalize and keep distinct services 
decoupled.  Sure, you can look at apples and oranges as more generic 
fruits....but in this case I think it makes more sense to keep them separate.

> Item 2 leads to a very nice bonus capability where a generic property
> editor without prior knowledge can:
> 
> 1. Query the container for its list of Embedlet names/ids
> 2. Select an Embedlet and send a 'getProperties' request. (Note the plural
> form). 3. Display/edit the returned object properties in a name/value
> grid. 4. Modify and update via a 'setProperties' request that returns the
> modified object packet.

All of these can be done (from a Management perspective) with a vocabulary 
that is more aligned with the JMX API standard as well.  Furthermore, it can be 
done with an Enterprise Management tool like Tivoli, Openview or Unicenter.  
JMX also provides the capability of receiving remote notifications (simple 
matter to translate an embedlet event into a notification), monitoring services 
and more, which do not map cleanly into an application specific XML 
vocabulary, but that we would need to have present for the optional 
Management Service to be able to provide JMX capability easily.

A Persistence schema/vocabulary might be a lot closer to a typical JavaBeans 
serialization approach, and might look a lot more like your suggestions.  SOAP 
RPC syntax does look very much like your approach under the covers, and we 
should probably use SOAP it where it makes sense, since standards are 
"good things(tm)". ;-)

The problem is trying to do both Persistence and Management in a single 
format....I don't think that is wise.

> The responder has control over the properties that are
> exposed/read/written unlike native Java serialization.

Same with the more generic management approach I have outlined.

> The disadvantage of course is that getting the whole object packet is
> likely to be more expensive than a single RPC query, but probably not more
> expensive than 2. If this were an issue the container could filter the
> response down to the requested property.

The exposed API's should provide the level of granularity that makes sense 
(regardless of the on-the-wire encoding which is really driven by the API 
design in most cases).  We could easily provide Management API's that allow 
the manipulation/query of individual component properties, and/or more coarse 
interfaces like sending/getting of a whole config object in one method.  That is 
where the "art" of service interface design comes in....figuring out what level of 
granularity makes the most sense.

Andrzej Jan Taramina
Chaeron Corporation: Enterprise System Solutions
http://www.chaeron.com