Bug 779133 (SOA-1531)

Attachment: Added: ESB_Administration_Guide.pdf

Section 1.1

Text:
   The link: http://wiki.jboss.org/wiki/ConfiguringMultipleJBossInstancesOnOneMachine

Comment:
   The link has been moved to:  http://www.jboss.org/community/wiki/ConfiguringMultipleJBossInstancesOnOnemachine

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

Figure 1.2. Clustering Scenario Two

Comment: I think we need to add some explanatory text to this figure. The difference between the 2 diagrams is that he ESB-aware gateways are either clustered, or duplicated. When would we recommend one configuration over the other? I'll try to get some details that we can add to the guide.

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

Section 1.3. JBossESB Java Message Service Providers

Text:
   Red Hat currently support the use of a number

Comment:
   "supports"

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

Text:
   How Can I Configure Them?
   You can configure JMSListeners and JMSGateways to listen to either "Queues" or "Topics" by
   setting the following parameters in the Service Configuration file:

Comment:
   We should explicitly refer to the "jboss-esb.xml Service Configuration file."

(FYI guys - see:  https://jira.jboss.org/jira/browse/SOA-534 - this is a confusing part of the book.)

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

Section: 1.3.1. JBoss Messaging

Text:
   One should set the parameters for JBoss Messaging to:
   jndi-URL="localhost"
   jndi-context-factory="org.jnp.interfaces.NamingContextFactory"
   connection-factory="ConnectionFactory"
   destination-type="queue"
   destination-name="queue/A"

Comment:

   We should replace the reference to "queue/A" with another queue name - maybe "queue/myqueue" - the "A," "B," "C," and "D" queues that we preconfigured in SOA-P 4.2 and 4.3 are not in 5.0.

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

Section: 1.3.2. Apache ActiveMQ

Text:
   Warning
   Apache ActiveMQ has not been fully tested & is not a supported JMS implementation.

Comment:
   If it's not supported then we should not document it. Can we remove this section?

Text:
In your classpath you should have:
• activemq-core-4.x
• backport-util-concurrent-2.1.jar
Both of these JARs can be found in the lib/ext/jms/activemq file.

Comment:
   We don't ship these files as part of SOA-P.

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

Section: 1.3.7. Oracle Advanced Queuing (AQ)

Text:
  Oracle AQ has not been fully tested and it is not a supported JMS implementation.

Comment:
   If it's not supported then we should not document it. Can we remove this section?

Text:
   An example jboss-esb.xml configuration file that one may find useful can be found in the
   samples/quickstarts/helloworld_action/oracle-aq directory.

Comment:
   We don't ship this quickstart with SOA-P.

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

Section: 1.3.11. Updated Database Configuration

Comment:

   The updated ant output is listed below - the list of supported database as described in the document should match this output:


[ldimaggi@ldimaggi schema]$ ant
Buildfile: build.xml

check.profile:
     [echo] JBoss SOA Platform Database Configuration Script
     [echo] ------------------------------------------------
     [echo]  
     [echo] This script is used to configure the SOA platform and all its
     [echo] constituent components against a new RDBMS.  Deployment scripts
     [echo] are currently available for the following databases:
     [echo]   DB2, MSSQL, MySQL, Oracle, PostgreSQL
     [echo] 
     [echo] ** Warning **
     [echo]   This script may not work correctly if you have made manual
     [echo]   changes to the database configuration.
     [echo] 

ask.profile:
    [input] Which server configuration are you changing? (production, all, ...): [default]


exists.profile:
     [echo] Using directory /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default

check.clustered:

check.backup:

do.backup:
     [echo] Backing up files ...
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy/jbossesb-registry.sar/META-INF
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy/jbossesb-registry.sar
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy/jbossesb.esb
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy/jbpm.esb
     [copy] Copying 1 file to /jboss/local/50_ER4/jboss-soa-p.5.0.0/jboss-as/server/default/deploy/jbpm.esb

execute:
     [echo] Databases configured by this script are:
     [echo]   DB2 9.7, MS SQL 2005, MySQL 5.1, Oracle 10g, PostgresSQL 8.3.7
     [echo] Please enter the database you wish to configure:
    [input]   [db2-97, mssql2005, mysql51, oracle10g, postgresql837]:

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

Chapter 3: Configuring Web Service Integration

Comment:
   We should add a brief description of the new SOAPProxy action to this chapter. Maybe the first paragraph from here:   http://www.jboss.org/jbossesb/docs/4.7/javadoc/esb/org/jboss/soa/esb/actions/soap/proxy/SOAPProxy.html

   Or a summary of:  http://jbossesb.blogspot.com/2009/11/proxying-soap-web-services-in-jbossesb.html

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

Section: 6.1. Updated Monitoring and Management in the SOA-P

Comment:
   We should remove the references to "JBoss Enterprise Service Bus Release 4.2.0.GA" and "JBoss Enterprise Service Bus Release 4.6" form the first paragraph. 

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

Figure 6.1. JBoss Administration Console

Comment: We'll need all new screenshots for the 5.0 guide as the consoles' appearance is changed relative to 4.3.

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

Section: 6.3. JON for SOA

Comment:
   We added byte counts on services, and the message alerts (which are only available if you enable them).

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

Section: 8.1. The "Contract" Application
                                                           
Text:
   For this purpose, Red Hat bundle the Contract Application 

Comment:
   "bundles"

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

Section: 8.2. Publishing a Contract from an Action


8.2. Publishing a Contract from an Action

This link: 
http://jboss.org/repos/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/SOAPProcessor.java

Is no longer valid - I found the source code here:

http://anonsvn.jboss.org/repos/labs/labs/jbossesb/branches/JBESB_4_7_CP/product/services/soap/src/main/java/org/jboss/soa/esb/actions/soap/SOAPProcessor.java

But - I'm not sure that this (JBESB_4_7_CP) is the correct tag. Will try to get you a better answer.

Same problem on this link:

http://anonsvn.jboss.org/repos/labs/jbossesb/trunk/product/services/soap/src/main/java/org/jboss/soa/esb/
actions/soap/JBossWSWebserviceContractPublisher.java

One more comment - the reference to:
   SOA-1310 - Added Performance Tuning Chapter. Chapter 10

SOA-1310 does not refer to performance documentation - it's one of the JIRAs related to optimistic locking and jBPM.

Completed, barring confirmation of URLs for section 8.2 as outlined above.  Please confirm these.

Chapter 10 Performance tuning should be updated according to information provided in https://docspace.corp.redhat.com/clearspace/docs/DOC-20069

The original source of information seems not to be updated.

Suggested fixes:
1) Keep section 10.1 as is
2) Keep section 10.2 as is
3) Rename and update section 10.3 according to section "Transport threads" in DOC-20069
4) Remove section 10.4 - JBR is deprecated
5) Keep section 10.5 as is
6) Add all missing sections from DOC-20069

It would be great if DOC-20069 could be automatically checked for updates with future Admin. Guide releases.

SOA-1310 should be SOA-1032, and it shouldn't be in the revision history for this version of the document either ;-) FIXED.

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

Assigning back to David - the book is not here:  http://documentation-stage.bne.redhat.com/docs/en-US/index.html

I have undertaken these changes.

We believe we have fixed the Doc Stage issue so this has just been sent to the server.  It should be available in a few hours.

Hey David,
 some comments:

section 6.1
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5.0.0/html/ESB_Administration_Guide/monitoring_and_management.html

Figures 6.1, 6.2 and 6.3
1. could be a little bit bigger
2. refer to AS 4


6.1.1.  Services
Each ESB service is displayed along with the processing time per action, processed count per action, failed count per action and overall message count (per service), as can be witnessed in the following screen-shot:
1. the following screenshot is not aligned with the text above
2. There are no metrics like "processing time per action, processed count per action, failed count per action".


The Message Counter keeps track of the number of both successful and failed messages, along with their processing times and the dates.
"processing times" should be "processed bytes"


Figure 6.3. MBean Counter
Maybe "Message Counter" would be better?


6.1.3.  Smooks Transformations
There is an MBean that keeps track of the count of "processed" Smooks Transformations and the time taken to process each. It also keeps track of the overall count of the Transformation Chain. 
Could this be explained in more detail? Where to find that MBean?


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

section 6.2 Alerts
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5.0.0/html/ESB_Administration_Guide/alerts.html

Chapter is based up on web-console which is no longer shipped AFAICT - but this needs to be clarified.

Maybe this or "6.3.1. Message Alerts" would be a good place to document SOA-1656. 



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

http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5.0.0/html/ESB_Administration_Guide/JON_for_SOA.html
section 6.3

in the eponymously-named quick start, "messagealert."
1. dot should be after "
2. the QS name is plural, messagealerts


As one can deduce from this screenshot, the counters can be reset through the JMX console:
1. The screnshot is too small to be able to deduce it
2. It's not the *counter* that can be *reset* but *alerts* that can be *cleared*


Figure 6.4. Clustering Scenario One
wrong title


Sample code of MyJMSListenerAction.java not properly formatted at the end and following imported classes are never used:
javax.management.MalformedObjectNameException
org.jboss.mx.util.MBeanProxyExt
org.jboss.soa.esb.actions.AbstractActionPipelineProcessor
org.jboss.soa.esb.actions.ActionProcessingException

I think, here would be a good place to document SOA-1660


Adding your JBoss SOA Platform Server to the JON Inventory
missing numbering (6.2)


Conveniently, the error message also contains a short-cut link to the "Connection Properties" page.
Looks like there is no error message anymore, but the SOA-P is marked as DOWN (see down.png attached)


Figure 6.5 is refferring to SOA-P 4.3 instead of 5.0


JBoss SOA-P Enterprise Service Bus Statistics 
missing numbering (6.3)


Once one's JBoss SOA-P server is correctly configured for the JBoss Operations Network tool, one should find the item JBoss ESB Statistics now available underneath the menu entry in Resources on the MONITOR tab.
"available underneath the menu entry in Resources" - not sure this is true, attaching screen "underneath.png" for clarification.. I *think* this should read "available above the Resource menu entry"


The metrics collected and displayed vary, depending on the Enterprise Service Bus component in question. The available metrics include:
this needs to be revisited, I can help with this setting up the environment, just ping me; attaching screens, might be helpful (count1.png - count7.png)



Figure 6.6. Metrics Displayed 
1. Displayed should not start with a capital D
2. figure could be bigger


Managing deployed ESB archives 
missing numbering (6.4)


A new Enterprise Service Bus archive can be deployed by selecting JBoss ESB Deployment from the Create New menu. Then, from the Create New Resource page, specify which archive to deploy, to where it should be sent (which, under normal circumstance, would be one's deploy directory) and, finally, whether it should be sent as a compressed or extracted archive.
"whether it should be sent as a compressed or extracted archive" - you can only upload *zipped* archives (files, not directories) - the "Deploy Zipped" option tells whether it should be *deployed* as an zipped or exploded archive.


Automatic Service Discovery 
missing numbering (6.5)

Attachment: Added: underneath.png
Attachment: Added: down.png

Attachment: Added: count1.png
Attachment: Added: count2.png
Attachment: Added: count3.png

Attachment: Added: count4.png
Attachment: Added: count5.png
Attachment: Added: count6.png

Attachment: Added: count7.png

I have addressed most of the issues raised by yourself and Jaroslaw above.


Here are  a few that I have not done, with my comments in CAPITALS:


6.1.3. Smooks Transformations 
There is an MBean that keeps track of the count of "processed" Smooks Transformations and the time taken to process each. It also keeps track of the overall count of the Transformation Chain. 
Could this be explained in more detail? Where to find that MBean? 

NEED INFORMATION FROM SUBJECT MATTER EXPERT



The metrics collected and displayed vary, depending on the Enterprise Service Bus component in question. The available metrics include: 
this needs to be revisited, I can help with this setting up the environment, just ping me; attaching screens, might be helpful (count1.png - count7.png) 
NOT QUITE SURE WHAT THE ISSUE IS THAT JAROSLAW IS TRYING TO RAISE.  ARE THE METRICS OUT OF DATE OR INACCURATE?



Maybe this or "6.3.1. Message Alerts" would be a good place to document SOA-1656. 
SOA 1656 IS ASSIGNED TO DARRIN BUT I WILL LIAISE WITH HIM ABOUT THIS.

Also, "Chapter [Alerts] is based up on web-console which is no longer shipped AFAICT - but this needs to be clarified. "

NEED INFORMATION FROM SUBJECT MATTER EXPERT.  I HAVE COMMENTED THIS SECTION OUT BUT CAN REINSTATE IT PENDING ADVICE.

re: web-console, see SOA-1823 for details

David:

1) I can't find "web-console" in the current draft of the book. Yes, the web-console is deprecated. The bits are still shipped, but customers should use the new admin console instead. The old web-console can no longer be reached from the console UI.

2) Message alerts:  Text contributed by Tom Cunningham in SOA-1656:  The JON integration for message alerts collects the alerts and displays them as JON events, or if the administrator wishes to do so, as JON alerts that are fired triggered by the message alert JON event. Both the message's size and the processing time are available within that context.

3) 6.1.3. Smooks Transformations - I cannot find any such MBean - will check:

"...There is an MBean that keeps track of the count of "processed" Smooks Transformations and the time taken to process each. It also keeps track of the overall count of the Transformation Chain..."

4) New issue - all the admin console screen-shots are of Jopr consoles, not the SOA-P branded console. See attached screenshots.

Will review the rest of the book today.

Note sent to Tom Fennelly:

Smooks question for you on the ESB/SOA-P Admin Guide. Section 6.1.3 refers to:

6.1.3. Smooks Transformations

"...There is an MBean that keeps track of the count of "processed" Smooks Transformations and the time taken to process each. It also keeps track of the overall count of the Transformation Chain..."

But, this is the only smooks MBean that I can find - but - it does not keep track of the transformations:
     http://localhost:8080/jmx-console/HtmlAdaptor?action=inspectMBean&name=jboss.esb%3Adeployment%3Dsmooks.esb

Does this MBean still exist?

Just found this  http://jboss.org/jbossesb/docs/4.6/javadoc/esb/org/jboss/soa/esb/actions/converters/SmooksMessageCounter.html

But - it's not in the JMX console.

Screenshots

Attachment: Added: admin_guide.png
Attachment: Added: ER7.png

Went through the code, and although this bean exists, I cannot find it being registered anywhere.        We should probably remove the references to it for now.

Please remove the references to the smooks MBean:


<ldimaggi_> tcunning, will try a smooks sample
<tcunning> just tried one
<tcunning> it looks to me like that bean is never registered
<tcunning> so i think you're okay removing the section i added
<ldimaggi_> tcunning, Was it ever registered?   I'm guessing no - thanks!

Final comments on this version of the guide:

Section: 1.4. JBossESB Java Message Service Providers

Text:
Important
In the sections that follow, these assumptions are made:
• your JMS provider runs on 'localhost'
• the connection factory is called 'ConnectionFactory'
• the destination-type is a 'queue'
• the destination-name is 'queue/A'

Comment: We changed the examples to not all use queue/A, remember? This line should be removed.

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

1.4.1. JBoss Messaging

Text:
Instructions for installing JBoss Messaging can be found on the project website:
http://labs.jboss.com/jbossmessaging/docs/userguide-1.4.0.GA/html/installation.html

Comment:

We should remove the reference to installing JBoss messaging. SOA-P customer will already have it installed.

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

Section: 1.4.6. Tibco Enterprise Message Service (EMS)

Text:
One should set the parameters for the Tibco Enterprise Message Service to the following:
jndi-URL="tcp://localhost:7222"
jndi-context-factory="com.tibco.tibjms.naming.TibjmsInitialContextFactory"
connection-factory="QueueConnectionFactory"
destination-type="queue"
destination-name="<queue-name>"

Comment: We should name the queue "myqueue" to be consistent with the JBoss messaging example.

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

Section: 1.4.9. Updated Database Configuration

Text (in the note):
As long as there is script availabe for one's database, the Enterprise Service Bus will
auto-create the schemas on startup. (By default, the JBoss Enterprise Service Bus is
configured to use a JEE data source.)

Comment:
"availabe"

Comment:

The ant output references the ER4 build - should be GA.

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

Section: 1.4.10. Switching Databases

Comment: The example refers to a version of Postgres (7.2) that we do not support.
---------------------------------

Section: 1.4.11. Using a JSR-170 Message Store

Text: 
The Java Content Repository implementation included is called Apache Jackrabbit. To enable the
Java Content Repository's message store, add the following property to the "core" section of the
jbossesb-properties.xml file, (which can be found in the root of the jboss-esb.sar or the root
of deployers/esb.deployer on AS5):

Comment:

On a SOA-P server, the file is found in: ./deployers/esb.deployer/jbossesb-properties.xml

Also - we should remove the reference to AS5.

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

Section:  1.4.13. Clustering and Fail-Over Support

Text:  

Because the ServiceInvoker hides much of the fail-over complexity from users, it only works with
"native" SOA Platform messages. Furthermore, not all gateways have been modified to use the
ServiceInvoker, so incoming messages that are unaware of the SOA Platform may not always be
able to take advantage of service fail-over. The Release Notes document contains more details
related to this topic.

Comment: Is this still described in the rel notes?

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

I have made all of the changes requested above, including changing the images to those supplied by Len (replacing the Embedded JOPR ones.)  I removed that refence to the Release Notes as it appeared to be out of date - there is no reference to it in the new release notes.  

References to that MBean and to AS5 have been removed, file path updates, code sample altered to refelct suport version of Postgres and so forth.

It should be noted that although JON can run under JDK 1.5 and 1.6, the ESB plugin will only work with 1.6. We have tested on both, Sun and OpenJDK, however AFAICT JON is not officially supported on OpenJDK 1.6.

http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5.0.0/html/ESB_Administration_Guide/JON_for_SOA.html
6.2.  JON for SOA 

Maybe after this section?

"JON for SOA" is a stand-alone release of JON that includes functionality that has been specifically designed for the JBoss SOA-P. This section provides an overview of that functionality and assumes a basic knowledge of the JBoss Operations Network product on behalf of the readership.

The ESB plugin can be compiled with either 1.5 or 1.6, but I believe the current SOA build only uses 1.6.

Done.



NOTE:  We are not accepting any further QE feedback, unless they are mission-critical issues that would result in data loss.  We are closing this stage of the process for this release.  Thanks.