Re: [smila-dev] ipc (de)serialization vs. generic handling

[Jürgen Schumacher <juergen.schumacher@xxxxxxxxxxxxx>]

Hi,

more comments inline...

-----Original Message-----
From: smila-dev-bounces@xxxxxxxxxxx [mailto:smila-dev-bounces@xxxxxxxxxxx] On Behalf Of Thomas Menzel
Sent: Thursday, November 24, 2011 9:41 AM
To: Smila project developer mailing list
Subject: Re: [smila-dev] ipc (de)serialization vs. generic handling

>Well, yes. But AFAICS this JsonReqHandler doesn’t do anything JSON specific anymore after I'm thru with it ;) >and hence I would rename it to smth. like IpcRequestHandler or IpcSingleRecordRequestHandler.
>If one still needs JSON specific stuff, then a new JsonRequestHandler  class could be reintroduced and
>inserted in the class hierarchy.

Yes, maybe. The main reason I proposed not to refactor this is that on our side quite a lot depends on that this thing is working, so the inevitable bugs during such a migration would be problematic for us. Additionally, I think it makes sense to do a new more generic base handler from scratch, because there are some more things in the JsonRequestHandler that could be designed better (use annotations do specify allowed methods, for example; do less with inheritance, more with delegation, make original request object available in process method, ...). We could also think of applying some standard Java ReST framework (we have currently no experience with any of them).

>>The correct way to do this in ReST APIs would be to use HTTP header settings:
>>- "Content-Type:" to describe the format (as a mimetype + encoding) of the request body.
>>- "Accept:" to specify which response formats (again as a mimetype) the client can read.
>>And usually the mimetype would not only be something generic like "text/xml" (which would be just any XML) 
>>but "application/vnd.smila.record+xml" to denote that the XML is a SMILA record.
> I had been thinking about this too but, here are the reasons I didn’t suggest it (though I should have 
> written about this)
> - it makes it harder to spec this in a browser/GET setting
> - I'm not sure if we should define unstandardized mime types, or if that is an OK practice. If we have these > then these should be the ones to register the impls. under. If we go this way then we should, include 
> optionally the version of the XML as well, like so: application/vnd.smila.record+xml+.2.0. If the version 
> isn’t given then the current one is the default.

Using vendor mimetypes is absolutely OK in ReST APIs, if you are using a specific format, especially for XML formats: it's like specifying the XML schema of the request/response. And yes, it can include a version, too (however, the "+xml" or "+json" must be at the end, according to conventions). Alternatively I suppose you still could use a more generic XML format like RDF to represent records.
True, for simple browser GETs this is a problem, but you can still use REST client plugins which are available for each (sensible) browser and there you can set header fields, too. For just browsing the API with a real web browser, a good rest API would even produce real HTML, but I think for our purposes JSON is fine as the default format.
See (for example): http://blog.steveklabnik.com/2011/07/03/nobody-understands-rest-or-http.html
I do not claim that our current ReST API is already a "Good ReST API" in every aspect, but if we change something, we should do it in a way to make it More Good (-;

>>Yes, because the IPC code is not meant to be generic, but only to support JSON/BON like formats because 
>>it depends on specified sequences of parse events. I suppose it would possible to add an XML implementation 
>>to handle the standard SMILA XML record form (because that's basically the same sequence of START_MAP, >>START_SEQ, some values, END_MAPPING, etc.), but not to process any generic XML format and map it to records.

>not quite understanding this answer... Might be b/c i dont know really how the IPC reader works. 
>with 'SMILA XML' you mean our XML serialization format version 2.0? and with 'generic XML' mean you mean >another XML representation of a record (that doesn’t exist)? 
>OR if not, I could only think of this meaning, that the IPC reader doesnt support nested Maps/sequences >records?    

It does, of course. The "IPC" reader assumes that the underlying implementation produces a stream of event and data tokens like "a map starts", "a sequence start", "here comes a STRING value", "now there comes a LONG value", "a map ends", etc. (see org.eclipse.smila.ipc.IpcToken). And these events can be simply mapped to the SMILA data model. Incidentally (-; it is simple to produce these events from JSON, and BON is basically a "compressed" version of JSON, so this works, too. Again, when parsing an XML in SMILA record (2.0) format it should be possible to produce these events, too, so yes, there could (should) be an IpcXmlStreamReader/Writer implementation. When parsing an arbitrary XML, it will be hard to map to these tokens, so I suppose the IPC stuff is not suitable for putting an "arbitrary XML" parser under it.

Hope this helps.

>Note: I'm understanding IPC such that it means "Inter Process Communication" and is then an abstract term to >denote diff. serialization formats, that can be arbitrarily structured/capable internally. As consequence XML >should be included as part of. But if this not what IPC is all about and has a diff. scope/intention I might 
>be "barking up the wrong tree"/ "on the wrong track"?

Ok, the term "IPC" probably sounds more generic than it was meant to be. (: It's not supposed to mean "anything two processes could exchange", but it's more like "here's a protocol to exchange data where the actual serialization is still customizable".

Cheers,
Juergen.