Bug 611560 - Documentation of change from BURL to ADDR for destinations is poor
Documentation of change from BURL to ADDR for destinations is poor
Status: CLOSED INSUFFICIENT_DATA
Product: Red Hat Enterprise MRG
Classification: Red Hat
Component: Messaging_Programming_Reference (Show other bugs)
beta
All All
high Severity high
: ---
: ---
Assigned To: Alison Young
ecs-bugs
: Documentation
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2010-07-05 12:18 EDT by Jiri Kolar
Modified: 2012-09-21 08:58 EDT (History)
5 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
<Release Notes> If you are upgrading an existing application (with destinations defined using the Binding URL format), to use the new Qpid libraries, one of the following needs to be done in order to ensure the destination definitions are parsed correctly. (a) Use -Dqpid.dest_syntax=BURL to switch the default destination syntax to Binding URL format. (b) Prefix each destination definition with "BURL:" Ex BURL:direct://amq.direct/MyQueue?routingkey='test' </Release Notes
Story Points: ---
Clone Of:
Environment:
Last Closed: 2011-08-28 20:18:05 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Jiri Kolar 2010-07-05 12:18:13 EDT
Description of problem:
Documentation does not explain the change from BURL to ADDR good enough. I guess many users will ask simply why the code that worked in 1.2 does not work on 1.3 anymore, and there should be a detailed explanation what changed and how to fix it. It should be probably included somewhere in FAQ.

Especially i miss completely documentation of switch  -Dqpid.dest_syntax=BURL that allows to use BURL addresses. This i probably going to be most used workaround for users with legacy code. 

Version-Release number of selected component (if applicable):
rhm-docs-0.7.946106-2

How reproducible:
see docs

Steps to Reproduce:
1.
2.
3.
  
Actual results:
there is nothing about this chage

Expected results:
this should be clearly documented

Additional info:
Comment 2 Rajith Attapattu 2010-09-14 22:20:30 EDT
The following information needs to be in the programming guide as well as the release notes.

* I will check in the doc updates to the upstream programming guide doc.
* I will open a separate BZ for the text that goes into release notes.


<Programming Guide>
The JMS client supports both Addressing and Binding URL formats for specifying destinations. It also allows both formats to be used simultaneously as well.

Default Destination Syntax.
---------------------------
By default any string describing a destination in the jndi file or passed into either session.createQueue or session.createTopic methods are interpreted based on the addressing format.

(*) If you only need a particular string to be interpreted as a binding URL, you would need to explicitly mark it with the prefix "BURL:".

Ex. BURL:direct://amq.direct/MyQueue?routingkey='test'


(*) If you are upgrading an existing application that uses the Binding URL format to use the new Qpid libraries you need to switch the default destination syntax to the Binding URL format as follows. (or else you need to prefix each string with "BURL:" as shown above)

   -Dqpid.dest_syntax=BURL  


(*) If you have switched the default to Binding URL format but would like to use the addressing format for any new development, you need to prefix any addressing string with "ADDR:" 

Ex. "ADDR:amq.topic/hello"
</Programming Guide>


<Release Notes>
If you are upgrading an existing application (with destinations defined using the Binding URL format), to use the new Qpid libraries, one of the following needs to be done in order to ensure the destination definitions are parsed correctly.

(a) Use -Dqpid.dest_syntax=BURL to switch the default destination syntax to Binding URL format.

(b) Prefix each destination definition with "BURL:"
Ex BURL:direct://amq.direct/MyQueue?routingkey='test'

</Release Notes>
Comment 3 Rajith Attapattu 2010-09-14 22:21:07 EDT
    Technical note added. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    New Contents:
<Release Notes>
If you are upgrading an existing application (with destinations defined using
the Binding URL format), to use the new Qpid libraries, one of the following
needs to be done in order to ensure the destination definitions are parsed
correctly.

(a) Use -Dqpid.dest_syntax=BURL to switch the default destination syntax to
Binding URL format.

(b) Prefix each destination definition with "BURL:"
Ex BURL:direct://amq.direct/MyQueue?routingkey='test'

</Release Notes
Comment 5 Lana Brindley 2011-02-02 19:11:03 EST
Release note will be added for 1.3.2.

Documentation changes will be assessed for 2.0.

LKB
Comment 6 Alison Young 2011-02-16 02:02:04 EST
Rajith, 

Can you please clarify which book this is for and what source content is to be used. I've been unable to determine if these update have been made already or not.

Thanks
Comment 9 Alison Young 2011-03-20 20:00:21 EDT
Deadline for this needinfo set to 30 June 2011 due to its inclusion in the 2.1
release. May change pending planning deadlines for MRG 2.1.
Comment 10 Susan Burgess 2011-04-11 22:08:41 EDT
It appears to be a duplicate of BZ 634043 whihc was doc'd in the Rlease Note . Please see:
http://documentation-stage.bne.redhat.com/docs/en-US/Red_Hat_Enterprise_MRG/1.3.2/html/MRG_Release_Notes/sect-MRG_Release_Notes-RHM-RHM_Update_Notes.html

INvestigate the correct book etc, as maybe this is filed under the wrong component.?

"Consider using the new addressing scheme from JMS. This is described further in the Programming with Apache Qpid guide. "
Comment 11 Alison Young 2011-04-13 22:01:38 EDT
It appears bug 634043 is the Release Note BZ for this.

There is currently no content about the following terms in the Programmers Guide, Programming in Apache Qpid, as at v1.3.
BURL
default destinations
session.createQueue 
session.createTopic 
Dqpid 
ADDR: 

A new section will need to be added using the content from Comment 2. Can Rajith please confirm this update to the Programming in Apache Qpid book is still accurate?

Note You need to log in before you can comment on or make changes to this bug.