Just to add to the above,
I may be repeating certain things from my previous email, but I think
it's important context to understand this email on it's own.
Examples is an overloaded term.
I think we try to do **too many** things with our examples.
1. Use as an intro to the project and a quick getting started guide.
2. Use as a basis for demonstrating certain qpid concepts.
3. Use as a basis for the tutorial (that goes beyond a getting started guide)
4. Use as a basis for demonstrating interoperability
5. Use as a basis for interoperability testing.
While you can conceivably construct examples that may achieve all of
the above, I believe it's not the most optimal.
Infact it only serves to reduce the effectiveness of each goal as we
have to balance all aspects.
As mentioned many times before, I think we need different strategies
to address the specific needs of the above goals.
Getting Started and Tutorial
---------------------------------
- The getting started guide and tutorial could be combined to reduce the effort.
And the Hello World example is a really nice way to introduce the
project and then move to the rest of the topics in the tutorial.
- We need to use code snippets from outside of our examples. We can't
write examples that touch everything.
Demonstrating Concepts
------------------------------
- These are runnable pieces of code.
- These should be,
- nice little utilities like drain or spout
- something dirt simple like the Hello World example
- scripts that help run one of the above using authentication, ssl etc..
- If they are natural candidates for showing interoperability then so
be it. However interoperability should not be the primary goal.
Demonstrating Interoperability
-------------------------------------
- Perhaps the "reservation example" can be developed into a nice
little application that can demonstrate interoperability sufficiently.
- Demonstrating interoperability is not just a Hello World program or
sending a map full of primitives !
Interoperability testing.
----------------------------
- Using simple examples as a means of testing interoperability is
woefully inadequate.
(All though I agree something is better than nothing, we need to
move forward from this mind set)
- This should be a separate suite of tests to sufficiently tests a
wide range of aspects.
I think Rupert starting something along this lines, but not sure
what the current status of it.
Enough ranting I will get back to my work :)
Regards,
Rajith
On Mon, Apr 19, 2010 at 11:06 AM, Rajith Attapattu <[email protected]> wrote:
> 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/
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
