On 04/08/2010 12:38 AM, Jonathan Robie wrote:
I've checked in very preliminary and incomplete documentation for the High Level API in qpid/doc/book/High-Level-API.xml. I have not yet added this to the main document.
Thanks for getting this started Jonathan! Some comments/opinions on whats there at present:
I'm not too keen on the whole introduction. I don't really like the term 'high level api'. I think the 'similarity' to JMS is overstated and I don't think we should be talking about AMQP 1.0 here (except at most as a minor footnote).
I think the introduction should briefly explain API support/options in all supported languages with links to further information where appropriate[1]. The rest of this chapter can then describe the Qpid specific API and its current support/implementation in python and c++, as well as a short section on how the addresses are used in JMS.
Listing the key classes/object on which the messaging API is based is good. I think the descriptions could do with some refinement though (this should be tied in to similar descriptions for those classes in the reference docs for each client). I also feel that listing address as one of those is not appropriate at this point (connection, session, sender, receiver and maybe message are all that is required).
Rather than have two separate programs to demonstrate a simple sender and a simple receiver I would have a single 'hello-world' example that combines the two into a single program.
I think this would reduce the noise without reducing the information conveyed and could conveniently postpone the need to get into detail on a couple of points until later on. The aim of the code is just to quickly show how the concepts are realised in the two different languages (we should also offer the same program in python as well as c++). On a more minor point we should use the simple 'unofficial' form of url (e.g. 127.0.0.1:5672) instead of the full blown scheme as defined by the spec (which is not supported in python).
First introducing simple addresses and then moving on to a more complete description of address string syntax, their mapping to 0-10 in detail and what can be achieved with extended features of that would I think make things feel more accessible. I think the hello world example would provide a nice segue into describing a simple address and demonstrating its use with spout and drain. After that, a fuller description of address strings, various options and demos of those options (or subject) would follow quite logically. ( like what you have here for the most part).
I'm prepared to provide a patch for all of this if you like, but I felt that it would be better to get some agreement on the right structure and approach first.
--Gordon. [1] e.g. "Qpid provides reliable, asynchronous messaging using AMQP in several different languages. The well-known JMS API is supported for java programs [[link to JMS in here]]. For .net programs there is a WCF binding provided [[link or ref to more detail here]]. For python and c++ programs however, Qpid defines a messaging API. The concepts of this API are similar in each language. Support for this API in ruby will be coming soon, for now ruby exposes different apis depending on the version of AMQP you use [[ref to section that provides some detail]]. The other APIs above are all independent of the specific protocol version in use." --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:[email protected]
