----- Original Message -----
> From: "Alan Conway" <acon...@redhat.com>
> To: proton@qpid.apache.org
> Cc: "Darryl L. Pierce" <dpie...@redhat.com>, "Gordon Sim" <g...@redhat.com>
> Sent: Monday, May 25, 2015 12:46:32 PM
> Subject: New language bindings - when are they ready? [was Re: Ruby Engine 
> APIs up for review]
> 
> On Thu, 2015-05-14 at 16:28 -0400, Darryl L. Pierce wrote:
> > I've pushed these APIs up for public review on their own branch [1] in
> > the Apache git repo. They're on a branch named ruby-engine-apis.
> > 
> > Please take a look, tinker and please provide feedback. :D
> > 
> > [1]
> > http://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=shortlog;h=refs/heads/ruby-engine-apis
> 
> We have a bunch of new bindings on branches (Go, Ruby, C++) When is a
> binding ready for trunk?
> 
> I would propose the following as a basic critiera:
> 
> - Complete and tested for basic use.
> - API documentation in language-normal form (godoc, rdoc, doxgygen)
> - Core set of examples.
> - Automated testing of all examples.
> - Getting started README that explains how to run the examples.
> 
> I would suggest the following core examples for all bindings:
> 
> - send: connect to endpoint, send N messages.
> - receive: connect to endpoint, receive N messages.
> - broker: accept connections, in-memory queues created on demand.
> - request_response: synchronous request-response client.
> - echo_server: accept connections, echo message to reply-to address on
> same connection.
> 
> This gives us a *small* set of examples that still has good coverage of
> key scenarios (brokered and client-server) and can be used *without* any
> external broker. This can be the common introduction to all our
> bindings.
> 
> The python binding has all these, with different names. Rationale for
> proposing the above names:
> 
> - The simplest send/receive examples should be called simply
> "send"/"receive". Python has "simple_send"/"simple_receive" which seems
> redundant.
> - "request_response" is more descriptive than
> "sync_client" ("sync_client" is a daft name, my bad)
> - "echo_server" describes what the server does, just "server" is to
> generic. The broker is also a server, and there may be other example
> servers.
> 
> I can live with the python names if there's a consensus for that but now
> might be a good time to rationalize. I do think the python examples
> should be re-organized to start with these core examples. Right now the
> python README requires you to start by installing an unspecified
> "intermediary" which is going to cause confusion and frustration.
> 
> The very first README for every binding should show how to run
> send/receive examples against the example broker, and request_response
> against the example server. AFTER we have demonstrated that proton is
> useful *on its own* we can and should provide further examples of using
> it with other brokers, tornado, ruby/go/whatever specific frameworks and
> what have you.
> 
> Some bindings (Go, possibly C++) provide additional API or toolkit to
> server multiple connections concurrently. They should also provide
> concurrent versions of the core examples. The go examples have send and
> receive take a list of addresses as arguments and send/receive on all
> addresses concurrently. I would suggest that as a model.
> 
> Interested in feedback! I'll be working on Go and C++ in coming weeks so
> I'd like to co-ordinate with ruby and python efforts so we can present
> something coherent to our users.
> 
> Cheers,
> Alan.
> 
> 

Working with a completely different code base the same set of questions came 
up. What makes a good example suite?
Today this kit has:
 * HelloWorld
 ** HelloWorld_simple
 ** HelloWorld_robust
 * Interop
 ** Interop.Client
 ** Interop.Server
 ** Interop.Drain
 ** Interop.Spout
 * AnonymousRelay
 ** AnonymousRelay
 * PeerToPeer
 ** PeerToPeer.Client
 ** PeerToPeer.Server
 * ReceiveSelector
 ** ReceiveSelector

1. The HelloWorld, Interop, AnonymousRelay, and ReceiveSelector examples 
require an external broker or a Dispatch router network

2. HelloWorld has a _simple and a _robust. Criticism of send_simple has basis 
as long as there's only one send example. If you throw in another example with 
exception checking, error recovery, configuration options, logging, proper 
resource closure, and so on with some/many of the things a real application 
will need eventually then 'send_simple' is a good way to describe the simple 
one. That's how the two HelloWorld variants came to be.

3. The Interop sets client/server and drain/spout faithfully reproduce the 
command line options of the Qpid Messaging examples. Getting these examples to 
work in the new client were helped a lot by having known-good Qpid code as the 
peer for the test.

Your list of requirements seems good and I like your suggested names. 
I'd add the requirement that new binding examples MUST interoperate with the 
existing examples and bindings.

-Chuck

Reply via email to