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.
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?
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]
