On Thu, Feb 10, 2011 at 7:16 PM, Andrew Kennedy < [email protected]> wrote:
> On 10 February 2011 14:54, Rajith Attapattu <[email protected]> wrote: > >> 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.html >>> gives an overview. There is more detail in following sections and in the >>> respective language references. >>> >> > 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. >> > > > There is not always a correlation between the formality of a specification > and its usefulness, particularly when trying to be language agnostic ;) > > Perhaps we could try creating a UML mapping of the AMQP specification, and > describing that? There are other formal specification languages, but UML is > well known and understood, and AMQP is fairly simple to describe with no > unusual abstractions. Also, many modelling tools allow generation of > interfaces for different languages and documentation direct from a UML > document, which may be useful. I don't have a lot of experience here though, > so any other suggestions would be good? > > Standardised representations of APIs created by, e.g. perl or Java are more > relevant for general use, c.f. the existing user documents. Simply having > these native APIs available *and* annotated with references to the AMQP > specification (which specification/version?) would be a good first step, as > that can easily illustrate commonalities and inconsistencies. These would be > where, say, functional languages would start to have very different patterns > from OOP style languages, and things like the platform threading and > concurrency model would become significant. > > > 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. >> > > > Good things to have, obviously. > > But I would think this is also a matter for, e.g. the AMQP-WG or > AMQP-API-SIG (does such a thing exist?) or similar organisation, and would > be, probably, an incredibly formal specification document that will not be > of a great amount of use to developers who just want a client API definition > for $FAVOURITE_LANGUAGE. What developers actually need is references written > in the idiom of the language or platform they are developing for, and > although those exist for C++ and Python, as you say, we need to make an > effort to show how they are related, similarly with the JMS API, although in > that case we defer to the J2EE javadoc, and I'm not sure it wouldn't end up > being confusing if we were to deviate from this. I think Java is the problem > (at leat, odd-one-out) here, as all the swig generated APIs will, of > necessity, show large similarities. There is of course, the question of AMQP > 1.0 support, too. > > > I don't doubt for a minute that we can improve that documentation There >>> are certainly also some unintentional inconsistencies between languages. >>> >> > > And, indeed, *intentional* inconsistencies, due to varying client models, > such as JMS, WCF et al. > > The differences I am alluding to are between the Python, C++ and soon to be Perl and PHP clients. They all have a high level API (protocol agnostic) which looks very similar, which IMO is huge win. However there exists some very minor inconsistencies. I was hoping a more formal document that describes this high level API will contribute a lot towards improving on those inconsistencies. The JMS and WCF will be different and is expected. > > 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. >> > > > As long as we are positioning the C++ and Java brokers as parts of the same > product, there needs to be an explanation of the JMS-AMQP mapping, and I > suppose that also means there should be a Java version of a direct AMQP API > exposed publicly. > > In summary, we need the following items, with 1. being possibly the > responsibility of the AMQP working group: > > 1. Language agnostic description (using UML or some other formal modelling > language) of a common API based on some AMQP official specification. > 2. For each client language or platform using AMQP directly, an API > document in its native, idiomatic form, with annotations referencing the > official AMQP specification(s). > 3. For other clients, such as JMS and WCF, a similar API document, with > annotations linking concepts to their semantic equivalent in the common AMQP > API as well as referencing the AMQP specification. > 4. An informal document describing the common API with links to language or > platform specific idiosyncrasies. > 5. An informal programming guide for each type of client, describing > language/platform specific idiom and idiosyncrasies, with code samples. > There may be multiple guides for some platforms. > > We kind of have 4. and 5. already, and (rudimentary) versions of 2. for > some clients, as Gordon pointed out. Each of these will probably need to be > produced separately for each supported AMQP version, with at least 0-9-1, > 0-10 and 1-0. > > As for the rest, I think vmware/rabbitmq do this very nicely, and are > probably worth emulating. See these pages: > > * http://www.rabbitmq.com/specification.html > * http://www.rabbitmq.com/api-guide.html > * http://www.rabbitmq.com/amqp-0-9-1-quickref.html > * http://www.rabbitmq.com/amqp-0-9-1-reference.html > > I particularly like their quick reference document. Look at "channel close" > - it has the method signature, with each parameter linked to the relevant > part of the AMQP specification, an indication of the support level in their > client, the method description and documentation, and then links to the > actual native Java and .NET documentation, and the AMQP specification for > the command itself: > >> channel.close(reply-code reply-code, reply-text reply-text, class-id >> class-id, method-id method-id) ➔ close-ok >> >> Support: full >> Request a channel close. >> >> This method indicates that the sender wants to close the channel. This may >> be due to internal conditions (e.g. a forced shut-down) or due to an error >> handling a specific method, i.e. an exception. When a close is due to an >> exception, the sender provides the class and method id of the method which >> caused the exception. >> >> [javadoc] [dotnetdoc] [amqpdoc] >> >> > Is this what you were thinking of, Rajith? > > Andrew the API I am referring to here is the new Qpid initiative to define a high level protocol agnostic API. This API is a generic "messaging" API that can abstract not only multiple versions of the AMQP protocol, but even a different protocol like Stomp. This API will provide the same benefits of the JMS API in terms of stability and not having to worry about the underlying protocol semantics and behaviour. The API that is in place for C++ and Python will provide seamless migration to AMQP 1.0 if and when Qpid implements that. That to me is a huge win and Kudos to Rafi and Gordon for pioneering this. Anyways sorry for leading everybody down a rat hole here. Perhaps we should start a new thread on this and focus on the JMS issue here :) Rajith > Cheers, > Andrew. > -- > -- andrew d kennedy ? apache qpid project : http://qpid.apache.org/ ; > > --------------------------------------------------------------------- > Apache Qpid - AMQP Messaging Implementation > Project: http://qpid.apache.org > Use/Interact: mailto:[email protected] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/
