2011.02.15-API Notes

File contents

API unification meeting: Will, Chris, Ola, Jean-Marie, Josh (9:30 UK)

* Initial
    * Will: Still have cleaning up to do
    * Jean-Marie: Need to prevent explosion of gateway methods
        * Start with mgmt methods
        * ...
* Primary question: Do we keep the two synchronized?
    * createGateway
        * Adam used it
        * Will used it in his scripts & examples
    * Chris: have 3 gateways in Python
        * script_utils, GatewayPrx, omero.gateway.BlitzGateway
    * Overview (Will):
        * Certain number of methods in gateway module ("ton of wrappers")
            * Caching (Python-y stuff)
            * Extension point (historical, for Carlos & Ola to work together)
            * Some methods (getComments...) shouldn't necessarily be there
        * Jean-Marie: doesn't scale
        * Will: trying to make it more generic
            * Trying to get rid of "getDataset" etc.
            * getX(id)
            * listY() - convention
            * In Python, you only retrieve the root of the graph
            * Jean-Marie: load methods get whole graph.
        * Chris: @Wrapper around IQuery to prevent pain
            * Good number of the methods are single object retrievals
            * IQuery methods to mirror getObjects identically
            * Will: Wraps with appropriate wrappers.
            * Jean-Marie: purpose is to not have to know which service you are using
            * Jerome etc. want something simplified
            * Josh: are we trying to get away from services?
                * If so, then I'm for a unified API (Java & Python)
            * Chris: endemic of large number of services
                * Band-aiding core issue: to do work need 1/2 objects
                * Purpose would be to get common gateway in place.
        * Will: some of condensed methods have in lower-level service?
            * Jean-Marie: would rather do that.
        * Chris: currently methods expose that findAllByQuery is needed
            * Easy to push down
            * Jean-Marie: have to push them down
        * Will
            * Python would wrap
* Various
    * Chris: pojos hide lack of utility in services
    * Josh/Jean-Marie: could also use this as a method to get rid of pojos (i.e. message passing)
    * Will: can we tell people to start using it
        * Chris: Get rid of script_utils (4.3) in favor of blitz gateway
        * Remove server side gateway for 4.3
        * In the mean time, start moving logic to session or IQuery
        * For 4.3, no large changes to blitz gateway
        * Names are the same as in the model
        * Unifying some of blitz gateway methods
            * Chris: look at all retrieval methods and all getX
            * Figure out what lowest common denominator (e.g. "findExperimenterByName")
            * Need something like findByAttribute
    * Mark a good number as deprecated
        * Start marking methods & services deprecated (gateway, deleted, ...)
        * getObjects and some other are not yet released so can be removed

* Summary:
    * Need to unify these things and clean up our mess
    * Need to do our damndest that this does not continue
        * Everyone CANNOT create methods where they want
        * Is it documentation? Or is it not asking?

* TODOs
    * Wiki page for new remote API: *.slice file (Ice-compatbile objects)
    * Native binding page: omero.client, BlitzGateway/OMEROGateway.java (non-Ice tools)
        * Language- or Framework-specific