Rupert, Thank you very much for providing your feedback, we really appreciate it. I have discussed/consulted extensively with Arnaud, Rafi and Jonathan before I made the following comments (inline marked with [RA]). I hope they will chip in if I have missed anything.
Regards, Rajith On 7/30/07, Rupert Smith <[EMAIL PROTECTED]> wrote: > >From: Rajith Attapattu <[EMAIL PROTECTED]> > >Date: 27-Jul-2007 17:31 > >Subject: Re: Java low level AMQP examples? > >To: [email protected] > > > >You can take a look at the shape of the API from here. > > https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpid/nclient/api/ > > > >Please provide feedback > > > >Regards, > > > >Rajith > > > Well, I am a little confused. I thought the idea was that the Qpid low level > client API was to 'closely follow the protocol'. Looking at this API I was > therefore expecting classes and methods something along the lines of: > > public interface Connection > { ... } > > public interface Session > { > open(...) > flow(...) > close(...) > ... > } > > public interface Queue > { > declare(...) > bind(...) > unbind(...) > purge(...) > ... > } > > public interface Exchange > { ... } > > public interface Message > { > transfer(...) > consume(...) > ... > } > > That is to say, something that exposes the clients outgoing method call view > onto the spec in a pretty much literal manner, perhaps moved around a little > to provide the creation of resources relative to their containing concept. > For example, [RA] Rupert this is the approach I took in the first pass. But I clearly labeled it as an AMQP low level API as it was literally a 1:1 map of the protocol methods. In the current implementation all these methods are packed into two classes called Invoker and Delegate. The advantage of Rafi's approach is that Invoker and Delegate are auto generated from the spec. These in turn use version agnostic Struct interfaces to handle multiple version support. The version agnostic abstract interfaces and version specific concrete Structs are also auto generated. So the low level Qpid API you are talking about is there in the current code. However it would be tedious to program at this level with out a good knowledge of the protocol. Hence we need a more developer friendly API that is at a slightly higher level. This is what we want to promote as an API, and it does contain most of the methods in the low level API. Let me illustrate some of the subtle difference using the following example. In the low level API if people want they can do connection.start connection.secure connection.tune connection.open In the Qpid API connection.open will encompass the all of the above methods. But most other methods will be exposed directly where it makes sense. The Qpid API is the Qpid projects abstraction of AMQP. Please note we haven't used the word "low level", bcos clearly the proposed API is not low level. [...] > Might we need to define interfaces, again mapping the protocol as 1:1 as > possible, for incoming methods? For example: > > public interface MessageClientChassis > { > ... transfer(...) > } > > MessageClientChassis myHandler = new MessageClientChassis() { ... > transfer(...) { // do something interesting } }; > session.message.consume(myHandler, myQueue, ...); > > Or how about TransferListener, or MessageTransferListener instead of > MessageClientChassis? > > So the low-level API, is there for those who want to hook into the incoming > AMQP method calls and deal with them directly (as the JMS client > implementation will want to). The proposed API looks like an AMQP flavoured > JMS to me, rather than 1:1 low-level AMQP. > > The Resource interface confuses me. Why should a resource associated with a > session have a particular, and just one, queue associated with it? The > MessageSender interface that extends it only allows sending to that one > particular queue. Even the JMS API, although allowing creation of senders > with a default destination, has send methods to send to alternatives. It > would seem to me that the nice thing about AMQP is that it seperates all the > component parts of its messaging abstraction out into seperate 'classes', > connection, session, exchange, queue, exchange, message, which can be > combined freely within the semantics of the protocol. So the creation of an > interface that artificially forces the end user into a restricted > combination detracts from it. Please ditch Resource, its not a usefull > concept. > [RA] Rupert the Message interfaces are being re-worked as we speak. The final outcome is very much like what you are expecting (will commit them shortly) The current interfaces were just skeleton interfaces that captured interim discussions. The idea is to provide a more AMQPish type of interface where you can send and receive small messages as well as streaming of large messages. Will ping you as soon as we commit them. > MessageListener and ExceptionListener are copies of the same interfaces in > JMS. Need we redefine them? I would have though a low-level API would deal > more directly in terms of AMQP error codes. I think it would be better to > use error codes than to throw exceptions, as error codes are not really > exceptions, they are an expected part of the protocol, rather than erronous > program states. I would expect exceptions to be there for situations like > the connection failing just after I call queue.declare and so on. > [RA] The concept of the MessageListener is not JMS specific, neither can they claim it. It is a generic concept for processing messages asynchronously. This was introduced for non JMS users to do async message processing. JMS will naturally build on top of it. This is clearly not an attempt to redefine JMS interfaces. We have the same thing for python now as well. The same goes for ExceptionListener. It is a generic way of handling errors asynchronously. As Arnaud points out it is used in quite a few places (java.beans, BDB are examples of API using ExceptionListener ). However we may drop the ExceptionListener as we are comming up with a different stratergy for error handling. But it is not dropped to make the Qpid API less JMS like. > I would expect a low-level API to mirror the protocol as closely as it > possibly can in the target language, use the same class/method namings as > the protocol does, and allow EVERY method in the protocol to be called > directly or received directly through some sort of listener interface, > otherwise it is too weak an abstraction to be called low-level. [RA] As I said before, we do have that currently in the form of Invoker and Delegate. But not everybody wants to program at that level. However I am sure that the final Qpid API will look very closely like the protocol with sensible abstractions like connection.open or message receive ..etc > > Also, how does this API fit in with the stub that Rafael is developing? For > example, the SessionDelegate looks like it might implement (or provide a > default implementation of) the incoming Session protocol calls. There was > something called AbstractInvoker in the first version of the stub that > seemed like a natural implementation point of the Session API, that is, its > the thing that client code calls to 'invoke' the protocol. > [RA] You got that right. I still haven't committed the code, but once the code is committed you will see thats what we have done. > Rupert >
