Re: Intro to proton

[Ted Ross]

Hi Jake,

You are trying to run Proton (AMQP 1.0) against a broker that only talks
AMQP 0-10.  You need to make sure that the broker is loading the
"amqp.so" module so it can support the 1.0 protocol.

qpidd --load-module amqp.so

If you are building the broker from source, you need to make sure
Proton-c is installed or the build won't produce an amqp.so.

If you need further clarification, please ask.

-Ted

On 09/23/2014 01:26 PM, O'Hara, Jake wrote:
> Hello,
> 
> Our company is currently evaluating some AMQP technologies and one of the 
> ones we are interested in is proton.  We are currently having some trouble 
> getting a connection from the proton client to an Apache Qpid instance.  The 
> Qpid client connects with no problems, but when we use proton we get the 
> following error:
> 
> Calling pn_messenger_send()
> [003224B0]:ERROR[-2] SASL header mismatch: 'AMQP\x01\x01\x00\x0a'
> 
> [003224B0]:ERROR[-2] SASL header mismatch: ''
> CONNECTION ERROR connection aborted (remote)
> 
> Any help/guidance you can provide to get us past this would be greatly 
> appreciated.
> 
> Thanks,
> 
> Jake O'Hara | Software Architect | Design & Development
> Aristocrat Technologies, Inc.
> tel 702 270 1217 | fax 702 270 1136
> email jake.oh...@aristocrat-inc.com | 
> web www.aristocratgaming.com
> P Please consider the environment before printing this e-mail
> 
> 
> 
> IMPORTANT CONFIDENTIALITY NOTICE:
> 
> This E-mail (including any documents referred to in, or attached, to this 
> E-mail) may contain information that is personal, confidential or the subject 
> of copyright or other proprietary rights in favor of Aristocrat, its 
> affiliates or third parties. This E-mail is intended only for the named 
> addressee. Any privacy, confidence, copyright or other proprietary rights in 
> favor of Aristocrat, its affiliates or third parties, is not lost because 
> this E-mail was sent to you by mistake.
> 
> If you received this E-mail by mistake you should: (i) not copy, disclose, 
> distribute or otherwise use it, or its contents, without the consent of 
> Aristocrat or the owner of the relevant rights; (ii) let us know of the 
> mistake by reply E-mail or by telephone (US 1-877-274-9661, or  AU +61 2 9013 
> 6000); and (iii) delete it from your system and destroy all copies.
> 
> Any personal information contained in this E-mail must be handled in 
> accordance with applicable privacy laws.
> 
> Electronic and internet communications can be interfered with or affected by 
> viruses and other defects. As a result, such communications may not be 
> successfully received or, if received, may cause interference with the 
> integrity of receiving, processing or related systems (including hardware, 
> software and data or information on, or using, that hardware or software). 
> Aristocrat gives no assurances in relation to these matters.
> 
> If you have any doubts about the veracity or integrity of any electronic 
> communication we appear to have sent you, please call (US 1-877-274-9661, or  
> AU +61 2 9013 6000) for clarification.
> 

Intro to proton

