You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Jonathan Robie <jo...@redhat.com> on 2010/04/17 14:16:17 UTC
Messaging API Tutorial - early drafts in PDF and HTML
I created PDF and HTML for the current state of the Messaging API
Tutorial and placed them here:
http://people.apache.org/~jonathan/High-Level-API.pdf
http://people.apache.org/~jonathan/High-Level-API.html
In theory, this should tell people what they need to know to write
programs in C++, Python, or Java JMS.
Feedback would be great! If anyone hasn't picked up the new API or the
new address scheme, see if this tells you what you really need to know,
and let me know how to improve it.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Jonathan Robie <jo...@redhat.com>.
On 04/19/2010 05:12 AM, Ján Sáreník wrote:
> Hello Jonathan!
>
> On Sat, Apr 17, 2010 at 08:16:17AM -0400, Jonathan Robie wrote:
>
>> I created PDF and HTML for the current state of the Messaging API
>> Tutorial and placed them here:
>>
>> http://people.apache.org/~jonathan/High-Level-API.pdf
>> http://people.apache.org/~jonathan/High-Level-API.html
>>
> Wonderful comprehensive docs, good job!
>
> Comments:
>
> - In the beginning, when you list the most important classes of API,
> you use session with upper-case s in the last (receiver) part,
> but lower-case s in the part above (sender).
>
Nice catch. I'm also inconsistent with capitalization for the broker.
> - In Extended Address Options part there is an example with a queue
> named "xoxox" but in both command-lines it uses drain command,
> I guess it should be spout in the "Second Window".
>
Indeed. Nice catch!
> - In Table 1.2. Node Properties, please add upper-index A with
> an anchor to first occurance of "topic" as well (I mean when
> it is mentioned as a parameter for property "type").
>
OK.
>> In theory, this should tell people what they need to know to write
>> programs in C++, Python, or Java JMS.
>>
> It does so, indeed.
>
Thanks!
>> Feedback would be great! If anyone hasn't picked up the new API or
>> the new address scheme, see if this tells you what you really need
>> to know, and let me know how to improve it.
>>
> There are no "semantics" for some table fields, e.g. in Table 1.1.
> Otherwise very handy docs.
>
I'll work on adding them - thanks for the feedback!
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Ján Sáreník <js...@redhat.com>.
Hello Jonathan!
On Sat, Apr 17, 2010 at 08:16:17AM -0400, Jonathan Robie wrote:
> I created PDF and HTML for the current state of the Messaging API
> Tutorial and placed them here:
>
> http://people.apache.org/~jonathan/High-Level-API.pdf
> http://people.apache.org/~jonathan/High-Level-API.html
Wonderful comprehensive docs, good job!
Comments:
- In the beginning, when you list the most important classes of API,
you use session with upper-case s in the last (receiver) part,
but lower-case s in the part above (sender).
- In Extended Address Options part there is an example with a queue
named "xoxox" but in both command-lines it uses drain command,
I guess it should be spout in the "Second Window".
- In Table 1.2. Node Properties, please add upper-index A with
an anchor to first occurance of "topic" as well (I mean when
it is mentioned as a parameter for property "type").
> In theory, this should tell people what they need to know to write
> programs in C++, Python, or Java JMS.
It does so, indeed.
> Feedback would be great! If anyone hasn't picked up the new API or
> the new address scheme, see if this tells you what you really need
> to know, and let me know how to improve it.
There are no "semantics" for some table fields, e.g. in Table 1.1.
Otherwise very handy docs.
Thank you, best regards, Ján
--
Red Hat Czech, MRG Quality Engineering
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Jonathan Robie <jo...@redhat.com>.
On 04/19/2010 07:41 AM, Robbie Gemmell wrote:
> Looks good Jonathan,
>
> Only taken a cursory glance through so far, but noticed a couple of nits:
>
> The JMS example could use some formatting so it fits the PDF page width better.
>
Yeah, I agree.
> On page 5 of the PDF in Address Strings, it says "send messages using
> drain, and receive messages using spout." Other way round?
>
Yes - nice catch. I'll fix this.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Robbie Gemmell <ro...@gmail.com>.
Looks good Jonathan,
Only taken a cursory glance through so far, but noticed a couple of nits:
The JMS example could use some formatting so it fits the PDF page width better.
On page 5 of the PDF in Address Strings, it says "send messages using
drain, and receive messages using spout." Other way round?
Robbie.
On 17 April 2010 13:16, Jonathan Robie <jo...@redhat.com> wrote:
> I created PDF and HTML for the current state of the Messaging API Tutorial
> and placed them here:
>
> http://people.apache.org/~jonathan/High-Level-API.pdf
> http://people.apache.org/~jonathan/High-Level-API.html
>
> In theory, this should tell people what they need to know to write programs
> in C++, Python, or Java JMS.
>
> Feedback would be great! If anyone hasn't picked up the new API or the new
> address scheme, see if this tells you what you really need to know, and let
> me know how to improve it.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Jonathan Robie <jo...@redhat.com>.
On 04/20/2010 02:49 PM, Gordon Sim wrote:
> I feel that some restructuring is required. Some of the descriptions
> are not accurate or are a little misleading (or just not to my
> liking!). I started off listing each one but ended up creating a
> (rather large) patch. Applying this may be the simplest way to see
> what I think needs to change. This is by no means complete or fully
> polished either of course. I haven't even touched the JMS section
> (other than moving the two pieces together, though I think it could
> use a little work also.
I've merged your patch with some changes I had made myself based on
Rajith's feedback, and tried polishing it up some. This is still a
little rough, but I think we're getting there.
Newly build versions here:
http://people.apache.org/~jonathan/High-Level-API.pdf
http://people.apache.org/~jonathan/High-Level-API.html
Thanks for your help on this!
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Gordon Sim <gs...@redhat.com>.
On 04/17/2010 01:16 PM, Jonathan Robie wrote:
> I created PDF and HTML for the current state of the Messaging API
> Tutorial and placed them here:
>
> http://people.apache.org/~jonathan/High-Level-API.pdf
> http://people.apache.org/~jonathan/High-Level-API.html
>
> In theory, this should tell people what they need to know to write
> programs in C++, Python, or Java JMS.
>
> Feedback would be great! If anyone hasn't picked up the new API or the
> new address scheme, see if this tells you what you really need to know,
> and let me know how to improve it.
I feel that some restructuring is required. Some of the descriptions are
not accurate or are a little misleading (or just not to my liking!). I
started off listing each one but ended up creating a (rather large)
patch. Applying this may be the simplest way to see what I think needs
to change. This is by no means complete or fully polished either of
course. I haven't even touched the JMS section (other than moving the
two pieces together, though I think it could use a little work also.
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Jonathan Robie <jo...@redhat.com>.
On 04/19/2010 05:39 PM, Marnie McCormack wrote:
> Hi,
>
> Is there a schedule/proposed timeline for the next release ? Are you
> planning to wait until then to publish the docs ?
>
> Be good discuss roadmap plans, since the work outstanding on the Java Broker
> (management aside) to make 0-10 work is substantial and I think taking most
> of the effort for the next while.
>
We're planning to make the current state of the DocBook docs available
later this week alongside the existing Wiki, and start deleting
redundant Wiki content.
If the Java broker and C++ broker don't interop at the level described
in the tutorial, we'll need a separate tutorial for the Java broker, I
guess. I just think it would be a shame if it's still needed by the time
0.7 is released.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Marnie McCormack <ma...@googlemail.com>.
Hi,
Is there a schedule/proposed timeline for the next release ? Are you
planning to wait until then to publish the docs ?
Be good discuss roadmap plans, since the work outstanding on the Java Broker
(management aside) to make 0-10 work is substantial and I think taking most
of the effort for the next while.
Marnie
On Mon, Apr 19, 2010 at 3:29 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> On 04/17/2010 02:07 PM, Marnie McCormack wrote:
>
>> I had a read over the Java JMS section and think that it's useful and laid
>> out very nicely for the reader.
>>
>>
>
> Thanks!
>
>
> I think it possibly better labelled as 'for the C++ broker' since the bulk
>> of the setup details only apply to C++. I'd hope we'll get some time on
>> the
>> Java broker side to contribute to the docs/examples shortly so we can
>> flesh
>> out the same for the JB.
>>
>>
>
> By the time we release 0.7. I'd really like to see both brokers work the
> same way for the simple command-line utilities like qpid-config, for the
> Qpid Messaging API, and for Java JMS applications using JNDI and the new
> addressing scheme.
>
> I'd much prefer that to having two separate tutorials. I think anything
> that requires us to have two separate tutorials is probably an indication
> that we're not doing a good enough job of working together as one coherent
> project.
>
>
> The code example is good and simple, comments would be even better.
>>
>>
>
> Thanks - I'll add some to the Java JMS example, am I being overly
> optimistic in thinking that the C++ and Python examples can be understood
> relatively easily without comments?
>
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Rajith Attapattu <ra...@gmail.com>.
Jonathan,
Here is my 2 cents :)
Positives and minor points
---------------------------------
1. I think the intro and the use of the Hello World examples is really nice.
2. I like the way the addressing is described using drain and spout.
3. In "Address Strings" I think we should put the complete syntax,
including the BNF (as described in the python file) - or maybe the BNF
can be in the appendix?
4. How about we describe the general addressing options before talking
about 0-10 specific mappings?
Presumably the address was designed with 1.0 in mind, so if we
restructure the docs properly it will make things easy for us and the
end users when we eventually get to 1.0
Note ** However for the "Example 1.1. Simple Address Strings" it's
fine to have the queue and exchange example there.
5. Extended Address Options - I dislike this heading. I don't think
create, assert..etc are extended options.
As I mentioned above, I believe it's best we describe the general
options and then the 0-10 mapping.
6. Messaging Properties - lets include the JMS message props as well.
I will try to get them to you soon.
And then under separate heading we can show the 0-10 mapping for
the message props.
7. "Apache Qpid JNDI Properties for AMQP Messaging" should probably be
under JMS client as it's only relevant for that.
Also there are quite a bit of props now and let me get all that
info for you.
Perhaps this can be an appendix?
Really minor points, but annoying if not fixed
-----------------------------------------------------
1. The doc should have numbering
2. The overall structure doesn't seem well organized. (I will write
separate email on this when I have a chance to organize my thoughts).
Major points that I think is lacking
------------------------------------------
** This is not a criticism of the work you have done. I appreciate
the fact that for some of the points below you don't have the required
material yet.
But I like to see them eventually and I will contribute with what I know/can **
1. The tutorial doesn't really go beyond the basics (apart from addressing).
Is this the intention? I believe it shouldn't be.
2. Critical pieces that are missing
** Please note, you don't need complete runnable pieces of code to
illustrate the following. If we try to couple the tutorial to
examples, then we will end up limiting both**
Also some of the points below should be described in detail in a
user guide. But how to run them with an existing example is best
tackled via tutorial.
* How to do common messaging patterns (store-&-forward, pub/sub,
request/reply).
* How to do flow control
* Failover
* Transactions
* map messages (nested lists/maps - I don't think u need a
separate runnable example. This is pure code that and not really qpid
specific either)
* SSL (atleast point to something and maybe have a canned script
to run the hello world with one.)
* Authentication (describe the theory and then how the hello world
can be run with different auth mechs/options)
* ACL (I will do this for you - again not an example on it's own
nor a complete description.).
* Encryption.
* Transactions (not sure about this).
Sorry about the long list, neither do I claim this as an exhaustive list.
I am also very open to suggestions.
I think if we get this right, we can improve the end user experience
tremendously.
Regards,
Rajith
On Mon, Apr 19, 2010 at 10:29 AM, Jonathan Robie
<jo...@redhat.com> wrote:
> On 04/17/2010 02:07 PM, Marnie McCormack wrote:
>>
>> I had a read over the Java JMS section and think that it's useful and laid
>> out very nicely for the reader.
>>
>
> Thanks!
>
>> I think it possibly better labelled as 'for the C++ broker' since the bulk
>> of the setup details only apply to C++. I'd hope we'll get some time on
>> the
>> Java broker side to contribute to the docs/examples shortly so we can
>> flesh
>> out the same for the JB.
>>
>
> By the time we release 0.7. I'd really like to see both brokers work the
> same way for the simple command-line utilities like qpid-config, for the
> Qpid Messaging API, and for Java JMS applications using JNDI and the new
> addressing scheme.
>
> I'd much prefer that to having two separate tutorials. I think anything that
> requires us to have two separate tutorials is probably an indication that
> we're not doing a good enough job of working together as one coherent
> project.
>
>> The code example is good and simple, comments would be even better.
>>
>
> Thanks - I'll add some to the Java JMS example, am I being overly optimistic
> in thinking that the C++ and Python examples can be understood relatively
> easily without comments?
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Jonathan Robie <jo...@redhat.com>.
On 04/17/2010 02:07 PM, Marnie McCormack wrote:
> I had a read over the Java JMS section and think that it's useful and laid
> out very nicely for the reader.
>
Thanks!
> I think it possibly better labelled as 'for the C++ broker' since the bulk
> of the setup details only apply to C++. I'd hope we'll get some time on the
> Java broker side to contribute to the docs/examples shortly so we can flesh
> out the same for the JB.
>
By the time we release 0.7. I'd really like to see both brokers work the
same way for the simple command-line utilities like qpid-config, for the
Qpid Messaging API, and for Java JMS applications using JNDI and the new
addressing scheme.
I'd much prefer that to having two separate tutorials. I think anything
that requires us to have two separate tutorials is probably an
indication that we're not doing a good enough job of working together as
one coherent project.
> The code example is good and simple, comments would be even better.
>
Thanks - I'll add some to the Java JMS example, am I being overly
optimistic in thinking that the C++ and Python examples can be
understood relatively easily without comments?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Messaging API Tutorial - early drafts in PDF and HTML
Posted by Marnie McCormack <ma...@googlemail.com>.
Hi Jonathan,
I had a read over the Java JMS section and think that it's useful and laid
out very nicely for the reader.
I think it possibly better labelled as 'for the C++ broker' since the bulk
of the setup details only apply to C++. I'd hope we'll get some time on the
Java broker side to contribute to the docs/examples shortly so we can flesh
out the same for the JB.
The code example is good and simple, comments would be even better.
Regards,
Marnie
On Sat, Apr 17, 2010 at 1:16 PM, Jonathan Robie
<jo...@redhat.com>wrote:
> I created PDF and HTML for the current state of the Messaging API Tutorial
> and placed them here:
>
> http://people.apache.org/~jonathan/High-Level-API.pdf
> http://people.apache.org/~jonathan/High-Level-API.html
>
> In theory, this should tell people what they need to know to write programs
> in C++, Python, or Java JMS.
>
> Feedback would be great! If anyone hasn't picked up the new API or the new
> address scheme, see if this tells you what you really need to know, and let
> me know how to improve it.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>