XMLBeans
  1. XMLBeans
  2. XMLBEANS-463

Improve the "First Steps with XMLBeans" tutorial

    Details

      Description

      I have found several issues with the First Steps with XMLBeans tutorial, as well as some functional issues.... below are comments/findings:

      =================================================

      The opening introduction states, "you'll get a hands on view of two of the three technologies that make up version 1 of XMLBeans:". Rather than leaving the reader wondering what the third uncovered technology is, it would be nice to at least mention it. Note: From the main page of the web site, "I believe it's Support for XML DOM".

      Note: I just noticed that the third option is covered a little deeper into the tutorial... but it still may be beneficial to mention it upfront.

      =================================================

      The tutorial reads:

      "To get started, you'll need the following:

      • JDK 1.4 for version 1 XMLBeans releases."

      Observation: Java 2 Platform, Standard Edition, v 1.4.2 has been end-of-service life since 2008. I believe 1.5 is also. Since JDK 1.7 was just released and the industry standard up to now has been JDK 1.6, I think the documentation and testing and deployment of the product, in general, should reflect this.

      =================================================

      The tutorial reads:

      "To get started, you'll need the following:

      ...

      • An XMLBeans version 1 installation. ..."

      Observation: The target here should be a version 2 installation.

      =================================================

      The tutorial states references, "xpretty schemas\easypo\easypo.xsd".

      However, there is no "easypo" directory in version 2.5.0.

      Therefore, the tutorial should reference, "xpretty schemas\easypo.xsd"

      =================================================

      The tutorial states:

      "scomp -out tutorials\gettingstarted\lib\easypo.jar schemas\easypo\easypo.xsd"

      However, there is no easy po directory in version 2.5.0 so it should read:

      "scomp -out tutorials\gettingstarted\lib\easypo.jar schemas\easypo\easypo.xsd"

          • There's an error with this too, as it's trying to run the javac compiler from the xmlbeans-2.5.0 folder.

      The fix for this is:

      "scomp -compiler %JDK_HOME%\bin\javac.exe -out tutorials\gettingstarted\lib\easypo.jar schemas\easypo\easypo.xsd"

      There's a problem here too, if Java is installed in a directory with a space (e.g., "C:\Program Files\Java\jdk1.6.0_26"). That is moving the install to "C:\jdk1.6.0_26" works fine. This is a problem as the space should be handled.

      =================================================

      The tutorial reads:

      The output should look like the instance output above, but with the following added as the last <line-item> element, immediately before the <shipper> element.

      <line-item>
      <description>Backyard Astronomer's Guide, The</description>
      <per-unit-ounces>5.0</per-unit-ounces>
      <price>49.95</price>
      <quantity>2</quantity>
      </line-item>

      but it should read:

      The output should look like the instance output above, but with the following added as the last <line-item> element, immediately before the <shipper> element.

      <line-item>
      <description>a new item</description>
      <per-unit-ounces>5.0</per-unit-ounces>
      <price>20.00</price>
      <quantity>6</quantity>
      </line-item>

      =================================================

      Test in the tutorial reads:

      Here's a full version of the POUpdater class, with the addLineItem method accessible via a main method.
      ...
      import org.apache.easypo.*;

      As this doesn't compile, it should read:

      Here's a full version of the POUpdater class, with the addLineItem method accessible via a main method.
      ...
      import org.openuri.easypo.*;

      That is, "import org.apache.easypo.;" should read "import org.openuri.easypo.;"

      Actually, it's a best practice if the imports spelled out the exact class names, and not use a wildcard. So, all the imports throughout the tutorial should site the specific classes being used.

      =================================================

        Activity

        There are no comments yet on this issue.

          People

          • Assignee:
            Unassigned
            Reporter:
            Robert Liguori
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development