Bug 779633 (SOA-2003)

Duplicate text

Attachment: Added: Screenshot_duplicates.png

I have made all of the requested changes up to this point.  (The new table is in Section 11.5.1.)

Cheers.  

Attachment: Added: Screenshot.png

Additional comments:

--------------------------------------------

Note in section 4.1.3

In JBoss ESB 4.3.CP03 the name of the property used to enclose NotificationList
elements in the <action> target is not validated.

Is this^ new in 4.3 CP03?

--------------------------------------------

Section: 4.3.1. ServiceInvoker

This paragraph should be removed:

From a clients perspective, the Courier interface and its various implementations can be used to
interact with services. However, this is still a relatively low-level approach, requiring developer code
to contact the registry and deal with failures. Furthermore, since JBossESB has fail-over capabilities
for stateless services, this would again have to be managed by the application. See the Advanced
chapter for more details on fail-over.

--------------------------------------------

Chapter 6. Example

Comment: Better to call this section "An Example"

--------------------------------------------

7.2.5. Quartz Scheduler Property Configuration

I'm not sure if we support this - we removed it from the 5.0 book - will check with Kevin

--------------------------------------------

Duplicated sections:

11.5.3.2.1. Updated HTTP Connection Configuration.
This "Configurator" is always applied to HttpClient instances created by the
HttpClientFactory. To make the connection configurations in a different way, create a custom
configurator that can generate and attach a different HttpConnectionManager instance with its own
settings.

11.7.3.1. Updated HTTP Connection Configuration.
This "Configurator" is always applied to HttpClient instances created by the
HttpClientFactory. To make the connection configurations in a different way, create a custom
configurator that can generate and attach a different HttpConnectionManager instance with its own
settings.

Misc. screenshot comments

Attachment: Added: screenshot_comments.zip

------------------------

Proposed rewording:

7.1.1. Services, EPRs, listeners and actions

As we have discussed previously, within the jboss-esb.xml each service
element consists of one or more listeners and one or more
actions. Let's take a look at the JBossESBHelloworld example.  The
configuration fragment below is loosely based on the configuration of
the JBossESBHelloworld example. When the service initializes it
registers the category, name and description to the UDDI
registry. Also for each listener element it will register a
ServiceBinding to UDDI, in which it stores an EPR. In this case it
will register a JMSEPR for this service, as it is a jms-listener. The
jms specific like queue name etc are not shown, but appeared at the
top of the jboss-esb.xml where you can find the 'provider' section. In
the jms-listener we can simply reference the "quickstartEsbChannel" in
the busidref attribute.


7.1.1. Services, EPRs, listeners and actions

As we have discussed previously, within the jboss-esb.xml each service
element consists of one or more listeners and one or more actions. As
an example, the configuration fragment below is based on the
"helloworld" quickstart. When the service initializes it registers its
category, name and description to the UDDI registry. Also, for each
listener element, the service registers a ServiceBinding, in which it
stores an EPR, to the UDDI registry. In this case it will register a
JMSEPR for this service, as it is a jms-listener. The JMS specific
elements such as queue name, etc. are not shown here, but can be seen
"provider" section at the top of jboss-esb.xml. In the jms-listener we
can simply reference the "quickstartEsbChannel" in the busidref
attribute.

------------------------

7.1.5. Channel Fail-over and Load Balancing

We can even mix protocols in this setup, so we can also add and ftp-listener to
the mix.

"add an"

------------------------

7.2. Scheduling of Services

Proposed rewording:

2. Schedule Providers, which supply messages to action processing pipelines based on a schedule
   driven model i.e. where the underlying message delivery mechanism (e.g. the file system) offers
   no support for triggering the ESB when messages are available for processing, a scheduler
   periodically triggers the listener to check for new messages.

2. Schedule Providers, which supply messages to action processing pipelines based on a schedule
   driven model. For this provider type, the underlying message delivery mechanism (e.g., the file 
   system) does not offer support for triggering the ESB when messages are available for 
   processing. Instead, a scheduler periodically triggers the listener to check for new messages.

------------------------

7.2. Scheduling of Services

