Derby
  1. Derby
  2. DERBY-3518

Getting started guide: Incomplete instructions for compiling WwdEmbedded.java

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.3.2.1
    • Fix Version/s: 10.6.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      In the Getting Started with Derby manual's Self-study tutorial for users new to Derby, there is an Activity 3 which describes how to run a JDBC program using the embedded driver: http://db.apache.org/derby/docs/dev/getstart/twwdactivity3_Setup.html .
      In step 2, the guide says:

      <quote>
      Compile the WwdEmbedded.java program.

      javac WwdEmbedded.java
      </quote>

      Since WwdEmbedded.java (available from <bin-installation>/demo/programs/workingwithderby/) references the WwdUtils class, WwdUtils.java needs to be copied and compiled as well. Otherwise, compiling will fail with:

      WwdEmbedded.java:80: cannot resolve symbol
      symbol : variable WwdUtils
      location: class WwdEmbedded
      if (! WwdUtils.wwdChk4Table(conn))
      ^
      WwdEmbedded.java:92: cannot resolve symbol
      symbol : variable WwdUtils
      location: class WwdEmbedded
      answer = WwdUtils.getWishItem();
      ^
      2 errors

      The manual should be updated to reflect this requirement.

      This issue was first reported on the derby-user mailing list 2008-03-06 by Tosca Lahiri, see http://www.nabble.com/javac-WwdEmbedded.java-td15924527.html

      1. derby3518-correction.diff
        1 kB
        Kim Haase
      2. docs.diff
        2 kB
        Bryan Pendleton
      3. docs2.diff
        3 kB
        Bryan Pendleton
      4. twwdactivity3_Setup.html
        8 kB
        Bryan Pendleton
      5. twwdactivity3_Setup.html
        8 kB
        Bryan Pendleton
      6. twwdactivity4.html
        16 kB
        Bryan Pendleton

        Activity

        Hide
        John H. Embretsen added a comment -

        Activity 4, Step 1 f (compiling WwdClient.java) should probably clarify this as well.

        Show
        John H. Embretsen added a comment - Activity 4, Step 1 f (compiling WwdClient.java) should probably clarify this as well.
        Hide
        Bryan Pendleton added a comment -

        I adjusted the text in the step 2 section slightly to clarify that both
        Java source files need to be compiled.

        Show
        Bryan Pendleton added a comment - I adjusted the text in the step 2 section slightly to clarify that both Java source files need to be compiled.
        Hide
        Kim Haase added a comment -

        Actually, WwdClientExample.java is provided just as a sanity check for Activity 4, though I don't think it is mentioned there. Activity 3 should probably mention only the embedded example and the utility class, unless you want to modify Activity 4 too.

        Activity 4 tells people to copy the embedded program to WwdClient.java and make the two changes that turn it into a client example.

        If you wanted to to go to the bother of modifying Activity 4, you could change that topic to tell people to check their edited program against WwdClientExample.java. A more elaborate change would to tell them, instead of copying the file and making the changes, to open WwdClientExample.java in a text editor and notice the differences from the embedded program and then run it.

        Your call ... Thanks for dealing with this issue!

        Show
        Kim Haase added a comment - Actually, WwdClientExample.java is provided just as a sanity check for Activity 4, though I don't think it is mentioned there. Activity 3 should probably mention only the embedded example and the utility class, unless you want to modify Activity 4 too. Activity 4 tells people to copy the embedded program to WwdClient.java and make the two changes that turn it into a client example. If you wanted to to go to the bother of modifying Activity 4, you could change that topic to tell people to check their edited program against WwdClientExample.java. A more elaborate change would to tell them, instead of copying the file and making the changes, to open WwdClientExample.java in a text editor and notice the differences from the embedded program and then run it. Your call ... Thanks for dealing with this issue!
        Hide
        Bryan Pendleton added a comment -

        Thanks Kim! I was a bit confused about the WwdClientExample.java program;
        your explanation makes it more clear.

        I attempted to clarify both activity 3 and activity 4 with respect to the use of
        the WwdClientExample program in this latest patch, and have attached
        updated copies of the generated HTML.

        Show
        Bryan Pendleton added a comment - Thanks Kim! I was a bit confused about the WwdClientExample.java program; your explanation makes it more clear. I attempted to clarify both activity 3 and activity 4 with respect to the use of the WwdClientExample program in this latest patch, and have attached updated copies of the generated HTML.
        Hide
        Bryan Pendleton added a comment -

        Committed to the docs trunk as revision 881809.

        Show
        Bryan Pendleton added a comment - Committed to the docs trunk as revision 881809.
        Hide
        John H. Embretsen added a comment -

        Excellent, looks good. Closing the bug.

        Show
        John H. Embretsen added a comment - Excellent, looks good. Closing the bug.
        Hide
        Kim Haase added a comment -

        Very sorry to have missed this before. A DITA error in a source file prevents the PDF from being created:

        [pipeline] [Error] twwdactivity4.dita:246:12: The content of element type "taskbody" must match "(prereq?,context?,(steps|steps-unordered)?,result?,example?,postreq?)".

        The solution is simply to move the new <note> element inside the <context> element.

        I'll attach a patch that makes this change.

        Show
        Kim Haase added a comment - Very sorry to have missed this before. A DITA error in a source file prevents the PDF from being created: [pipeline] [Error] twwdactivity4.dita:246:12: The content of element type "taskbody" must match "(prereq?,context?,(steps|steps-unordered)?,result?,example?,postreq?)". The solution is simply to move the new <note> element inside the <context> element. I'll attach a patch that makes this change.
        Hide
        Kim Haase added a comment -

        Patch to correct DITA error in twwdactivity4.dita.

        Show
        Kim Haase added a comment - Patch to correct DITA error in twwdactivity4.dita.
        Hide
        Bryan Pendleton added a comment -

        I confirmed that Kim's patch removes the [Error] from the build in my environment,
        and committed the patch to the docs trunk as revision 888233.

        I'll leave this issue open until we confirm that the docs can be built successfully to the web site.

        Show
        Bryan Pendleton added a comment - I confirmed that Kim's patch removes the [Error] from the build in my environment, and committed the patch to the docs trunk as revision 888233. I'll leave this issue open until we confirm that the docs can be built successfully to the web site.
        Hide
        Bryan Pendleton added a comment -

        (re-)resolved. The follow-on patch appears to be fine, and the docs build
        to the master website seems to be OK.

        Show
        Bryan Pendleton added a comment - (re-)resolved. The follow-on patch appears to be fine, and the docs build to the master website seems to be OK.
        Hide
        Knut Anders Hatlen added a comment -

        [bulk update] Close all resolved issues that haven't been updated for more than one year.

        Show
        Knut Anders Hatlen added a comment - [bulk update] Close all resolved issues that haven't been updated for more than one year.

          People

          • Assignee:
            Bryan Pendleton
            Reporter:
            John H. Embretsen
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development