On Tue, Apr 13, 2010 at 12:02 PM, Gordon Sim <[email protected]> wrote: > 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?
I agree that the only thing that would be different is the address. While it is trivial to us, it's still an important distinction to the end users. However I agree with you that it's kind of useless to have two distinct complete examples for this, when the code is almost identical. I think the main issue here is that we think of examples as 1. Complete code that is runnable 2. As the basis for our tutorial. This has severely limited the examples and the tutorial as we have unsuccessfully tried to couple them both. While some examples can be used in the tutorial, we need to think of them independently as well. If am a new user, I will be looking for 3 things. 1. Examples for familiar concepts (ex pub/sub..store-&-forward) 2. Code snippets for important aspects like failover, flow control etc.. 3. Runnable examples. >> 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. Well if we do not try to couple the tutorial with examples, then we don't need to mess around with drain and spout. We can use drain and spout for what it's worth and try not to take code snippets from them. For that we can use simple code snippets. >> 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. If by reference docs you mean the API docs, then judging by the activity on user/dev lists it seems the end users are not being able to find them easily. I think atleast the core concepts should be in the tutorial. Otherwise what is the point of a tutorial ? >>> 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. My bad for not explaining properly. The list above is not necessarily complete pieces of code that are runnable. They are more like categories of examples (or perhaps entries in a TOC) that I would like to see in a tutorial. >> 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. Fair point I agree. >> >> 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. Having seen the examples I totally agree with you. I also thought the hello world examples provided a nice entry to the tutorial. >>> (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] > > -- Regards, Rajith Attapattu Red Hat http://rajith.2rlabs.com/ --------------------------------------------------------------------- Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:[email protected]