[O'Hara, Jake]

Hello,

Our company is currently evaluating some AMQP technologies and one of the ones 
we are interested in is proton.  We are currently having some trouble getting a 
connection from the proton client to an Apache Qpid instance.  The Qpid client 
connects with no problems, but when we use proton we get the following error:

Calling pn_messenger_send()
[003224B0]:ERROR[-2] SASL header mismatch: 'AMQP\x01\x01\x00\x0a'

[003224B0]:ERROR[-2] SASL header mismatch: ''
CONNECTION ERROR connection aborted (remote)

Any help/guidance you can provide to get us past this would be greatly 
appreciated.

Thanks,

Jake O'Hara | Software Architect | Design & Development
Aristocrat Technologies, Inc.
tel 702 270 1217 | fax 702 270 1136
email jake.oh...@aristocrat-inc.com | web 
www.aristocratgaming.com
P Please consider the environment before printing this e-mail



IMPORTANT CONFIDENTIALITY NOTICE:

This E-mail (including any documents referred to in, or attached, to this 
E-mail) may contain information that is personal, confidential or the subject 
of copyright or other proprietary rights in favor of Aristocrat, its affiliates 
or third parties. This E-mail is intended only for the named addressee. Any 
privacy, confidence, copyright or other proprietary rights in favor of 
Aristocrat, its affiliates or third parties, is not lost because this E-mail 
was sent to you by mistake.

If you received this E-mail by mistake you should: (i) not copy, disclose, 
distribute or otherwise use it, or its contents, without the consent of 
Aristocrat or the owner of the relevant rights; (ii) let us know of the mistake 
by reply E-mail or by telephone (US 1-877-274-9661, or  AU +61 2 9013 6000); 
and (iii) delete it from your system and destroy all copies.

Any personal information contained in this E-mail must be handled in accordance 
with applicable privacy laws.

Electronic and internet communications can be interfered with or affected by 
viruses and other defects. As a result, such communications may not be 
successfully received or, if received, may cause interference with the 
integrity of receiving, processing or related systems (including hardware, 
software and data or information on, or using, that hardware or software). 
Aristocrat gives no assurances in relation to these matters.

If you have any doubts about the veracity or integrity of any electronic 
communication we appear to have sent you, please call (US 1-877-274-9661, or  
AU +61 2 9013 6000) for clarification.

Re: [documentation] -- Intro to Proton

[Rajith Attapattu]

Phil,

I think it's worth experimenting with an approach that has a low
barrier-to-entry.
Markdown seems very very appealing. Anytime you can get away with
plain text, it's great.

And as Alan mentioned, the source doc itself can be a finished product.
So my +1 for trying this.

Regards,

Rajith

On Mon, Feb 25, 2013 at 8:56 PM, Phil Harvey  wrote:
> I do agree with you that having documentation committed alongside code is
> the right approach.
>
> I propose that we write this documentation in Markdown syntax. That gives
> us (or our users) the option of easily generating HTML whilst keeping the
> barrier to entry low for authors.
>
> I recognise that Markdown lacks the semantic richness of Docbook (used for
> the Qpid Broker), but I believe that's ok in this case since our
> documentation should be quite short (or we're doing something wrong).
>
> Phil
> On Feb 25, 2013 7:07 PM, "Rajith Attapattu"  wrote:
>
>> I'm strong believer in maintaining our docs in the source tree, as it
>> makes it easy to release docs along side the code.
>> Also it helps keep the docs current.
>> The wiki based documentation in the past had many issues, the chief
>> complaint being stale most of the time.
>>
>> We could look at doing something similar to the qpid docs, or we could
>> also use this opportunity to experiment with a different approach/tool
>> set.
>>
>> Rajith
>>
>> On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish 
>> wrote:
>> >
>> > I think I will be landing it in the code tree first, and
>> > from there, I don't know.   Any suggestions?
>> >
>> > In the code -- I assume it should be at the top level?
>> > i.e. a sibling of the README file?   i.e.
>> >
>> >
>> >  qpid-proton-0.4/pulitzer_prize_winning_documentation
>> >
>> >
>> > or something along those lines?
>> >
>> > Agree?  Disagree?
>> >
>> >
>> >
>> >
>> >
>> >
>> > - Original Message -
>> > From: "Phil Harvey" 
>> > To: proton@qpid.apache.org
>> > Sent: Monday, February 25, 2013 12:14:00 PM
>> > Subject: Re: [documentation] -- Intro to Proton
>> >
>> > Hi Michael,
>> >
>> > Maybe you didn't see my previous question (or maybe I didn't see your
>> > answer).
>> >
>> > Where are you intending to store this documentation?  Similarly, where
>> are
>> > you intending to publish it, e.g. as HTML and/or PDF on our web site, as
>> a
>> > wiki page etc?
>> >
>> > Thanks
>> > Phil
>> >
>> >
>> > On 25 February 2013 16:15, Michael Goulish  wrote:
>> >
>> >>
>> >> Here's the introduction I'm planning on.
>> >>
>> >> If anyone has any opinions, I'd be happy to get them --
>> >> is there too much detail for a quick intro?  Too
>> >> little?  A crucial bit I left out?  Something I got wrong?
>> >>
>> >> ##
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> Introduction to Proton
>> >> ===
>> >>
>> >>
>> >>
>> >> The Messenger interface is a simple, high-level API that lets
>> >> you create point-to-point messaging applications quickly and easily.
>> >>
>> >> The interface offers four main categories of functionality.
>> >>
>> >>
>> >>
>> >>
>> >> Messenger Operation
>> >> ---
>> >>
>> >>   There are only a few operations that are not directly concerning
>> >>   with message transmission.
>> >>
>> >>   A messenger can be created, named, and freed.  It can be started
>> >>   and stopped, and it can be checked for errors after any operation.
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> Sending and Receiving
>> >> ---
>> >>
>> >>   Both sending and receiving happen in two stages, the inner stage
>> >>   moving the message between your application and a queue, the
>> >>   outer stage transmitting messages between your queues and
>> >>   remote messaging nodes.
>> >>
>&g

Re: [documentation] -- Intro to Proton

[Alan Conway]

On Tue, 2013-02-26 at 10:37 -0500, Michael Goulish wrote:
> Phil -- 
> 
> Wow, I was thinking of using ASCII.

Markdown is ASCII.

> Let me look at Markdown hmm, I do like the sound of this:
> 
>   "radically simplified and far more human readable form of HTML"
> 
> 
> But what's the value proposition of using any kind of markup?
> Better readability?  Linking with other docs?

We need to provide docs in HTML and PDF. It is impossible to generate
useful HTML or PDF from arbitrarily structured ASCII. 

> It seems to me that, at least after a build process, we should have 
> plain ASCII somewhere.  Do you agree?

Markdown is plain ASCII but with fixed conventions about how to
represent headings, bold, italic etc. It is intended to be readable as
plain ascii as well as being structured enough to generate HTML etc.

> 
> But it does seem reasonable to do some form of markup as the foundation
> and generate other things from there (including flat ASCII).
> 
> 
> I like the Markdown concept.  
> ( And I think DocBook is way too heavyweight. )
> ( And I suppose that nothing but flat ASCII is too lightweight. )
> Does anybody else agree ?
> 

Yep. I've never tried it but I think its worth a try. Docbook is a pain.
My main concern is  how we verify that changes to the doc are valid
markdown. Anyone know of approaches to that?

Re: [documentation] -- Intro to Proton

[Rafael Schloming]

It's important that whatever it is adds minimal dependencies to the toolset
required to build. I took a quick look at markdown and it seems to have a
number of different implementations (perl, php, python, etc) that are
fairly widely available. The web site also claims that it is designed to be
natural looking and human readable in its original form without any
processing, so worst case if the tools aren't available we can skip that
part of the build and let people read the source documentation directly.
Given all that it sounds like it's worth a try to me.

--Rafael

On Tue, Feb 26, 2013 at 8:20 AM, Alan Conway  wrote:

> On Tue, 2013-02-26 at 01:56 +, Phil Harvey wrote:
> > I do agree with you that having documentation committed alongside code is
> > the right approach.
> >
> > I propose that we write this documentation in Markdown syntax. That gives
> > us (or our users) the option of easily generating HTML whilst keeping the
> > barrier to entry low for authors.
>
> Markdown is worth a try. docbook is a severe pain in the rear to write
> and the XML is almost as painful to read. Seems like pandoc can generate
> PDF and even docbook from markdown.
>
> >
> > I recognise that Markdown lacks the semantic richness of Docbook (used
> for
> > the Qpid Broker), but I believe that's ok in this case since our
> > documentation should be quite short (or we're doing something wrong).
> >
> > Phil
> > On Feb 25, 2013 7:07 PM, "Rajith Attapattu"  wrote:
> >
> > > I'm strong believer in maintaining our docs in the source tree, as it
> > > makes it easy to release docs along side the code.
> > > Also it helps keep the docs current.
> > > The wiki based documentation in the past had many issues, the chief
> > > complaint being stale most of the time.
> > >
> > > We could look at doing something similar to the qpid docs, or we could
> > > also use this opportunity to experiment with a different approach/tool
> > > set.
> > >
> > > Rajith
> > >
> > > On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish 
> > > wrote:
> > > >
> > > > I think I will be landing it in the code tree first, and
> > > > from there, I don't know.   Any suggestions?
> > > >
> > > > In the code -- I assume it should be at the top level?
> > > > i.e. a sibling of the README file?   i.e.
> > > >
> > > >
> > > >  qpid-proton-0.4/pulitzer_prize_winning_documentation
> > > >
> > > >
> > > > or something along those lines?
> > > >
> > > > Agree?  Disagree?
> > > >
> > > >
> > > >
> > > >
> > > >
> > > >
> > > > - Original Message -
> > > > From: "Phil Harvey" 
> > > > To: proton@qpid.apache.org
> > > > Sent: Monday, February 25, 2013 12:14:00 PM
> > > > Subject: Re: [documentation] -- Intro to Proton
> > > >
> > > > Hi Michael,
> > > >
> > > > Maybe you didn't see my previous question (or maybe I didn't see your
> > > > answer).
> > > >
> > > > Where are you intending to store this documentation?  Similarly,
> where
> > > are
> > > > you intending to publish it, e.g. as HTML and/or PDF on our web
> site, as
> > > a
> > > > wiki page etc?
> > > >
> > > > Thanks
> > > > Phil
> > > >
> > > >
> > > > On 25 February 2013 16:15, Michael Goulish 
> wrote:
> > > >
> > > >>
> > > >> Here's the introduction I'm planning on.
> > > >>
> > > >> If anyone has any opinions, I'd be happy to get them --
> > > >> is there too much detail for a quick intro?  Too
> > > >> little?  A crucial bit I left out?  Something I got wrong?
> > > >>
> > > >> ##
> > > >>
> > > >>
> > > >>
> > > >>
> > > >>
> > > >> Introduction to Proton
> > > >> ===
> > > >>
> > > >>
> > > >>
> > > >> The Messenger interface is a simple, high-level API that lets
> > > >> you create point-to-point messaging applications quickly and easily.
> > > >>
> > > 

Re: [documentation] -- Intro to Proton

[Alan Conway]

On Tue, 2013-02-26 at 01:56 +, Phil Harvey wrote:
> I do agree with you that having documentation committed alongside code is
> the right approach.
> 
> I propose that we write this documentation in Markdown syntax. That gives
> us (or our users) the option of easily generating HTML whilst keeping the
> barrier to entry low for authors.

Markdown is worth a try. docbook is a severe pain in the rear to write
and the XML is almost as painful to read. Seems like pandoc can generate
PDF and even docbook from markdown.

> 
> I recognise that Markdown lacks the semantic richness of Docbook (used for
> the Qpid Broker), but I believe that's ok in this case since our
> documentation should be quite short (or we're doing something wrong).
> 
> Phil
> On Feb 25, 2013 7:07 PM, "Rajith Attapattu"  wrote:
> 
> > I'm strong believer in maintaining our docs in the source tree, as it
> > makes it easy to release docs along side the code.
> > Also it helps keep the docs current.
> > The wiki based documentation in the past had many issues, the chief
> > complaint being stale most of the time.
> >
> > We could look at doing something similar to the qpid docs, or we could
> > also use this opportunity to experiment with a different approach/tool
> > set.
> >
> > Rajith
> >
> > On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish 
> > wrote:
> > >
> > > I think I will be landing it in the code tree first, and
> > > from there, I don't know.   Any suggestions?
> > >
> > > In the code -- I assume it should be at the top level?
> > > i.e. a sibling of the README file?   i.e.
> > >
> > >
> > >  qpid-proton-0.4/pulitzer_prize_winning_documentation
> > >
> > >
> > > or something along those lines?
> > >
> > > Agree?  Disagree?
> > >
> > >
> > >
> > >
> > >
> > >
> > > - Original Message -
> > > From: "Phil Harvey" 
> > > To: proton@qpid.apache.org
> > > Sent: Monday, February 25, 2013 12:14:00 PM
> > > Subject: Re: [documentation] -- Intro to Proton
> > >
> > > Hi Michael,
> > >
> > > Maybe you didn't see my previous question (or maybe I didn't see your
> > > answer).
> > >
> > > Where are you intending to store this documentation?  Similarly, where
> > are
> > > you intending to publish it, e.g. as HTML and/or PDF on our web site, as
> > a
> > > wiki page etc?
> > >
> > > Thanks
> > > Phil
> > >
> > >
> > > On 25 February 2013 16:15, Michael Goulish  wrote:
> > >
> > >>
> > >> Here's the introduction I'm planning on.
> > >>
> > >> If anyone has any opinions, I'd be happy to get them --
> > >> is there too much detail for a quick intro?  Too
> > >> little?  A crucial bit I left out?  Something I got wrong?
> > >>
> > >> ##
> > >>
> > >>
> > >>
> > >>
> > >>
> > >> Introduction to Proton
> > >> ===
> > >>
> > >>
> > >>
> > >> The Messenger interface is a simple, high-level API that lets
> > >> you create point-to-point messaging applications quickly and easily.
> > >>
> > >> The interface offers four main categories of functionality.
> > >>
> > >>
> > >>
> > >>
> > >> Messenger Operation
> > >> ---
> > >>
> > >>   There are only a few operations that are not directly concerning
> > >>   with message transmission.
> > >>
> > >>   A messenger can be created, named, and freed.  It can be started
> > >>   and stopped, and it can be checked for errors after any operation.
> > >>
> > >>
> > >>
> > >>
> > >>
> > >> Sending and Receiving
> > >> ---
> > >>
> > >>   Both sending and receiving happen in two stages, the inner stage
> > >>   moving the message between your application and a queue, the
> > >>   outer stage transmitting messages between your queues and
> > >>   remote messaging nodes.
> > >>
>

Re: [documentation] -- Intro to Proton

[Michael Goulish]

Phil -- 

Wow, I was thinking of using ASCII.

Let me look at Markdown hmm, I do like the sound of this:

  "radically simplified and far more human readable form of HTML"


But what's the value proposition of using any kind of markup?
Better readability?  Linking with other docs?

It seems to me that, at least after a build process, we should have 
plain ASCII somewhere.  Do you agree?

But it does seem reasonable to do some form of markup as the foundation
and generate other things from there (including flat ASCII).


I like the Markdown concept.  
( And I think DocBook is way too heavyweight. )
( And I suppose that nothing but flat ASCII is too lightweight. )
Does anybody else agree ?



 Mick  .





- Original Message -
From: "Phil Harvey" 
To: proton@qpid.apache.org
Sent: Monday, February 25, 2013 8:56:12 PM
Subject: Re: [documentation] -- Intro to Proton

I do agree with you that having documentation committed alongside code is
the right approach.

I propose that we write this documentation in Markdown syntax. That gives
us (or our users) the option of easily generating HTML whilst keeping the
barrier to entry low for authors.

I recognise that Markdown lacks the semantic richness of Docbook (used for
the Qpid Broker), but I believe that's ok in this case since our
documentation should be quite short (or we're doing something wrong).

Phil
On Feb 25, 2013 7:07 PM, "Rajith Attapattu"  wrote:

> I'm strong believer in maintaining our docs in the source tree, as it
> makes it easy to release docs along side the code.
> Also it helps keep the docs current.
> The wiki based documentation in the past had many issues, the chief
> complaint being stale most of the time.
>
> We could look at doing something similar to the qpid docs, or we could
> also use this opportunity to experiment with a different approach/tool
> set.
>
> Rajith
>
> On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish 
> wrote:
> >
> > I think I will be landing it in the code tree first, and
> > from there, I don't know.   Any suggestions?
> >
> > In the code -- I assume it should be at the top level?
> > i.e. a sibling of the README file?   i.e.
> >
> >
> >  qpid-proton-0.4/pulitzer_prize_winning_documentation
> >
> >
> > or something along those lines?
> >
> > Agree?  Disagree?
> >
> >
> >
> >
> >
> >
> > - Original Message -
> > From: "Phil Harvey" 
> > To: proton@qpid.apache.org
> > Sent: Monday, February 25, 2013 12:14:00 PM
> > Subject: Re: [documentation] -- Intro to Proton
> >
> > Hi Michael,
> >
> > Maybe you didn't see my previous question (or maybe I didn't see your
> > answer).
> >
> > Where are you intending to store this documentation?  Similarly, where
> are
> > you intending to publish it, e.g. as HTML and/or PDF on our web site, as
> a
> > wiki page etc?
> >
> > Thanks
> > Phil
> >
> >
> > On 25 February 2013 16:15, Michael Goulish  wrote:
> >
> >>
> >> Here's the introduction I'm planning on.
> >>
> >> If anyone has any opinions, I'd be happy to get them --
> >> is there too much detail for a quick intro?  Too
> >> little?  A crucial bit I left out?  Something I got wrong?
> >>
> >> ##
> >>
> >>
> >>
> >>
> >>
> >> Introduction to Proton
> >> ===
> >>
> >>
> >>
> >> The Messenger interface is a simple, high-level API that lets
> >> you create point-to-point messaging applications quickly and easily.
> >>
> >> The interface offers four main categories of functionality.
> >>
> >>
> >>
> >>
> >> Messenger Operation
> >> ---
> >>
> >>   There are only a few operations that are not directly concerning
> >>   with message transmission.
> >>
> >>   A messenger can be created, named, and freed.  It can be started
> >>   and stopped, and it can be checked for errors after any operation.
> >>
> >>
> >>
> >>
> >>
> >> Sending and Receiving
> >> ---
> >>
> >>   Both sending and receiving happen in two stages, the inner stage
> >>   moving the message between your application and a queue, the
> >>   outer stage tr

Re: [documentation] -- Intro to Proton

[Michael Goulish]

Jakub -- 

Thanks for your thoughts!

Yes, I am thinking of it as part of a larger doc, and yes I 
definitely should change that to specify "Proton Messenger API".
I keep forgetting that there are more quarks in this particle than 
just the one I am looking at!I'll make that change in next version.

And in addition to the name change, I should also mention in my doc 
that there are other interfaces that the Messenger API uses -- maybe 
give a quick list of all of them ( engine, driver, whatever ).

Maybe I'll get to do similar docs for each interface.


--- Mick .





- Original Message -
From: "Jakub Scholz" 
To: proton@qpid.apache.org
Sent: Monday, February 25, 2013 5:53:29 PM
Subject: Re: [documentation] -- Intro to Proton

Hi Michael,

I know you mentioned plans to write some bigger document ... it is not
entirely clear to me, whether this is supposed to be a standalone
introduction or just a first chapter of the larger document. It suppose the
second is correct, right?

Also, is it introduction to Proton or just to the Proton Messenger API?
>From what I understood so far from the discussions here in the mailing
list, Proton is much more than just the Messenger API. I would either call
it Proton Messenger introduction or add some short explanation that the
Messenger API is just one part of Proton which might be the most
interesting for beginners.

Thanks & Regards
Jakub

On Mon, Feb 25, 2013 at 5:15 PM, Michael Goulish wrote:

>   The messenger interface allows you to use the Secure Sockets Layer
>   by exposing an interface to the OpenSSL library.
>

Re: [documentation] -- Intro to Proton

[Phil Harvey]

I do agree with you that having documentation committed alongside code is
the right approach.

I propose that we write this documentation in Markdown syntax. That gives
us (or our users) the option of easily generating HTML whilst keeping the
barrier to entry low for authors.

I recognise that Markdown lacks the semantic richness of Docbook (used for
the Qpid Broker), but I believe that's ok in this case since our
documentation should be quite short (or we're doing something wrong).

Phil
On Feb 25, 2013 7:07 PM, "Rajith Attapattu"  wrote:

> I'm strong believer in maintaining our docs in the source tree, as it
> makes it easy to release docs along side the code.
> Also it helps keep the docs current.
> The wiki based documentation in the past had many issues, the chief
> complaint being stale most of the time.
>
> We could look at doing something similar to the qpid docs, or we could
> also use this opportunity to experiment with a different approach/tool
> set.
>
> Rajith
>
> On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish 
> wrote:
> >
> > I think I will be landing it in the code tree first, and
> > from there, I don't know.   Any suggestions?
> >
> > In the code -- I assume it should be at the top level?
> > i.e. a sibling of the README file?   i.e.
> >
> >
> >  qpid-proton-0.4/pulitzer_prize_winning_documentation
> >
> >
> > or something along those lines?
> >
> > Agree?  Disagree?
> >
> >
> >
> >
> >
> >
> > - Original Message -
> > From: "Phil Harvey" 
> > To: proton@qpid.apache.org
> > Sent: Monday, February 25, 2013 12:14:00 PM
> > Subject: Re: [documentation] -- Intro to Proton
> >
> > Hi Michael,
> >
> > Maybe you didn't see my previous question (or maybe I didn't see your
> > answer).
> >
> > Where are you intending to store this documentation?  Similarly, where
> are
> > you intending to publish it, e.g. as HTML and/or PDF on our web site, as
> a
> > wiki page etc?
> >
> > Thanks
> > Phil
> >
> >
> > On 25 February 2013 16:15, Michael Goulish  wrote:
> >
> >>
> >> Here's the introduction I'm planning on.
> >>
> >> If anyone has any opinions, I'd be happy to get them --
> >> is there too much detail for a quick intro?  Too
> >> little?  A crucial bit I left out?  Something I got wrong?
> >>
> >> ##
> >>
> >>
> >>
> >>
> >>
> >> Introduction to Proton
> >> ===
> >>
> >>
> >>
> >> The Messenger interface is a simple, high-level API that lets
> >> you create point-to-point messaging applications quickly and easily.
> >>
> >> The interface offers four main categories of functionality.
> >>
> >>
> >>
> >>
> >> Messenger Operation
> >> ---
> >>
> >>   There are only a few operations that are not directly concerning
> >>   with message transmission.
> >>
> >>   A messenger can be created, named, and freed.  It can be started
> >>   and stopped, and it can be checked for errors after any operation.
> >>
> >>
> >>
> >>
> >>
> >> Sending and Receiving
> >> ---
> >>
> >>   Both sending and receiving happen in two stages, the inner stage
> >>   moving the message between your application and a queue, the
> >>   outer stage transmitting messages between your queues and
> >>   remote messaging nodes.
> >>
> >>   By changing the ratio of transmissions to queue transfers, you
> >>   can optimize your messaging application for message latency or
> >>   for overall throughput.
> >>
> >>   Subscriptions control what sources your messenger can receive
> >>   from, and what sources it can send to.  Your messenger
> >>   subscribes to the sources you want to receive from, while your
> >>   outgoing messages will be received by messengers that have
> >>   subscribed to your outgoing address.
> >>
> >>
> >>
> >>
> >>
> >> Message Disposition
> >> ---
> >>
> >>   When you receive messages, you must either accept or reject them.
> >>
> &

Re: [documentation] -- Intro to Proton

[Jakub Scholz]

Hi Michael,

I know you mentioned plans to write some bigger document ... it is not
entirely clear to me, whether this is supposed to be a standalone
introduction or just a first chapter of the larger document. It suppose the
second is correct, right?

Also, is it introduction to Proton or just to the Proton Messenger API?
>From what I understood so far from the discussions here in the mailing
list, Proton is much more than just the Messenger API. I would either call
it Proton Messenger introduction or add some short explanation that the
Messenger API is just one part of Proton which might be the most
interesting for beginners.

Thanks & Regards
Jakub

On Mon, Feb 25, 2013 at 5:15 PM, Michael Goulish wrote:

>   The messenger interface allows you to use the Secure Sockets Layer
>   by exposing an interface to the OpenSSL library.
>

Re: [documentation] -- Intro to Proton

[Rajith Attapattu]

I'm strong believer in maintaining our docs in the source tree, as it
makes it easy to release docs along side the code.
Also it helps keep the docs current.
The wiki based documentation in the past had many issues, the chief
complaint being stale most of the time.

We could look at doing something similar to the qpid docs, or we could
also use this opportunity to experiment with a different approach/tool
set.

Rajith

On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish  wrote:
>
> I think I will be landing it in the code tree first, and
> from there, I don't know.   Any suggestions?
>
> In the code -- I assume it should be at the top level?
> i.e. a sibling of the README file?   i.e.
>
>
>  qpid-proton-0.4/pulitzer_prize_winning_documentation
>
>
> or something along those lines?
>
> Agree?  Disagree?
>
>
>
>
>
>
> - Original Message -
> From: "Phil Harvey" 
> To: proton@qpid.apache.org
> Sent: Monday, February 25, 2013 12:14:00 PM
> Subject: Re: [documentation] -- Intro to Proton
>
> Hi Michael,
>
> Maybe you didn't see my previous question (or maybe I didn't see your
> answer).
>
> Where are you intending to store this documentation?  Similarly, where are
> you intending to publish it, e.g. as HTML and/or PDF on our web site, as a
> wiki page etc?
>
> Thanks
> Phil
>
>
> On 25 February 2013 16:15, Michael Goulish  wrote:
>
>>
>> Here's the introduction I'm planning on.
>>
>> If anyone has any opinions, I'd be happy to get them --
>> is there too much detail for a quick intro?  Too
>> little?  A crucial bit I left out?  Something I got wrong?
>>
>> ##
>>
>>
>>
>>
>>
>> Introduction to Proton
>> ===
>>
>>
>>
>> The Messenger interface is a simple, high-level API that lets
>> you create point-to-point messaging applications quickly and easily.
>>
>> The interface offers four main categories of functionality.
>>
>>
>>
>>
>> Messenger Operation
>> ---
>>
>>   There are only a few operations that are not directly concerning
>>   with message transmission.
>>
>>   A messenger can be created, named, and freed.  It can be started
>>   and stopped, and it can be checked for errors after any operation.
>>
>>
>>
>>
>>
>> Sending and Receiving
>> ---
>>
>>   Both sending and receiving happen in two stages, the inner stage
>>   moving the message between your application and a queue, the
>>   outer stage transmitting messages between your queues and
>>   remote messaging nodes.
>>
>>   By changing the ratio of transmissions to queue transfers, you
>>   can optimize your messaging application for message latency or
>>   for overall throughput.
>>
>>   Subscriptions control what sources your messenger can receive
>>   from, and what sources it can send to.  Your messenger
>>   subscribes to the sources you want to receive from, while your
>>   outgoing messages will be received by messengers that have
>>   subscribed to your outgoing address.
>>
>>
>>
>>
>>
>> Message Disposition
>> ---
>>
>>   When you receive messages, you must either accept or reject them.
>>
>>   You can either configure your messenger to automatically accept
>>   all messages that you get, or you can exercise finer control over
>>   message acceptance and rejection, individually or in groups.
>>
>>   Trackers and Windows let you set or check the disposition of
>>   messages in groups.  Applying the disposition operations to
>>   groups of messages can improve your system's throughput.
>>
>>   When receiving messages, you can create a tracker
>>   for the most recently received message, and later use that tracker
>>   to accept or reject all messages up to (and including) that one.
>>
>>   When sending messages, you can create a tracker for your most
>>   recently sent message, and later use it to inquire about the
>>   remote disposition of all sent messages up to that point.
>>   If you don't want to let a receiver make you wait forever
>>   to see what he's going to do, you can set a timeout that will
>>   control how long he can take making up his mind.
>>
>>   By using incoming and outgoing Windows, you can limit the
>>   number of messages that these operations affect.
>>
>>
>>
>>
>>
>>
>>
>> Security
>> ---
>>
>>   The messenger interface allows you to use the Secure Sockets Layer
>>   by exposing an interface to the OpenSSL library.
>>
>>
>>
>>