Scheduling is new to the JBoss ESB and not all of the listeners have been migrated over to this model
yet.

This line ^ should be removed.

------------------------

9.1. Overview

By far the easiest way to create configurations based on this model, is to use an XSD aware XML
Editor such as the XML Editor in JBoss Developer Studio. This provides the author with auto-
completion features when editing the configuration.

Comment: We should also refer to the JBDS ESB editor: http://www.redhat.com/docs/en-US/JBoss_Developer_Studio/3.0/html-single/ESB_Tools_Reference_Guide/index.html

------------------------

9.8. Configuration

Note
We recommend that you construct your ESB configuration file using Eclipse or some
other XML editor. The JBossESB configuration information is supported by an annotated
XSD which should help if using a basic editor.

Comment: Again, we should also refer to the JBDS ESB editor: http://www.redhat.com/docs/en-US/JBoss_Developer_Studio/3.0/html-single/ESB_Tools_Reference_Guide/index.html

------------------------

Appendix B. Service Orientated Architecture Overview

Replace references to JBossESB with "JBoss SOA Platform"

And - I think we ned to rework the last paragraph:

B.4. JBossESB and its Relationship with SOA

SOA is more than technology: it does not come in a shrink-wrapped box and requires changes to
the way in which people work and interact as much as assistance from underlying infrastructures,
such as JBossESB. With JBossESB 4.3 GA, Red Hat is providing a base SOA infrastructure upon
which SOA applications can be developed. With the 4.2.1 release, most of the necessary hooks for
SOA development are in place and Red Hat is working with its partners to ensure that their higher
level platforms leverage these hooks appropriately. However, the baseline platform (JBossESB) will
continue to evolve, with out-of-the-box improvements around tooling, runtime management, service
life-cycle etc. In JBossESB 4.3 GA, it may be necessary for developers to leverage these hooks
themselves, using low-level API and patterns.

Proposed rewording:

B.4. JBoss SOA Platform and its Relationship with SOA

SOA is more than technology: it does not come in a shrink-wrapped box and requires changes to
the way in which people work and interact as much as assistance from underlying infrastructures,
such as JBossESB. With the SOA Platform, Red Hat is providing a base SOA infrastructure upon
which SOA applications can be developed. The Platform will continue to evolve, 
with out-of-the-box improvements around tooling, runtime management, service life-cycle etc. 

Link: Added: This issue related SOA-2018

Len, as per our IRC discussion, I decided to backport some of the rewritten stuff from 5.0 just to eliminate the grammar issues.  I did this on a para-by-para basis (scalpel, not the axe!) so it should be okay.  As you read through the book, though, please check that I have not inadvertently added anything 5.0.GA specific.

Note, there are large sections of the book that I did not backport so there are probably still a lot of grammar issues in parts you have not yet read.


With regard to the above issues you have raised, they are all done. I have "commented out" the Quartz section so it can easily be reinstated if need be.  Thanks!

As per IRC discussion, you might want to have a quick second look at this after I did the backporting the grammar fixes.  The issues you highlighted above should all be fixed, too.

9.1. Overview
JBoss ESB 4.3.CP03 configuration is based on the jbossesb-1.2.0 XSD . This XSD is always the definitive reference for the Enterprise Service Bus configuration.

==============================

All references to the 1.2.0 XSD must be removed from the 4.3 programmers guide - the correct XSD version for 4.3 is 1.0.1

http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd

9.3. Services

Reference to XSD version 1.0 should be changed to 1.0.1

References - such as in 9.8 - to "eclipse" should be replaced with references to JBDS

We recommend that you construct your ESB configuration file using Eclipse or some
other XML editor. The JBossESB configuration information is supported by an annotated
XSD which should help if using a basic editor.

Made required changes.

Still some errors in the doc - all references to:

   http://anonsvn.labs.jboss.com/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd

Should be replaced with:

   http://anonsvn.jboss.org/repos/labs/labs/jbossesb/trunk/product/etc/schemas/xml/jbossesb-1.0.1.xsd 

I have updated schema URLs to the current correct location.

Final edits verified in the docs.