Bug 778588

Jiri Pechanec has pointed out a number of faults in this doc.

* "3.2 Figure 3.1 and Figure 3.2 - each describes the same but have different structure (missing pieces in the figures)"
Diagrams are derived from the ESB Programmers Guide & I believe 3.1 is supposed to be a much generalized image. Guidance please.

* "3.2.4 The name for any given named object in a message must be unique or an exception will be thrown. - is it really true? How can this happen?"
Verify content in ESB Programmers Guide

* "3.2.5 Creating different body types - there is org.jboss.soa.esb.message.body.content.Payload class for this purpose
List of different message bodies - there are duplicate items"
Verify content in ESB Programmers Guide

* "4.1 Routers are in the section name but are not mentioned in the text - also need to explain difference between routers and notifiers Would be also good to mention that it is not necessary to provide the information to listener - the reference to provider for given transport is typically used
Update content in ESB Programmers Guide

* "5 This chapter should contain also Service orchestration section"
Update content in ESB Programmers Guide

* "page 73 - Note and page 34 - Note: The latter says that the gateway EPRs are not stored in registry and the former says they are"
Verify/update content in ESB Programmers Guide

* "Chapter 10 - the is new style functionality related to WS - EBWS (ESB services exposed as Web Services)"
Update content in ESB Programmers Guide

* "Appendix A - there is nothing in the text that justifies the inclusion of this Appendix - for what the JAXB is used in ESB context?"
Verify/update content in ESB Programmers Guide

Link: Added: This issue is a dependency of SOA-971

This is the same document as the ProgrammersGuide in the ESB project?

Its the 'productized' SOA version of it.  

There are some minor differences.  

These are the review comments for the Guide for the actual content from the ESB guide, ie its the same in both, and I need someone to verify either that it is correct or provide from info on what it should be.  Then I'll raise some JBESB JIRAS to update those items if necessary.

>These are the review comments for the Guide for the actual content from the ESB guide, ie its the same in both, and I need someone to verify either that it is correct or provide from info on what it >should be
Ok, I'll go through the ProgrammerGuide in the ESB project and take a look at the issues mentioned.
Do I need the SOA version of this document to find references to pages mentioned in this Jira?

Thanks

Yes, you can get it here: http://www.redhat.com/docs/en-US/JBoss_SOA_Platform/4.3.GA/pdf/Programmers_Guide/Programmers_Guide.pdf

Hey Darrin, 

I've looked through the issues here and compared them with the ESB projects documentation. I've added comments to each one below and this should hopefully be enough to create jiras for those issues that require a change to the ESB project docs. 

* "3.2 Figure 3.1 and Figure 3.2 - each describes the same but have different structure (missing pieces in the figures)"
>Diagrams are derived from the ESB Programmers Guide & I believe 3.1 is supposed to be a much generalized image. Guidance please.

This what Figure 3.1 looks like in the ESB Projects ProgrammersGuide:
<?xml version = "1.0" encoding = "UTF-8"?>
<jbossesb xmlns="http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd">

<services>
    <service category="Retail" name="ShoeStore" description="Acme Shoe Store Service">
        <actions>
            <action name="println" class="org.jboss.soa.esb.actions.SystemPrintln" />
        </actions>
     </service>
</services>

</jbossesb>

The "missing pieces would in this case be the provider configuration and the listener configurations, unless the invm transport is assumed. 
The two diagrams do not describe the same thing, unless I'm missing something. I don't think that action should be taken here.

* "3.2.4 The name for any given named object in a message must be unique or an exception will be thrown. - is it really true? How can this happen?"
No, this is not true (the report is correct that is). This is simply a Hashtable and adding a new named object will replace the old one.
This is also present in the ESB Programmers Guide on page 28 which needs to be updated

* "3.2.5 Creating different body types - there is org.jboss.soa.esb.message.body.content.Payload class for this purpose
>List of different message bodies - there are duplicate items"
There are no duplicates in the ESB projects programmers Guide. See page 24.

* "4.1 Routers are in the section name but are not mentioned in the text - also need to explain difference between routers and notifiers. 
>Would be also good to mention that it is not necessary to provide the information to listener - the reference to provider for given transport is typically used
Routers are not mentioned in the ESB Programmers Guide, not in this section. Update required.

* "5 This chapter should contain also Service orchestration section"
>Update content in ESB Programmers Guide
The "Service orchestration section" is located in the ESB projects document "ServicesGuide.pdf". It could be lifted into the SOA Platform document.

* "page 73 - Note and page 34 - Note: The latter says that the gateway EPRs are not stored in registry and the former says they are"
Page 41 of ESB ProgrammersGuide:
Note: It is possible that multiple EPRs may be present in the Registry with the same Service Name/Category and that some of these EPRs may not be ESB-aware, e.g., Gateways. 
If the ServiceInvoker receives ESB-unaware EPRs from the Registry then it will ignore them. You may see the warning: "Invalid EPR for service (probably ESB-unaware)".

Page 77 of ESB ProgrammersGuide:
Note: For each gateway listener defined in a service, an ESB aware listener (or "native") listener must also be defined as gateway listeners do not define bidirectional endpoints,
but rather "startpoints" into the ESB. From within the ESB you cannot send a message to a Gateway. 
Also, note that since a gateway is not an endpoint, it does not have an Endpoint Reference (EPR) persisted in the registry.

This will need to be updated.

* "Chapter 10 - the is new style functionality related to WS - EBWS (ESB services exposed as Web Services)"
This needs to be added to the ESB projecs ProgrammersGuide. This is no currently in the main trunk but will be shortly.

* "Appendix A - there is nothing in the text that justifies the inclusion of this Appendix - for what the JAXB is used in ESB context?"
The appendix is for "JAXB Introductions" (http://www.jboss.org/community/docs/DOC-10075) and not JAXB isself.

Link: Added: This issue is related to JBESB-2250

Hi Daniel, I've incorporated this feedback into the SOA 4.3.CP01 Programmers Guide.  I thought I'd put a comment on this JIRA a few days ago but I must have forgotten.
I'm fleshing a couple of the items out a little for the SOA guide and I raise a JIRA after CP01 is done to incorporate those changes into the ESB Guide.

As far as the WS-EBWS item... is there a JIRA for this?
"* "Chapter 10 - the is new style functionality related to WS - EBWS (ESB services exposed as Web Services)"
This needs to be added to the ESB projecs ProgrammersGuide. This is no currently in the main trunk but will be shortly. "

>As far as the WS-EBWS item... is there a JIRA for this? 
Service Contract Definition on page 34 describes this feature. Perhaps we should move this section though.

Where do you think it should belong?  Maybe we can just add a reference to it there?

Service definition moved to page 36.

Checked with Daniel and he's happy with the doc now.

Closing - any recent changes are tracked here:  SOA-1533