Bug 780675 (SOA-3117)

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

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

Parent: Added: SOA-3147

h1. Review of EDS admin guide

State of the Guide is disappointing. Problems: 
  * Obsolete content
  * Lot of typos
  * Inconsistent terminology
  * Incomplete examples without references on appropriate quickstarts (although they exist). This leads to low information value from reading the documentation

h2.Problematic parts of the guide
Following things I consider particulary bad: 

Inconsistent/wrong description of Administration console
  [where] Chapter 1, (especially 1.1.2 Metrics)
  [now] In documentation there is a list of metrics that can be "viewed" 
  [notes] 
    - The list contains actions: Terminate Session, Terminate Requests, Terminate Transaction. These actions 
       are not present on Metrics tab and are now on "Control" tab in actual Console. Next problem with these actions is that they are not "viewable" it seems that they were put to this chapter (1.1.2) by mistake or the heading "Control" is just missing (Control).
    - In my opinion this documentation is somehow very obsolete because not all actions available in console are listed here and Control tab is missing description in documentation.

Typography
  [where] 2.1 Getting started (Note box)
  [now] use theadminHelp()
  [suggest] use the adminHelp()

Wrong method name
  [where] 2.3  The Log and Recorded Script Files
  [now]    connectionAsAdmin()
  [suggest] connectAsAdmin()

Bad english
  [where] 3  Deploying Virtual Databases
  [now]     A VDB is the primary means to define a virtual database
  [note] "VDB are" or "VDB is primary mean". Although I don't know what is meant by VDB. I thought VDB is "virutal database" in which case the sentence wouldn't make sense.

Typo
  [where] 3.2. Deploying VDB Dependencies, second paragraph
  [now] TO give

Typo
  [where] 3.2. Deploying VDB Dependencies, last paragraph
  [now] Once you have deplored ...

Invalid path
  [where] Example 3.4 WS-Security
  [now]       ${jboss.server.home.dir}/server/default/conf/xxx-jbossws-cxf.xml
  [suggest]   ${jboss.server.home.dir}/conf/xxx-jbossws-cxf.xml

Type in example
  [where] Example 3.4 WS-Security
  [now] missing ending tag for <map>

