On 04/13/2010 04:36 PM, Rajith Attapattu wrote:
On Tue, Apr 13, 2010 at 8:19 AM, Gordon Sim<[email protected]> wrote:
On 04/12/2010 10:30 PM, Rajith Attapattu wrote:
Hi All,
Judging by some of the questions on the user list, I feel we could do
a much better with our examples.
(Also our examples should be more visible in the source tree and
easily accessible from our release artefacts.
However I believe that is a different discussion for another day.)
I am envisioning the following structure for the examples, and most of
the old examples can be easily adapted to the new format.
1. store-and-forward.
2. pub/sub with topics
3. request-reply
4. map messages
5. using flow control
6. * using addressing options (multiple examples showing binding to
multiple exchanges, create/delete/assert options ..etc)
7. using SSL/Kerb encryption
8. Authentication (ex. Kerberos, external)
9. using failover
10. transactions
* Maybe drain and spout could be used for this (as is or with some
modifications) ?
I think drain and spout should be used for 1. and 2. as well, also for 9.
and even to a lesser extent for 4.
I strongly disagree here.
So in your view what would the examples for 1. and 2. look like for the
new api?
As far as I can see the only thing that will change between them is the
address used (have a look for example at queue_sender/queue_receiver v.
topic_sender/topic_receiver in c++).
And for 9. again there is little that changes in the code, so what would
the example code for that look like in your view?
While drain and spout are excellent for demonstrating these aspects
they are not necessarily good code examples.
While the python is nice and compact the c++ and and the JMS based
versions are not !
I would argue that the issue to be dealt with there is some
restructuring of the example code (e.g. moving the options handling
code) to make it more readable.
Even in the python version 90% of the code is for handling opt parsing.
So IMO they are not good code examples, but excellent tools for
demoing concepts.
Hence I think they are excellent at showing different addressing examples.
Other than different addresses how do 1. and 2. differ in your view?
We really need to make a distinction btw code examples and tools/demos.
I think the end users are looking for both.
That is why I think a dedicated map message example that does nested
lists/maps is very very important !
>
How many times have seen people asking about how to do flow control
and acking etc.. ?
People are looking for specific code segments that are easily
identified in the example.
I think better reference documents are the real solution here.
I don't think 7. and 8. require a separate example. It is just a
configuration issue. Ideally all the examples should work using different
authentication configuration and we need some clear and accessible
documentation on how to do that rather than new examples. The same is
probably true for SSL.
Well examples are not just code only.
There were many users who asked on the list/offline about a working
SSL or Kerberos example.
Right, and having documentation that shows how to get an example working
with those features is needed. I'm saying it doesn't require a distinct
example program though, which is what I assumed your list above was
implying.
While the latter is difficult, at least the SSL one could be easily done.
The configuration matters and can be easily shown in the shell script etc..
The script can use code from another example.
If - in addition to clear documentation on the approach - you provide a
script for creating test certs and setting up env vars accordingly, fair
enough. I don't see any need to tie that to a specific example though.
I agree with you that we need good supplementary documentation.
The examples should be simple.
I think one of the problems is that all the examples are very simple. Having
simple examples is certainly important. However to my mind some of the
questions raised might be better answered by a slightly more involved
example, e.g. the reservations example in python.
My suggestion is:
(a) we get rid of the old amqp 0-10 specific examples
+1
(b) we have a simple helloworld example in each language
I am not sure what is really achieved here. Perhaps I misunderstood the intent?
It shows how to use the api to send and receive a message in a single
simple piece of code. This conveys the key objects (connection, session,
sender, receiver and message) that make up the api, and shows the basic
usage pattern.
I see this as a merging of a simple sender and a simple receiver program
into a single program that sends itself a message. I don't think any
information is lost, and the resulting example is smaller and easier to
take in through a single glance.
(c) we have spout and drain to show different messaging patterns
See my comments above.
(d) we have a client-server example (to show use of reply-to and creation or
temp reply queues)
+1
(e) maybe have a dedicated map message example (not totally sure this is
needed)
IMO this is needed.
(f) we start trying to build out the reservations example as a more complete
program
I could definitely see the value of such an example.
(g) we describe how to run at least spout and drain using authentication,
SSL etc
See my comment about.
In summary I don't think a one size fits all example is going to be
useful at all.
While a generic example can be used as much as we can, specific
targeted examples are needed as well.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