Re: [documentation] -- Intro to Proton

[Michael Goulish]

I think I will be landing it in the code tree first, and
from there, I don't know.   Any suggestions?

In the code -- I assume it should be at the top level?  
i.e. a sibling of the README file?   i.e.  


 qpid-proton-0.4/pulitzer_prize_winning_documentation


or something along those lines?

Agree?  Disagree?






- Original Message -
From: "Phil Harvey" 
To: proton@qpid.apache.org
Sent: Monday, February 25, 2013 12:14:00 PM
Subject: Re: [documentation] -- Intro to Proton

Hi Michael,

Maybe you didn't see my previous question (or maybe I didn't see your
answer).

Where are you intending to store this documentation?  Similarly, where are
you intending to publish it, e.g. as HTML and/or PDF on our web site, as a
wiki page etc?

Thanks
Phil


On 25 February 2013 16:15, Michael Goulish  wrote:

>
> Here's the introduction I'm planning on.
>
> If anyone has any opinions, I'd be happy to get them --
> is there too much detail for a quick intro?  Too
> little?  A crucial bit I left out?  Something I got wrong?
>
> ##
>
>
>
>
>
> Introduction to Proton
> ===
>
>
>
> The Messenger interface is a simple, high-level API that lets
> you create point-to-point messaging applications quickly and easily.
>
> The interface offers four main categories of functionality.
>
>
>
>
> Messenger Operation
> ---
>
>   There are only a few operations that are not directly concerning
>   with message transmission.
>
>   A messenger can be created, named, and freed.  It can be started
>   and stopped, and it can be checked for errors after any operation.
>
>
>
>
>
> Sending and Receiving
> ---
>
>   Both sending and receiving happen in two stages, the inner stage
>   moving the message between your application and a queue, the
>   outer stage transmitting messages between your queues and
>   remote messaging nodes.
>
>   By changing the ratio of transmissions to queue transfers, you
>   can optimize your messaging application for message latency or
>   for overall throughput.
>
>   Subscriptions control what sources your messenger can receive
>   from, and what sources it can send to.  Your messenger
>   subscribes to the sources you want to receive from, while your
>   outgoing messages will be received by messengers that have
>   subscribed to your outgoing address.
>
>
>
>
>
> Message Disposition
> ---
>
>   When you receive messages, you must either accept or reject them.
>
>   You can either configure your messenger to automatically accept
>   all messages that you get, or you can exercise finer control over
>   message acceptance and rejection, individually or in groups.
>
>   Trackers and Windows let you set or check the disposition of
>   messages in groups.  Applying the disposition operations to
>   groups of messages can improve your system's throughput.
>
>   When receiving messages, you can create a tracker
>   for the most recently received message, and later use that tracker
>   to accept or reject all messages up to (and including) that one.
>
>   When sending messages, you can create a tracker for your most
>   recently sent message, and later use it to inquire about the
>   remote disposition of all sent messages up to that point.
>   If you don't want to let a receiver make you wait forever
>   to see what he's going to do, you can set a timeout that will
>   control how long he can take making up his mind.
>
>   By using incoming and outgoing Windows, you can limit the
>   number of messages that these operations affect.
>
>
>
>
>
>
>
> Security
> ---
>
>   The messenger interface allows you to use the Secure Sockets Layer
>   by exposing an interface to the OpenSSL library.
>
>
>
>

