[ome-devel] Understanding the 'Big Picture' behind the OME API

Fri Sep 11 16:52:35 BST 2009

Hi Nick!

If you want to understand the server-client communication you should
take a look at the Ice manual. I just read chapters 2 and 3 and
looked into details when I needed them.

Ice provides a middleware that allows to write server client
applications with object oriented communication. Actually, when you
work with the OMERO service objects in your client you have a proxy
with a remote object of that service on the server that has access to
the filesystem, database etc...
In order to work with the objects that are defined on the server, your
client needs to know *how* they are defined. You need header files and
a library in order to work with them. That's where slice comes into
the game. You define your API, services, objects that hold data etc.
in the slice language and a code generator creates the header and
implementation files for you which are needed to instantiate them.
That's not the full truth, as objects methods are not implemented,
because slice does not allow to define method logic, it just defines
the interface.

So, the Omero server is an application that defines some services and
objects which should be exposed to client applications. The developers
took the slice language to write the definitions of these to generate
the library and header files to create client applications.

Thus, the best place to look for the methods defined in the API are
the slice files. But I also often have to look into the header file to
get the method signature right.

The nice thing about Ice and the slice code generator is that it
produces code for different target languages. All the basic types and
containers are nicely mapped to the standard containers of that
language. So when you define a method in slice that returns a list,
you get a python list, a c++ std::vector, a Java list etc. in the code
that is generated.

Ice itself is provides the necessary parts that are needed for the
communication in the different target languages and most of the time
you don't care, it happens behind the scenes, in particular if you
just work with the API on the client side.

I hope that helps a little bit to understand the big picture.

Best wishes! Bernhard

On Thu, Sep 10, 2009 at 5:32 PM, Nick Perry <nperry at stanford.edu> wrote:
> Okay, so having read this page
> (http://trac.openmicroscopy.org.uk/omero/wiki/OmeroClients?onlycpp) about
> 1000 times, I'm ready to test if I finally understand what's going on here.
> I'm just going to start listing points/concepts, so if anyone can just
> confirm/correct as they see fit, that would be extremely helpful. It could
> also probably be useful in helping clean up that page since it is rather
> confusing (to someone who didn't develop this stuff, anyway).
>
> - ICE provides generic types (primitives, sequences, dictionaries, etc) that
> serve as the 'middle-man' for converting between those types between
> languages (ie, going from a list in python to a vector in C++, or something
> like that via the Ice 'sequence'). The reason for using ICE is so that
> people can write client stuff in any of the 4 languages (Python, Java, C++,
> Matlab) and everything gets converted the same way. All the information
> about the types provided and what they convert to in each language are found
> in the slice definitions that can be found here:
> https://trac.openmicroscopy.org.uk/omero/browser/trunk/components/blitz/resources/omero
>
> - From the types that ICE provides (primitives, sequences, etc), OME made a
> bunch of objects, which are the objects that get passed to and from (along
> with the ICE types) the server from the client. However, once these objects
> are on the client side (my side) I can cast them back to their native
> language. For example, if I have a sequence of objects
> (omero::api::IObjectList), I can cast it back to a vector of those objects
> in C++ (a vector of IObjects).
>
> Question: Where is the master list of objects? Right now, I guess I can just
> check out Image.h to find out about the Image class, but there must be a
> list online somewhere?
>
> Question: Is Image a subclass of IObject? Similar to how Map is a subclass
> of Object in Java (hopefully I'm using my terminology correctly...)
>
> - Every OME object (for example, Image) has a constructor with an 'I' added
> (ImageI(), for example) which returns a pointer (ImagePtr) to that object,
> all provided by the API library.
>
> - In addition to objects, OME also made a bunch of methods. If i were to
> click through each service on
> http://trac.openmicroscopy.org.uk/omero/wiki/OmeroApi I would see every
> method available to me through the API, and know which category of use it
> belongs to.
>
> Question: If this is not the case, are all the methods defined here
> (http://hudson.openmicroscopy.org.uk/job/OMERO/javadoc/) under ome.api?
>
> - I can use normal C++ types in my code, and ICE handles converting it to
> the 'generalized' form when it's compiled that the (Blitz?) server can
> understand. The server otherwise doesn't understand just plain C++ types
> (especially the ones the other 3 languages don't share). However, sometimes
> in my code, like when a method returns an object used by ICE (for example, a
> omero::api::IObjectList), i need to write that as what is being returned in
> my code. But, I can immediately cast it to vector if I wanted to. So in my
> code I can use both the ICE types and c++ types that ICE supports, and
> everything will be ok.
>
> Question: Will everything be ok..?
>
> - rtypes just give primities in a 'wrapper' that allow them to be NULL. kind
> of like how Integer is a wrapper for an int in Java to provide special
> benefits.
>
> In summary:
>
> - ICE makes my basic types (in my incorrect vocabulary, my arrays, maps,
> ints, floats, etc) (documentation:
> https://trac.openmicroscopy.org.uk/omero/browser/trunk/components/blitz/resources/omero)
> - OME made objects that utilize the above ICE basic types (documentation: i
> have no idea)
> - OME made methods for the above OME objects and ICE basic types used to
> communicate to the server. (documentation: maybe at
> http://hudson.openmicroscopy.org.uk/job/OMERO/javadoc/)
>
> Thanks for the help
> Nick
>
> _______________________________________________
> ome-devel mailing list
> ome-devel at lists.openmicroscopy.org.uk
> http://lists.openmicroscopy.org.uk/mailman/listinfo/ome-devel
>
>