[Dev] Re: Remote Browsing API in Chandler .1

[Andi Vajda]

 Hi Andy (cc: dev),

I've got remote item loading over SOAP and Jabber now. It's not checked in as
the tree is still frozen until 0.2, but here are the steps to load an item
remotely:

  - decide on a transport protocol, currently SOAP or Jabber

  - setup the server thread/process using the corresponding repository server
    implementation, by instantiating SOAPRepositoryServer or
    JabberRepositoryServer
  - start the server with the startup() method

from model.persistence.RepositoryServer import JabberRepositoryServer
from model.persistence.XMLRepository import XMLRepository

r = XMLRepository('data')
r.open(verbose=True)

server = JabberRepositoryServer(r, 'user at server/resource', password)
server.startup()

  - setup the client by instantiating a RemoteRepository using the server
    chosen transport

from model.persistence.RemoteRepository import RemoteRepository
from model.persistence.Transport import JabberTransport

r = RemoteRepository(JabberTransport('client at server/resource', password,
                                     'server at server/resource'))
r.open(verbose=True)

  - use the regular repository APIs, like find(), to fetch objects

That's it.

It seems that the APIs you're describing below are higher level and could take
advantage of the new APIs above. Also, the jabber transport uses the standard
jabber:iq:rpc namespace and I didn't have to do anything special on the jabber
message format side. Currently, the jabber transport I implemented is
synchronous (using IQ requests).

Andi..

On Wed, 13 Aug 2003, Andy Hertzfeld wrote:

> At the release meeting, I said I would document the API that Chandler
> .1 uses for sharing, so we can discuss it on Thursday and decide what
> we want to do for the .2 release.   The write-up follows below; I will
> also try to add it to the wiki later this evening.
>
> -- Andy
>
> Remote Browsing API in Chandler .1
>
>      Remote Browsing is accomplished in Chandler .1 by exchanging Python
> objects and meta-information using Jabber as a transport.  The Jabber
> subsystem accesses the objects through an API implemented by the
> ViewerParcel class.  There are 5 methods in the API, which should be
> overriden by a parcel viewer:
>
> GetAccessibleViews(who):
>     return a list of strings containing the relative urls of views that
> are accessible to the user who is represented by the Jabber ID passed
> in the 'who' parameter.   At this stage, parcels ignore the who
> parameter, and just return the views that are marked public.
>
> AddObjectsToView(url, objectList, lastFlag):
>     Add the Python objects in the objectList to the view referenced by
> the url.  AddObjectsToView may be called multiple times to fulfill a
> request; the lastFlag boolean is true if it's the final call of the
> request.  AddObjectsToView is usually called in response to a
> 'RequestRemoteObjects' call (see below)
>
> GetViewObjects(url, jabberID):
>      Returns a list of PythonObjects in the view referenced by the url
> that are accessible to the user represented by the jabberID.   These
> are the objects that will be transferred to be viewed remotely.
>
> HasPermission( jabberID, url):
>      returns true if the user represented by the jabberID has permission
> to access the view referenced by the url.  At this stage, the jabberID
> is ignored and we return true if the view is marked public.
>
> HandleErrorResponse(jabberID, url, errorMessage):
>      invoked instead of AddObjectsToView when an error occurs when
> requesting objects from the passed-in jabberID and url.  Typically, the
> viewer should display the error message in a dialog.
>
>      The Jabber subsystem is responsible for transferring the objects
> and meta-information by conveying them in jabber messages with special
> headers, indicating their nature.   Parcels can call the jabber
> subsystem by using the jabberClient object that is referenced from the
> app object.   An object transfer is initiated when a viewer calls
> RequestRemoteObjects instead of the local repository to get objects to
> display, which is passed a jabberID and a url referencing a remote
> view, as follows:
>
>                app.jabberClient.RequestRemoteObjects(remoteAddress, URL)
>
>      Additionally, a viewerParcel should call the jabber subsystem's
> PermissionsChanged(url) call when the permissions to any of its views
> change, so it can notify any remote clients that may be using it, as
> follows:
>
>               app.jabberClient.PermissionsChanged(URL)
>
>      The RequestRemoteObjects call initiates a sequence of instant
> messages to effect the object transfer.  The messages contain a special
> extension block to indicate that they are part of the object transfer
> protocol and not ordinary messages.  The following special messages are
> defined:
>
> chandler:request-objects
>         used to initiate an object transfer; the subject field contains
> the url of the view
>
> chandler:receive-objects
> chandler:receive-objects-done
>         used to receive objects as a result of a request; the subject
> field contains the url, and the message body contains a pickled Python
> objects that are based64 encoded to eliminate whitespace.  There may be
> multiple receive-object messages sent in response to a request; the
> last one will be marked with receive-objects-done instead of
> receive-objects
>
> chandler:receive-error
>         sent instead of receive-objects-done to indicate an error.  The
> subject field contains the url while the body contains the text of the
> error message
>
> chandler:request-views
>          request-views is used to request a list of urls of views that
> are accessible to the sender.
>
> chandler:response-views
>          response-views is sent to respond to a request-views message.
> The body of the message contains a list of urls of the views accessible
> to the requestor, delimited by newline characters.
>
>