Incomplete or wrong information
  [where] 3.2.3.3 Logging 
  [now]    Logging, when enabled, will be performed at an INFO level to the org.apache.cxf.interceptor context
  [info]   As I understood this sentence, after turing this feature ON, in my server log I should have logged requests and responses under mentioned logger. I made sure to have correctly configured log4j in my SOA platform and although I see logged request and response (encrypted) I don't see it coming out from org.apache.cxf.interceptor logger.
  [suggest] Add more information to this paragraph about where user can expect the output of such logger and add INFO box that he should have logging set up accordingly (as default settings of SOA P won't allow him to see the INFO outputs)

Typo causing non-deployable DS
  [where] Example 3.6. Example Disabling Host-name Verification
  [now]     ...rs disableCNcheck="true" /> 
  [suggest] ...rs disableCNCheck="true"/> 
  [note] When you supply examples, please validate at least against available xml schemas...

Wrong chapter numbering
  [where] 3.2.5 CXF Configuration
  [now]     3.2.5 
  [suggest] 3.2.4.1 or consolidate the paragraph with 3.4.2 
  [note] It seems that CXF configuration is logically connected to 3.2.4 because notes about salesforce is there. Therefore it certainly shouldn't be numbered as 3.2.5

Confusing and duplicit information
  [where] 3.2.4, 3.2.5
  [now]   Information about how to configure salesforce connector with CXF configuration
  [note]  The information is duplicit and is essentially copy-paste of 3.2.3.1. The documentation is confusing mainly becase of ambiguous titles of headings
  [suggest] Delete 3.2.5 and just refer to the fact that teiid-connector-salesforce.rar uses same configuration as CXF web services for Bus configuration. Also remove second Note box for "bus info".


Cubersome language
  [where] 3.3
  [now]   If a specific version is set, then you can only connect to that VDB. If no version is set, the deployed VDBs are searched until the appropriate version is found. This feature helps support more fluid migration scenarios. 
  [suggest] Specifying version is optional. If the version is not specified then deployer will decide which version of the VDB should be used. This helps...

Not following conventions
  [where] 3.3 VDB Versioning
  [now] ... the deployment file (such as vdbname.version.vdb or marketdata.2.vdb...
  [suggest] use italic for "vdbname.version". Also restructure to something like: "... the deployment file such as vdbname.version.vdb, e.g. marketdata.2.vdb
  
Typo
  [where] 4.4.2.2  Role Based Credential Map
  [now] ... , this module will hold credentail to that role ...
  
Wrong filename, bad formatting
  [where]  4.4.2.1. CallerIdentity and Trusted Payload
  [now] Here is a sample configuration, this needs to be configured in "teiid-jboss-beans.xml" file. 
  [note] File listing is in fact snippet from totally different file (login-config.xml). On top of that file names should be typeset in Bold not in quotes.

Unclear usage of role based credential map
  [where]  4.4.2.2. Role Based Credential Map 
  [now]    no example of credential map is given
  [note]   From the text it is not clear that credential map is in format <role>=<credential>

Cubersome text
  [where]  4.4.2.2. Role Based Credential Map 
  [now]    quotes are used to emphasize "credentialMap", "UsersRolesLoginModule","managedConnectionFactoryName". RoleBasedCredentialMapIdentityLoginModule is refered to as "RoleBasedCredentialMap" login module.
  [note]   UsersRolesLoginModule is spelled out correctly but RoleBasedCredentialMap is spelled out differently than it actually is. Whole paragraph seems very cubersome and suprisingly long for low amount of information given. 
  [suggest] Rewrite whole paragraph. 
  
Not working security settings
  [where]  4.4.2.2. Role Based Credential Map
  [now] At the end of the section there is a method to use encrypted passwords in credential map.
  [note] I wasn't able to reproduce this functionality. To try the functionality I used eds_multi_source_federation quickstart. Below are settings I used before password encryption (which worked perfectly). Non-functionning encrypted version follows.
  [suggest] Investigate whether outlined procedure is still valid.

  [before-encryption]
      login-config.xml
        <application-policy xmlns="urn:jboss:security-beans:1.0" name="teiid-security">
            <authentication>
               <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
                  <module-option name="usersProperties">props/teiid-security-users.properties</module-option>
                  <module-option name="rolesProperties">props/teiid-security-roles.properties</module-option>
               </login-module>
               <login-module 
                  code="org.teiid.jboss.RoleBasedCredentialMapIdentityLoginModule" 
                  flag="required">
                  <module-option name="password-stacking">useFirstPass</module-option>
                  <module-option name="credentialMap">
                      props/teiid-credentialmap.properties
                  </module-option>
                  <module-option name="managedConnectionFactoryName">
                      jboss.jca:service=LocalTxCM,name=MySQLDB
                  </module-option>
               </login-module>            
            </authentication>
         </application-policy>
      props/teiid-credentialmap.properties
        sa=

      After deploying/running the quickstart everything went fine.

 [encryption]
    From directory 
      <SOAP>/jboss-as/lib
    I encrypted empty string (which is the password for "sa") as follows
        java -cp jbosssx.jar:jboss-logging-spi.jar org.jboss.security.plugins.PBEUtils 12345678 10 piiibpass ''
    Encoded password: D8cSQ8OvwNz

    So I modified files as indicated in documentation:

    login-config.xml
       <application-policy xmlns="urn:jboss:security-beans:1.0" name="teiid-security">
          <authentication>
             <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
                <module-option name="usersProperties">props/teiid-security-users.properties</module-option>
                <module-option name="rolesProperties">props/teiid-security-roles.properties</module-option>
             </login-module>
             <login-module 
                code="org.teiid.jboss.RoleBasedCredentialMapIdentityLoginModule" 
                flag="required">
                <module-option name="password-stacking">useFirstPass</module-option>
                <module-option name="credentialMap">
                    props/teiid-credentialmap.properties
                </module-option>
                <module-option name="managedConnectionFactoryName">
                    jboss.jca:service=LocalTxCM,name=MySQLDB
                </module-option>
                
                <module-option name = "pbealgo">PBEWithMD5AndDES</module-option>
                <module-option name = "pbepass">piiibpass</module-option>
                <module-option name = "salt">12345678</module-option>
                <module-option name = "iterationCount">10</module-option>
            </login-module>            
          </authentication>
       </application-policy>

    props/teiid-credentialmap.properties
      sa=D8cSQ8OvwNz

    After restarting SOA-P and redeploying/running quickstart I get:
    On Client: Caused by: java.sql.SQLException: Remote java.sql.SQLException: Access is denied

Confusing terminology
    [where]  Chapter 5. Logging
    [now]    Log4J loggers are referred to as "context" and mentions of DETAIL logging level are used.
    [suggest] context -> logger
              DETAIL  -> INFO
               
Nonexistent config key
    [where]  7.* Memory Management
    [now]    BufferManager properly is one of the most important parts of ensuring high performance
    [note]   Because BufferManager is so important it is very disappointing that no such configuration value exists in teiid-jboss-beans.xml
    [suggest] BufferManager -> BufferService

              
Product/project naming mismatch
    [where]  7.1 Memory Management 
    [now]    ... being read through Teiid, but does introduce ...
    [suggest]  Teiid -> Data Services

Typography
    [where]  7.5,7.6
    [now]    ... the "lobChunkSizeInKB" property ... ; maxSourceRows ; exceptionOnMaxSourceRows
    [suggest] Don't use quotes, use bold.

Nonexistent jars and ambiguous paths
    [where]  Other Scripting Environments
    [now]    You will also need to ensure that the lib/teiid-client.jar and lib/teiid-adminshell-7.1.1.jar are in your class path. 
    [note] From which 'lib' directory these jars should be imported? teiid-client.jar is present in many directories. On the other hand it is not possible to 'ensure ... adminshell ... ON your classpath' because in SOA-P no file with name pattern '*adminshell-*.jar' exists.
  

h2. Minor comments
I consider following problems minor, because those are my personal opinions which are non-critical to readers or I have low confidence whether they are actual problems. 

Typo 
  [where] Chapter 1 Monitoring Data Services 
  [typo] no dot at the end of the paragraph

Inconsistency 
  [where] 1.1 What can be monitored.... 
  [now] a. Source - these are physical sources 
  [suggest] In admin console those are named "Single Source Models"

Inconsistency
  [where] 1.1.1 Configuration 
  [suggest] Items in list are named a little differently than those in admin console (no dashes, CAPS)

Location of adminshell, adminshell-console 
  [where] 2.1 Getting started 
  [suggest] Add location of adminshell (<SOAP root>/eds/teiid/adminshell)

Method connectAsAdmin with 3 parameters doesn't exist
  [where] 2.1 Getting started
  [now] Throughout the code examples non-existent method is used

Confusing method names in adminshell
  [where] 2.3  The Log and Recorded Script Files
  [now]   by using startRecording and stopRecording: 
  [note] code sample shows different commands: "record start", "record stop"

Inconsistent terminology
  [where] 3.1.3 AdminShell Deployment
  [now]  The advantage of this approach is that you can automate artifact deployment.
  [note] Throughout the guide the term "artifact" is not used and doesn't really fit this usage.
  [suggest] ... you can automate VDB deployment.

Cubersome sentence structures
  [where] 3.1.4
  [now] The Admin API provides Java API methods that allow you to connect to a Data Services run-time and deploy a VDB. If you need to deploy a VDB programmatically, use this method. 
  [note] It seems that both sentences speak of 1 concept (deploying VDB programmatically at run-time). 
  [suggest] Delete one of the sentences.

Nonconformity with document conventions
  [where] spotted in 3.2.1, 3.2.2
  [now] <PROFILE> {jboss-as}
  [note] variable text parts should be typeset with Mono-spaced Bold Italic or Proportional Bold Italic

Incomplete examples
  [where] Example 3.4. Example WS-Security enabled data source
  [now] Example represents valid values but is not usable without further elaboration
  [suggest] Extend the examples to be more functional or point to quickstarts

Cubersome naming
  [now] Example 3.5. Example logging data source 
  [suggest] Example 3.5 CXF web services logging

Not standard terminology
  [where] 3.2.3.3 Logging
  [now] Logging, when enabled, will be performed at an INFO level to the org.apache.cxf.interceptor context: 
  [suggest] ... INFO level to the org.apache.cxf.interceptor logger:
 
Low priority information provided first
  [where] 4.1. Authentication
  [now] Documentation states that name may be considered optional
  [note] Could the documentation be a litte more specific? I tried omitting username in EDS quickstarts and the login modules that is used in it (org.jboss.security.auth.spi.UsersRolesLoginModule) seems to lack this functionality. Also in my opinion this information is of very low priority.
  [suggest] Omit this low priority information from documentation or put it into "Note box". The fact that it is placed in the first paragraph of the chapter (which indicates importance or high level of abstraction) is confusing.

Inconsistent typography
    [where]  System Properties
    [now]    ... estDefault - defaults to false. Set...
    [note]  Other paragraphs doesn't start on the same line as description of last item org.teiid.subqueryUnnestDefault

Comment contributed by Ken Johnson:

1. The Modeshape docs (Getting Started Guide; Reference Guide) are
included and branded as part of the SOA Platform.  They belong as part
of the Data Services Platform.  See:

http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5/html/Modeshape_Getting_Started_Guide/index.html
http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Enterprise_SOA_Platform/5/html/Modeshape_Reference_Guide/index.html

2. The branding/titling of the Doc is "Modeshape".  It should probably
be "ModeShape Metadata Repository".  How about something along these lines?:

Title: Metadata Repository Getting Started Guide
Subhead: A beginnes guide to using the ModeShape Repository in
conjunction with the JBoss Enterprise Data Services Platform.

Title: Metadata Repository Reference Guide
Subhead: A guide for programmers working with the ModeShape Repository.

Closing - QE doc reviews are complete.