Bug 1099448

(In reply to Petr Matousek from comment #0)
> Description of problem:
> 
> Several connection options are missing in the connection options reference,
> please see:
> http://deathstar1.usersys.redhat.com:3000/builds/19948-
> Messaging_Programming_Reference/#Connection_Options_Reference
> 
> Following options are not documented:
>   - reconnect-urls-replace
>   - locale
>   - max-channels
>   - max-frame-size
>   - bounds
>   - ssl-cert-name
>   - x-reconnect-on-limit-exceeded 
> 
> Moreover there are several amqp1.0 specific options:
>   - container-id
>   - nest-annotations
>   - properties
> 
> Version-Release number of selected component (if applicable):
> Messaging Programming Reference - latest build
> 
> How reproducible:
> n/a
> 
> Steps to Reproduce:
> n/a
> 
> Actual results:
> Incomplete list of supported connection options.
> 
> Expected results:
> Connection Options Reference lists all the supported connection options.
> 
> Additional info:

Hey Petr, refresh my memory. These config options are documented somewhere, apart from the --help for the tool. What was the link again?

Update:
- asked on mrg-program-list for SME assistance with correct options.

From what I can tell, the parameters with missing documentation are these:

 - reconnect_urls_replace
 - locale
 - bounds
 - x-reconnect-on-limit-exceeded

Everything else is covered in the 0.30 api doc.  The latter, with the x- prefix, likely should *not* be documented.

Gordon, for the others can, you provide blurbs?

(In reply to Justin Ross from comment #7)
> From what I can tell, the parameters with missing documentation are these:
> 
>  - reconnect_urls_replace
>  - locale
>  - bounds
>  - x-reconnect-on-limit-exceeded
> 
> Everything else is covered in the 0.30 api doc.  The latter, with the x-
> prefix, likely should *not* be documented.
> 
> Gordon, for the others can, you provide blurbs?

The reconnect_urls_replace option is used to control how setting the reconect_urls option is treated. If true, then setting reconnect_urls causes the old list to be replaced with the new one. If false, the new list is added to the old list. It's false by default, which seems wrong to me, and I'm not crazy about the logic of this option. It was mostly added for internal use with the updating of cluster membership if I recall.

I wouldn't document the others at this stage (not sure that I would bother with the one above either tbh).

The 'bounds' option was an early hack to control buffering, I wouldn't recommend anyone to change it. The 'locale' isn't yet sent over 1.0, and for 0-10 I don't believe there is any broker in existence that pays any attention to it. The x-reconnect-on-limit-exceeded is 0-10 specific. It was used before we had producer flow control as a way of handling hitting limits. With producer flow control implemented it is not as useful and again, I would not really recommend anyone to use it at this point.

(In reply to Gordon Sim from comment #8)
> (In reply to Justin Ross from comment #7)
> > From what I can tell, the parameters with missing documentation are these:
> > 
> >  - reconnect_urls_replace
> >  - locale
> >  - bounds
> >  - x-reconnect-on-limit-exceeded
> > 
> > Everything else is covered in the 0.30 api doc.  The latter, with the x-
> > prefix, likely should *not* be documented.
> > 
> > Gordon, for the others can, you provide blurbs?
> 
> The reconnect_urls_replace option is used to control how setting the
> reconect_urls option is treated. If true, then setting reconnect_urls causes
> the old list to be replaced with the new one. If false, the new list is
> added to the old list. It's false by default, which seems wrong to me, and
> I'm not crazy about the logic of this option. It was mostly added for
> internal use with the updating of cluster membership if I recall.
> 
> I wouldn't document the others at this stage (not sure that I would bother
> with the one above either tbh).
> 
> The 'bounds' option was an early hack to control buffering, I wouldn't
> recommend anyone to change it. The 'locale' isn't yet sent over 1.0, and for
> 0-10 I don't believe there is any broker in existence that pays any
> attention to it. The x-reconnect-on-limit-exceeded is 0-10 specific. It was
> used before we had producer flow control as a way of handling hitting
> limits. With producer flow control implemented it is not as useful and
> again, I would not really recommend anyone to use it at this point.

Based on this advice, I have added only the reconnect_urls_replace option to the table at http://docbuilder.usersys.redhat.com/19948/#Connection_Options_Reference

There are still many connection options that are not properly documented in the MPR, summarizing: 

Added to the documentation (in scope ogf this bug):
  - reconnect-urls-replace

Per Gordon's suggestion we decided not to document the following:
  - locale
  - bounds
  - x-reconnect-on-limit-exceeded (and x-*)

To be documented:
  - max-channels
  - max-frame-size
  - ssl-cert-name
  - ssl_ignore_hostname_verification_failure

To be documented (AMQP1.0 specific):
  - container-id
  - nest-annotations
  - set_to_on_send
  - properties or client_properties

Gordon, do you have any comments here, are there any reasons why the options above shall not be mentioned in the Messaging Programing Reference (ie.: obsolete options)? Thanks for clarifying.

-> ASSIGNED

(In reply to Petr Matousek from comment #10)
> To be documented:
>   - max-channels
>   - max-frame-size
>   - ssl-cert-name
>   - ssl_ignore_hostname_verification_failure
> 
> To be documented (AMQP1.0 specific):
>   - container-id
>   - nest-annotations
>   - set_to_on_send
>   - properties or client_properties
> 
> Gordon, do you have any comments here, are there any reasons why the options
> above shall not be mentioned in the Messaging Programing Reference (ie.:
> obsolete options)? Thanks for clarifying.

No all of these can be documented, and are documented (albeit tersely) in the upstream doxygen comments. http://qpid.apache.org/releases/qpid-0.30/messaging-api/cpp/api/classqpid_1_1messaging_1_1Connection.html#a9fe3af4ad4a25621065c30a677dcbabe

(In reply to Gordon Sim from comment #11)
> (In reply to Petr Matousek from comment #10)
> > To be documented:
> >   - max-channels
> >   - max-frame-size
> >   - ssl-cert-name
> >   - ssl_ignore_hostname_verification_failure
> > 
> > To be documented (AMQP1.0 specific):
> >   - container-id
> >   - nest-annotations
> >   - set_to_on_send
> >   - properties or client_properties
> > 
> > Gordon, do you have any comments here, are there any reasons why the options
> > above shall not be mentioned in the Messaging Programing Reference (ie.:
> > obsolete options)? Thanks for clarifying.
> 
> No all of these can be documented, and are documented (albeit tersely) in
> the upstream doxygen comments.
> http://qpid.apache.org/releases/qpid-0.30/messaging-api/cpp/api/
> classqpid_1_1messaging_1_1Connection.html#a9fe3af4ad4a25621065c30a677dcbabe

So if "not all of these can be documented", which ones *should* be documented. Just the tersely documented ones in the doxygen comments? And then ignore the rest?

Just want to ensure I'm not wasting effort. Also, my apologies if I misinterpreted your comment above: it just seemed a little non-specific to me.

(In reply to Jared MORGAN from comment #12)
> (In reply to Gordon Sim from comment #11)
> > (In reply to Petr Matousek from comment #10)
> > > To be documented:
> > >   - max-channels
> > >   - max-frame-size
> > >   - ssl-cert-name
> > >   - ssl_ignore_hostname_verification_failure
> > > 
> > > To be documented (AMQP1.0 specific):
> > >   - container-id
> > >   - nest-annotations
> > >   - set_to_on_send
> > >   - properties or client_properties
> > > 
> > > Gordon, do you have any comments here, are there any reasons why the options
> > > above shall not be mentioned in the Messaging Programing Reference (ie.:
> > > obsolete options)? Thanks for clarifying.
> > 
> > No all of these can be documented, and are documented (albeit tersely) in
> > the upstream doxygen comments.
> > http://qpid.apache.org/releases/qpid-0.30/messaging-api/cpp/api/
> > classqpid_1_1messaging_1_1Connection.html#a9fe3af4ad4a25621065c30a677dcbabe
> 
> So if "not all of these can be documented", which ones *should* be
> documented. Just the tersely documented ones in the doxygen comments? And
> then ignore the rest?

There is a comma missing in my comment that you quote above. It should read 'No, all of these *can* be documented'.

(In reply to Gordon Sim from comment #13)
> (In reply to Jared MORGAN from comment #12)
> > (In reply to Gordon Sim from comment #11)
> > > (In reply to Petr Matousek from comment #10)
> > > > To be documented:
> > > >   - max-channels
> > > >   - max-frame-size
> > > >   - ssl-cert-name
> > > >   - ssl_ignore_hostname_verification_failure
> > > > 
> > > > To be documented (AMQP1.0 specific):
> > > >   - container-id
> > > >   - nest-annotations
> > > >   - set_to_on_send
> > > >   - properties or client_properties
> > > > 
> > > > Gordon, do you have any comments here, are there any reasons why the options
> > > > above shall not be mentioned in the Messaging Programing Reference (ie.:
> > > > obsolete options)? Thanks for clarifying.
> > > 
> > > No all of these can be documented, and are documented (albeit tersely) in
> > > the upstream doxygen comments.
> > > http://qpid.apache.org/releases/qpid-0.30/messaging-api/cpp/api/
> > > classqpid_1_1messaging_1_1Connection.html#a9fe3af4ad4a25621065c30a677dcbabe
> > 
> > So if "not all of these can be documented", which ones *should* be
> > documented. Just the tersely documented ones in the doxygen comments? And
> > then ignore the rest?
> 
> There is a comma missing in my comment that you quote above. It should read
> 'No, all of these *can* be documented'.

That's awesome! Thanks for confirming so quickly. I misread your statement and added a "t" where it shouldn't be. :(

I'll get on it for 3.2.

(In reply to Jared MORGAN from comment #14)
> I misread your statement and added a "t" where it shouldn't be. :(

My fault. I mistyped it, and missed out "," where there should have been one. Errare humanum est!

(In reply to Gordon Sim from comment #15)
> (In reply to Jared MORGAN from comment #14)
> > I misread your statement and added a "t" where it shouldn't be. :(
> 
> My fault. I mistyped it, and missed out "," where there should have been
> one. Errare humanum est!

No worries, Gordon.

I've done some work to this topic and tried to clarify what parameters work with what. (they were a bit jumbled together before). 

See the separate tables for what I'm getting at here. I've also added the descriptions in the doxygen comments as a starting point (or minimum standard) for those parameters that relate to this bug.

If options should be rejigged a bit in those tables, just let me know. I think having them split out a bit will help customers understand which parameters are compatible with what client versions.

http://docbuilder.usersys.redhat.com/19948/#Connection_Options_Reference

And if there are other sources for more "fleshed out" Semantic descriptions, please let me know where they are and I'll go get them.

Looks good to me!

(In reply to Gordon Sim from comment #17)
> Looks good to me!
Thanks for confirming. I'll push to QE, but based on your feedback this should be ready to release.

Taking ownership of MRG-M bugs

MPR Revision 3.2.0-1. content approved. 

-> VERIFIED

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://rhn.redhat.com/errata/RHEA-2015-1879.html