On Thu, Feb 10, 2011 at 8:41 AM, Gordon Sim <[email protected]> wrote: > On 02/10/2011 12:56 PM, Rajith Attapattu wrote: > >> What I was specifically looking for is what exactly do we advertise as the >> "Common API" - what exactly does it look like ? >> > > http://qpid.apache.org/books/0.8/Programming-In-Apache-Qpid/html/ch02.htmlgives > an overview. There is more detail in following sections and in the > respective language references. >
Sir, that is a user guide that does a reasonably good job at explaining how to use the API. At the beginning of chapter 2 it does provide a high level view of what the API is. I also agree that there is useful information in the sections that follow. However IMO that document has a different purpose than what I am referring to. The above is not a formal authoritative document that describes what our Common API is. The one I am looking for should describe, - The interfaces and their respective methods. - The intended behaviour of these methods. - The common message formats we support and how they behave. If we have such a document, then that serves as a, 1. A language independent reference for our users and guarantee about stability. 2. A Reference guide for prospective client developers. 2. A guideline for QA folks to figure out what to test and what to expect in terms of behaviour. 3. A basis for interoperability testing between clients. 4. A basis to figure out and document the extras and workarounds added for each language client. > I don't doubt for a minute that we can improve that documentation There are > certainly also some unintentional inconsistencies between languages. I think the inconsistencies are a result of not having a formal authoritative document. As our client portfolio grows so will these inconsistencies bcos we don't have a proper reference guide. And people tend to interpret certain areas differently which results in these subtle differences. > However I don't think it is accurate or helpful to start by stating that > the information is not there at all. > I just simply stated that I am looking for a document that describes our Common API in a single document and it is not there. I didn't criticize any person or any document we already have for not having enough information. I certainly didn't imply that the user guide does not have any information nor do I believe the user guide is the right place for adding the document I described above either. The user guide could definitely have a reference to it. But IMO we certainly don't have the document I described above, and I don't think it's inaccurate or unhelpful to state such a thing. > > --------------------------------------------------------------------- > Apache Qpid - AMQP Messaging Implementation > Project: http://qpid.apache.org > Use/Interact: mailto:[email protected] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/
