Discuss/document new omero.cmd API

[jamoore]

As a part of #3845, the asynchronous API developed for delete (#2615) was expanded and renamed to "omero.cmd" in order to handle other background activities, most importantly for 4.3.2 chgrp modifications which will also take some time. Before committing to the API, there will need to be some design minigroup meetings to make sure that our requirements are met, and that this is something we can support for the immediate future.

Highlights

• A superclass omero.cmd.Session should be added between Glacier2.Session and omero.api.ServiceFactory
• Session should provide a simple, extensible API for which we can provide backwards-compatibility moving forward *omero.cmd.Session only passes primitives, and Request/Response? objects, (and eventually rtypes)
• The intent is that non-logged in users ('guests') should be able to get hold of a Session, even if they shouldn't necessarily have a ServiceFactory (#6316)
• omero.cmd.Request subclasses should be created for each type of action.
• Where the basic omero.cmd.OK and omero.cmd.ERR Response subtypes do not suffice, they should also be subclassed.
• A omero.cmd.HandlePrx should be returned from Session.submit(Request).
• For batching together Requests, a omero.cmd.DoAll([...]) Request subclass should be provided.
• The server should provide queries over all current handles ("ACTIVE", "FINISHED", "ERRORS", ...)
• The server should also provide a list of info/error messages for the running handles.

Example

    def testCommands(self):
        sess = getSession()

        handle1 = sess.submit(omero.cmd.Chgrp("/Image", 1, None))
        handle2 = sess.submit(omero.cmd.Delete("/Image", 1, None))

        #
        # Other possibile extensions
        #
        ExampleCmdCallback([handle1, handle2]).waitOnAll()

        client = SyncClient(session) # Does not yet exist

        link = Link(parent="Project:1", child=response.list[0])
        handle = sess.submit(link)

        pop = PopStatus(10, include=[FAILURE])
        response = client.call(pop) # Removes from queue

        findHandles = FindHandles(include=[DONE], exclude=[SUCCESS])
        response = client.call(findHandles)

        response = sess.call(ListCommands())

        # Multi-call
        requests = DoAll(list=[ListCommands(), ListCommands(),ListCommands()])
        responses = sess.call(req_list).list

[jburel]

Referencing ticket #3532 has changed sprint.

[jmoore]

Initial discussion on how to move from v1 to v2 done today (Feb. 22) after both Will and Jean-Marie had reviewed the methods in OmeroPy and OmeroJava respectively. There is some concern about the multitude of ways to delete now (to-be-deprecated).