Uploaded image for project: 'WildFly'
  1. WildFly
  2. WFLY-14349

Enhance the datasource documentation to better cover basic DS addition

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Unresolved
    • Major
    • None
    • None
    • JCA
    • None
    • Undefined
    • ---
    • ---

    Description

      The https://docs.wildfly.org/22/Admin_Guide.html#DataSource doc could use some improvement.

      The biggest thing is it should walk through a complete example of adding a datasource. Right now it notes the 'data-source' CLI command and tells you you can use --help. That's good to know but there should be an example of using 'datasource add'.

      Other inputs in no particular order of importance:

      1) 'Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs will contain a text a file named META-INF/services/java.sql.Driver, which contains the name of the class(es) of the Drivers which exist in that JAR. If your JDBC driver JAR is not JDBC 4-compliant, it can be made deployable in one of a few ways.' – The last sentence should be a separate paragraph as it's the beginning of a separate subtopic, one that is a distraction for many readers.

      2) The 'For a detailed explanation how to deploy JDBC 4 compliant driver jar, please refer to the chapter "Application Deployment"' text in the driver section should be moved before the discussion of non-JDBC4 compliant jars. It's more important info for a typical non-expert user. Also, I suggest a bit more words. 'A JDBC 4 compliant driver jar can be deployed using the CLI, the HAL management console or by copying the jar to the standalone/deployments directory. For a detailed explanation how to deploy a driver jar, please refer to the chapter "Application Deployment".'

      3) The 'Datasource Definitions' section includes CLI output of the installed-drivers-list operation. That should be in the previous section, and the example output should include a driver installed as a deployment, not just h2. (Which implies the previous section should include an example CLI command deploying a driver.)

      4) Add an actual example of using 'data-source add'

      Attachments

        Activity

          People

            tadamski@redhat.com Tomasz Adamski
            bstansbe@redhat.com Brian Stansberry
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated: