Bug 780667 (SOA-3107)

Reminder that Documentation Stage has now been moved to this server:  

http://documentation-stage-01.lab.eng.bne.redhat.com/

Parent: Added: SOA-3147

The very first chapter I have found that there are references that jbossesb-listener.xml and jbossesb-gateway.xml should be used to configure JMS providers. I believe that those files are already obsolete. There are  number of old issues related to this in JIRA (JBESB-1697, SOA-534, JBESB-2322, JBESB-1155) that were resolved/closed.

Also the JBossESB's documentation between versions 4.6-4.9 didn't include reference to jbossesb-listener.xml but 4.10  documentation mentions it again. So I think there is no point in reviewing administration guide until relevant version of documentation is built.

There is no reference to jbossesb-listener.xml in the JBoss ESB project 4.8 Admin doc:
   http://docs.jboss.org/jbossesb/docs/4.8/manuals/html/AdministrationGuide.html

But it's here in 4.10:
   http://docs.jboss.org/jbossesb/docs/4.10/manuals/html/Administration_Guide/index.html

So - when the Platform pulled in the project docs - we got the references to jbossesb-listener.xml.

===========

The jbossesb-listener.xml and jbossesb-gateway.xml files were replaced by jboss-esb.xml many releases ago.

Link: Added: This issue relates to SOA-3271

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

Link: Added: This issue relates to JBESB-3665

h1. Review of admin guide
The guide is relatively OK. Rest of this comment contains things I am not sure about.

h2. Problematic points
Invalid path
  [where] Chapter 1 Configuration
  [now] SOA_ROOT/server/CONFIG/deployers/esb.deployers/jbossesb-properties.xml
  [suggestion] SOA_ROOT/server/CONFIG/deployers/esb.deployer/jbossesb-properties.xml

Incomplete information
  [where] Chapter 1.3.1 Configuring a Java Message Service Provider
  [now] Docs suggest user should set destination-type, destination-name in jboss-esb.xml
  [note] After brief tryouts I wasn't able to find out how these two parameters should be set. I am used to the fact that when I want to set destination for JMS provider i will just use jms-message-filter element and dest-type/dest-name attributes. 
  However usage of destination-type and destination-name is not even in any quickstart that would help and neither is there any reference of these two parameters in XSD schema (they are probably set somewhere via string property of some xml element). As it is there is no way to easily follow what docs want to say for somebody who didn't use these params before.
  [suggest] Add these configuration into some hello world Quickstart with configuration pointing to implicit JBoss Messaging and reference this quickstart in docs. Also explain why there is need for these params when user can achieve this via dest-type/dest-name under jms-bus element.

Maybe not complete information
  [where] 1.3.17.2. Message Tracing
  [now] By default, every interaction between components and messages is logged.
  [note] I am using 5.0.2.ER3 build and by default (with log4j config set to INFO) I dont see any of these audit logs when running quickstarts.
  [suggest] please supply more information what should be done to se these logging messages

Incomplete information
  [where] Chapter 1.3.17.2 Message tracing
  [now] The TraceFilter will only log information if you set the org.jboss.soa.esb.messagetrace
  [note] Where should this property be set?
  
Broken links
  [where] 1.3.17.5. Installing and...; Procedure 1.2.  Deploying the OpenSSO to Tomcat, step 4
  [now] broken links:
     http://java.net/projects/opensso/public/use/docs/fampdf/index.html
     https://opensso.dev.java.net/public/use/index.html
   Because of this i couldn't review rest of the chapter 1

Cubersome language
  [where] Chapter 2 The Registry
  [now] when services run, they usually add an end-point reference to the registry. It is through this that they are contacted. If services have been programmed well, they automatically remove these end-point references when they terminate. However, if they are poorly programmed or crash, theese entries will remain there. These "orphan" entries will prevent subsequent deployments from executing correctly, so remove them manually. 
  [suggest] After service starts up, it usually adds an end-point reference (EPR) to the registry. EPR can be further used to contact the service. 
  \par
  Well programmed service removes its corresponding EPR upon termination. However poorly programmed service can leave EPR in the case of service crash, this kind of EPR is reffered to as "orphan entry". Because orphan entry will prevent subsequent redeployments of the service it must be removed manually.

Typo
  [where] Chapter 4 Default
  [now] word "prefixed" is used instaned of "suffixed" 

Incomplete information
  [where] 6.1 The Monitoring and ...
  [now] For instance, it displays message counts by service, action, and node. It also displays such useful information as: processing times,....
  [note] Where are those information in the console located?

Simplistic information about hotdeploy
  [where] Chapter 7. Hot Deployment
  [now] Very limited information about Hot deployment is explained in suprisingly long paragraphs.
  [suggest] Add information about hdscanner-jboss-beans.xml and limitations of Hot Deploy 

Cubersome language
  [where] 11.2.  Message Store Interface 
  [now]     can ignore this field if need be. 
  [suggest] can ignore this field if needed.

Missing security settings
  [where]   Table 12.1. jbossesb-properties.xml Security Settings
  [now]     table is missing <property name="org.jboss.soa.esb.services.security.publicKeyTransformation"  ...
  [suggest] add it

Typo
  [where]   12.1.1.  Configuring Security on Services  
  [now]     ... Her is a code ...
  [suggest] ... Here is a code...


h2. Minor comments
Confusing
  [where] Preface 1.1
  Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:
      Press Enter to execute the command.
      Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session. 
  [note] + is not a hyphen

Using different names for same concept
  [where] Chapter 1 configuration
    JBoss SOA Platform Enterprise Service Bus 
    JBoss Enterprise SOA Platform

Imprecise vocabulary and poor choice of words
  [where] 1.3
  [now] You can choose from between a number of Java Message Service applications
  [suggest] You can choose from number of JMS (Java Message Service) implementations 

Violation of conventions
  [where] 1.3, Important box
  [note] bold JSR-914 - which is not an application

Violation of conventions
  [where] 1.3.1, Important box
  [note] bold JMS Listeners, JMS Gateways - neither of which is an application

Imprecise info
  [where] 1.3.17.2 Message Tracing
  [now] To set this filter modify the properties in the Filter section of the JBossESB configuration file
  [note] this is confusing
  [suggest] To set this filter modify the properties under <properties name="filters"> element in jbossesb-properties.xml file.

Weird english
  [where] 1.3.17.2 Message Tracing
  [now] Note that this filter does not effect the input or output message
  [suggest] Note that this filter does not modify the input or output message


Incomplete information
  [where] 1.3.17.2 Message Tracing
  [now] MessageID field. You can read more about this in the Programmers' Guide.)
  [note] Where exactly? What should I learn from the Programmers guide?

Confusing information
  [where] 9.2.  JBPM Messaging and Scheduling Services 
  [now] By default, the JBoss Enterprise SOA Platform is configured to use the JMS/JCA-Inflow: 
  [note] I don't really get this one. After the semicolon there is a example of configured message and scheduler services (which is understandable because of the title) but why the first sentence ([now]) talks about JCA-Inflow?

Closing - QE doc reviews are complete.