[ome-devel] Remote Framework: A review

[Zachary Pincus]

On Aug 17, 2004, at 9:24 AM, Ilya Goldberg wrote:

> With regards to the "API", I do think that this is something that 
> needs to be specified in some sort of API specification language just 
> so that it is very specific, all its rules are enforceable, and there 
> would be some chance to achieve consistency in the API across all 
> languages (DOM is a good example of this - we're really trying to 
> achieve the same thing as was done with DOM).  I don't know a great 
> deal about this, but it seems like either CORBA IDL or WSDL would be 
> appropriate.  Ideally, the Java and C client-side interfaces should be 
> similar if not identical, but I'm not even sure if this is possible.  
> My bias is to do the least amount of work possible.  If we specify the 
> ome-java interface in IDL or WSDL, can't we just have an appropriate 
> compiler spit out our C bindings and not have to do anything else?

Disclaimer: I know very little about the art of interface definition in 
general. However, a month or so ago Harry and I emailed back and forth 
about putting together a WSDL description of the remote API, and I sat 
down to generate such a document.

Unfortunately, there were a few problems that foiled me. The first is 
that most of the methods aren't called directly, but are called via the 
"dispatch" caller. That is, if you want to run method "find" you 
actually call "dispatch" with "find" as a text parameter and the 
parameters to the "find" method thereafter. I don't know if IDL handles 
this better, but WSDL doesn't seem to have a good mechanism to deal 
with this sort of total dependence of output types on input parameter 
values. This could of course be fixed by removing the "dispatch" method 
and allowing the calling of the various methods directly. But I'd 
imagine there's a good reason "dispatch" exists...

This trouble is repeated at a deeper level with all of the DB query 
methods, which can return vastly different DTO structures depending on 
fairly minor changes in the input query. So it doesn't seem to be 
possible to provide any sort of strong typing for the outputs of these 
methods, other than saying that they will be DTO hashes. Even if one's 
interface definition language allows opaque types (a strange thing for 
such a language!), I suspect that code generation tools would barf when 
they see that sort of thing.

Basically, I suspect that, on several levels, the interface may be 
necessarialy more "meta" (pardon the abuse) than WSDL and perhaps IDL 
are able to handle. So perhaps a text description like Doug is working 
on, coupled with good client libraries, are as much as can be asked 
for?

> If that's asking for a little too much, then at least having the API 
> specification will be something to hang your hat on and will keep 
> everyone from wandering off into their own little corners.  Since 
> ome-java is the most generic and low-level API we have, its the right 
> place to start.

I agree. Even if the FM doesn't exist for the OME XML-RPC protocol, 
OME-Java is well-documented and totally encapsulates the network 
transport, so it's pretty easy to point a java programmer at that API. 
At some point here (soon, I hope), OME-C will join it for the 
java-impaired among us.

Zach