Re: [documentation] -- Intro to Proton

[Phil Harvey]

Hi Michael,

Maybe you didn't see my previous question (or maybe I didn't see your
answer).

Where are you intending to store this documentation?  Similarly, where are
you intending to publish it, e.g. as HTML and/or PDF on our web site, as a
wiki page etc?

Thanks
Phil


On 25 February 2013 16:15, Michael Goulish  wrote:

>
> Here's the introduction I'm planning on.
>
> If anyone has any opinions, I'd be happy to get them --
> is there too much detail for a quick intro?  Too
> little?  A crucial bit I left out?  Something I got wrong?
>
> ##
>
>
>
>
>
> Introduction to Proton
> ===
>
>
>
> The Messenger interface is a simple, high-level API that lets
> you create point-to-point messaging applications quickly and easily.
>
> The interface offers four main categories of functionality.
>
>
>
>
> Messenger Operation
> ---
>
>   There are only a few operations that are not directly concerning
>   with message transmission.
>
>   A messenger can be created, named, and freed.  It can be started
>   and stopped, and it can be checked for errors after any operation.
>
>
>
>
>
> Sending and Receiving
> ---
>
>   Both sending and receiving happen in two stages, the inner stage
>   moving the message between your application and a queue, the
>   outer stage transmitting messages between your queues and
>   remote messaging nodes.
>
>   By changing the ratio of transmissions to queue transfers, you
>   can optimize your messaging application for message latency or
>   for overall throughput.
>
>   Subscriptions control what sources your messenger can receive
>   from, and what sources it can send to.  Your messenger
>   subscribes to the sources you want to receive from, while your
>   outgoing messages will be received by messengers that have
>   subscribed to your outgoing address.
>
>
>
>
>
> Message Disposition
> ---
>
>   When you receive messages, you must either accept or reject them.
>
>   You can either configure your messenger to automatically accept
>   all messages that you get, or you can exercise finer control over
>   message acceptance and rejection, individually or in groups.
>
>   Trackers and Windows let you set or check the disposition of
>   messages in groups.  Applying the disposition operations to
>   groups of messages can improve your system's throughput.
>
>   When receiving messages, you can create a tracker
>   for the most recently received message, and later use that tracker
>   to accept or reject all messages up to (and including) that one.
>
>   When sending messages, you can create a tracker for your most
>   recently sent message, and later use it to inquire about the
>   remote disposition of all sent messages up to that point.
>   If you don't want to let a receiver make you wait forever
>   to see what he's going to do, you can set a timeout that will
>   control how long he can take making up his mind.
>
>   By using incoming and outgoing Windows, you can limit the
>   number of messages that these operations affect.
>
>
>
>
>
>
>
> Security
> ---
>
>   The messenger interface allows you to use the Secure Sockets Layer
>   by exposing an interface to the OpenSSL library.
>
>
>
>

