Uploaded image for project: 'JBoss Enterprise Application Platform'
  1. JBoss Enterprise Application Platform
  2. JBEAP-12196

Development Guide - Possible issues noted during review

XMLWordPrintable

      1. "Java Enterprise Edition 7 Full Profile"
        **I think you can remove bullet from "Included in the EE 7 Full Profile" and shift the bullets below to the left.
      2. "1.4. Configure the Default Welcome Web Application"
        • The sections under this seem more like procedures. I wonder if it would be better to change the titles, for example, from "Changing the welcome-content File Handler" to Change the welcome-content File Handler" and put the instructions in steps? This cooment also applies to "Changing the default-web-module" and "Disabling the Default Welcome Web Application"
      3. "2.2.5. Download the JBoss EAP Maven Repository Using the Offliner Application"
        • This section could be reorganized a bit so that it is not nested. Suggest removing this sentence: "Follow these steps to download the JBoss EAP Maven repository. " and this sentence "To download the JBoss EAP Maven repository, download and run the Offliner application." You end up with this content: 
                  An Offliner application is now available as an alternate option to download the Maven artifacts from the Red Hat Maven repository for developing JBoss EAP 7.1 applications.

        1. Download the jboss-eap-7.1.0.Beta1-maven-repository-content-with-sha256-checksums.txt text file, which serves as the input to the Offliner application, from the Red Hat Customer Portal.

        2. Download the Offliner application JAR from the Maven Central Repository.

        3. Execute the Offliner application by running the following command:

        java -jar offliner.jar -r http://repository.redhat.com/earlyaccess/all/ -d FOLDER_TO_DOWNLOAD_TO jboss-eap-7.1.0.Beta1-maven-repository-content-with-sha256-checksums.txt

        The artifacts from the JBoss EAP Maven repository will be downloaded in the FOLDER_TO_DOWNLOAD_TO directory.

        See the Offliner Documentation for more information on running the Offliner application.
      4. "3.7.4.1. Reference of Shared Session Config Options"
        • The structure at the beginning of this section seems redundant. It takes up lot of space and the elements and attributes are repeated in the XML example. Do you think the structure should be removed? Also, the elements and attributes and their descriptions might be better in a table.
      5. "3.9. Reference"
        • This chapter title is vague. Should it be renamed to "Class Loading Reference" or "Modules Reference"? Or maybe the topics should just be moved to the appendix?
      6. "3.9.1. Implicit Module Dependencies"\
        • Remove the backticks from standalone attribute entries in the table.
      7. "3.9.3. JBoss Deployment Structure Deployment Descriptor Reference"
        • How is this a reference? It seems odd there. Would be better to include the content with "3.1.4. jboss-deployment-structure.xml"?
      8. "4.5.7. References"
        • Again, this chapter title is vague. Should it be "JBoss Logging Tools References"?
      9. "Table 4.2. JBoss Logging Tools Annotations"
        • No need for backticks around annotations and attributes.
      10. "6.1.2. Enable Session Replication in Your Application"
        • The first 2 sentences in step 1 are strange. I think you can drop the first one. The second could be moved to the end of the preceding paragraph.
      11. " 7.2.2. Exclude Beans From the Scanning Process"
        • There is a huge block of source code commented out in this file, 4453.adoc. Can it be deleted?
      12. "7.2.3. Use an Injection to Extend an Implementation"
        • The second paragraph below the title "Example: Inject a Translator Bean Into the Welcome Class" repeats a lot of the content of the first paragraph. I suggest moving the example title down to just before the example and consolidating the content of the first two paragraphs.
      13. "10.1. Introduction to Undertow Handler"
        • Just curious: Why are labels used to describe the 4 things that can happen in the request lifecycle instead of bullets? It makes it look like a title, but it's not in titlecase. They are sentences but have no ending period. Also, the description of the 4th option is not really clear. Is ithis "In this case the exchange will not be finished" meant to be "in the case of the latter, the exchange will not be finished"?
      14. "10.3. Creating Custom Handlers"
        • This section is not really clear. I believe it is saying there are two ways to define customer handlers: "1. Using WEB-INF/jboss-web.xml file, 2. WEB-INF/undertow-handlers.conf file."It would be nice to add an introductory paragraph introducing this and then maybe use a subtitle for each method.
      15. "11.2.10. Limitations of the XA Recovery Process"
        • Should these labels be changed to bullets?
      16. "11.7. Transactions Usage In Practice"
        • This section doesn't flow right. The outline at the beginning doesn't match the content. There are sections like "11.7.4. Nested Transactions" that are between the "Begin Transaction" and "Commit Transaction".
      17. "11.7.3. Begin a Transaction"
        • This subsection seems out of place: "Participate in an existing transaction using the JTS specification". Does it belong here?
      18. "13.2.2. Hibernate Validator Constraints"
        • The annotation column doesn't need formatting in the tables.
      19. "Table A.4. Parameters, Table A.5. Parameters, Table A.6. Parameters, Table A.8. Parameters"
        • These tables contain a link to the Undertow default parameter, but the link takes you to the middle of a section. It might be nice to add a subsection title "Undertow Default Parameter" in that section to link to.
      20. "11.4.3. About Transaction Roll-Back"
        • This title and other instances of "roll-back" should just be "rollback".

            rhn-support-pnag Priyanka Pandey
            sgilda_jira Sande Gilda (Inactive)
            Jan Stourac Jan Stourac
            Jan Stourac Jan Stourac
            Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

              Created:
              Updated:
              Resolved: