XML-RPC interface (was: Will GnuCash ever work for me?)

[Linas Vepstas]

On Tue, Sep 25, 2001 at 01:18:44AM -0700, Jeb Bateman was heard to remark:
> On Mon, Sep 24, 2001 at 07:56:03PM -0500, Linas Vepstas wrote:
> > I'm curious to hear what Jeb means by 'arbitrary front-ends', as it
> > must certainly differ from the vision I had of gnucash as a kind of
> > 'applet' that can be embedded onto web pages.
> 
> Having a CGI interface does give you the ability to run GnuCash from a
> web page, (which is great); but having an XML-RPC interface also gives
> you that, plus a lot more capability because any program written in
> any language with an XML-RPC client library can then drive GnuCash.

The traditional gnucash 'theory' is that the 'correct' programming
interface/API is the 'engine' programming interface.  Part of this
theory is that there are supposed to be 'engine backends' that know how
to communicate with persistent-storage backends.

There are currently four backends:
-- the file format backend, can save/restore from file.  This is a 
   single-user, local-storage backend.
-- the sql backend, can connect to local or remote database, supports
   multiple simultaneous users.  Beta.  Works for me; might have
   scalability or performance problems.
-- the 'rpc' backend.  Uses rpc to talk to remote gnucash server.
   Code exists, but its broken, not currently operational.
-- the 'http' backend.  Uses http to manage connections.  Uses a
   an enhanced version of the XML file format as the actual data
   protocol.  Currently broken by recent file format changes, but it
   used to kinda-work.  (The idea was that http would provide SSL,
   authentication, socket management, state management, permissions,
   etc ... all that communnications-level stuff that apache provides).

> So, for example, I might want to enter some transactions from emacs.
> I think there is some XML-RPC client elisp code around, but if not I
> could probably write it...  Using that, I'd write an elisp function
> called gnucash-add-transaction (or something) which would prompt me

I don't know how similar elisp is to scheme, but ... we already have 
something like this with the scheme wrappers for the engine.  Pick the
right backend, and prgorgram to the scheme interface, and things will
'just work'.

> Or maybe I want to enter transactions from my WAP enabled cell phone.
> I write a little CGI script in Python, which presents a simple web
> form to enter the Date, Description, Account, and Amount.  Submit, and
> it hands the input data off to its XML-RPC client library for
> processing.  (Same thing for a regular web page, except it could
> probably have a have a more verbose layout than the WAP version.)

Right.  You could put an XML-RPC interface in front of the engine.
But I think it would suffer serious performance problems.  It would be 
nasty to make an rpc call to set the payee, a second one to set the
date, a third one to set the amount... etc. 

In designing the backend, the goal was to put the communications there
(such as XML-RPC), so that we ship only entire transactions (or even
entire lists of them) to the server.  One RPC call per block of 
data.  Much more efficient.

Note also that one of the things that the 'engine' provides
is a 'local cache' of the account data.  That means that it will 
get very good response times, because it doesn't contact the remote
server if it doesn't need to.  It also allows (in theory) disconnected
operation: if the server is down, you can still do some limited things
with your local data.  You could, for example, continue to add new
transactions; then, when the server/net-connection comes back up, then
it automatically 'syncs' with the remote server.

Note that the 'cache' is not a theory: it actually works with the sql
backend. As far as I know, there are are no bugs or problems with 
the cache getting out of sync.

The 'offline operation' is a theory.  In pricinciple, 'it should just
work', but in practice, if the sql client can't reach the server,
it just terminates in an ungraceful fashion.  There's some code to make
it work more elegantly, but its all messsed up at the moment.  It
shouldn't be hard, a week or two of work, but no one cares at the moment
...

Since we already have an RPC backend, I presume that converting it to
XML-RPC shouldn't be hard.   However, as I said, its currently broken
and functionally incomplete ...

> As Bill mentioned, a Java client can be written too, (which probably

Right. MoneyDance got its start as a gnucash Java client, before the
author made it proprietary.  Grep the gnucash mailing list archives ..
its all there ... incl sample java code ...:-)

I'm totally confused about what Bill actually did.  I read the note
several times, but couldn't make out where he put the interface, or 
what got connected to what.  Bill is smart, but prefers to reinvent
things on his own, rather than learn from the mistakes and experiences
of others ... 

> gives you a native looking GUI interface on multiple platforms ;-)

:-(  One problem with Java is that its just plain ugly.  You can make gtk
look soo much nicer ... 

> Anyway, I haven't actually done any XML-RPC hacking myself, but I was
> involved in the community where it was developed, (before giving up on

Well, Those arguments were correct.  What I find curious was that those
arguments were similar to the ones that resulted in CORBA being
created in 1990/1991.  corba was supposed to fix the shortcomings of
RPC. Unfortunately, corba was/is hard to use.   In some sense,
the microsoft .net strategy smells like 'corba done the way it was meant
to be'.  But, whatever. sidetrack.

> fragile CGI script, which returns output in a fragile HTML layout.

Right. But what made it fragile was 'bad programming technique':  
programmers mixed html layout with core logic, and that is what's bad.  
Old-time GUI programmers knew not to do this, but the web was filled
with new-comers who hadn't yet lived through that disease. 

What the world needed (and still needs?) is a version of glade for html
forms.   A web page designer that could give you the hooks to the gui 
elements that you could hook up to your app. That took care of the
'url-encoding' (which was like marshalling and unmarshalling) and the 
'cookies' (the session objects) under the covers, automatically.   
To the best of my knowledge, no one has ever built one of these,  
even though 'glade' and other GUI designers and RAD tools are common 
for non-web GUI interfaces. 

I think that one of the things the gnue.org guys understand, and that the 
treshna Bond guys understand is that you need to decouple the GUI from 
the app logic.  

--linas

> Hope that helps,

I was hopping that you were going to tell me that you had some explicit
plans ....



-- 
pub  1024D/01045933 2001-02-01 Linas Vepstas (Labas!) <linas@linas.org>
     Key fingerprint = 8305 2521 6000 0B5E 8984  3F54 64A9 9A82 0104 5933