[documentation] -- Intro to Proton

[Michael Goulish]

Here's the introduction I'm planning on.

If anyone has any opinions, I'd be happy to get them -- 
is there too much detail for a quick intro?  Too 
little?  A crucial bit I left out?  Something I got wrong?

##





Introduction to Proton
===



The Messenger interface is a simple, high-level API that lets 
you create point-to-point messaging applications quickly and easily.

The interface offers four main categories of functionality.




Messenger Operation
---

  There are only a few operations that are not directly concerning
  with message transmission.

  A messenger can be created, named, and freed.  It can be started
  and stopped, and it can be checked for errors after any operation.





Sending and Receiving
---

  Both sending and receiving happen in two stages, the inner stage
  moving the message between your application and a queue, the
  outer stage transmitting messages between your queues and
  remote messaging nodes.

  By changing the ratio of transmissions to queue transfers, you
  can optimize your messaging application for message latency or
  for overall throughput.

  Subscriptions control what sources your messenger can receive
  from, and what sources it can send to.  Your messenger
  subscribes to the sources you want to receive from, while your
  outgoing messages will be received by messengers that have
  subscribed to your outgoing address.





Message Disposition
---

  When you receive messages, you must either accept or reject them.

  You can either configure your messenger to automatically accept
  all messages that you get, or you can exercise finer control over
  message acceptance and rejection, individually or in groups.

  Trackers and Windows let you set or check the disposition of
  messages in groups.  Applying the disposition operations to
  groups of messages can improve your system's throughput.

  When receiving messages, you can create a tracker
  for the most recently received message, and later use that tracker
  to accept or reject all messages up to (and including) that one.

  When sending messages, you can create a tracker for your most
  recently sent message, and later use it to inquire about the
  remote disposition of all sent messages up to that point.
  If you don't want to let a receiver make you wait forever
  to see what he's going to do, you can set a timeout that will
  control how long he can take making up his mind.

  By using incoming and outgoing Windows, you can limit the
  number of messages that these operations affect.







Security
---

  The messenger interface allows you to use the Secure Sockets Layer
  by exposing an interface to the OpenSSL library.