[prev in list] [next in list] [prev in thread] [next in thread] 

List:       xmlbeans-dev
Subject:    [jira] [Updated] (XMLBEANS-463) Improve the "First Steps with
From:       "Robert Liguori (JIRA)" <xmlbeans-dev () xml ! apache ! org>
Date:       2011-08-01 11:56:09
Message-ID: 2033328435.22653.1312199769723.JavaMail.tomcat () hel ! zones ! apache ! org
[Download RAW message or body]


     [ https://issues.apache.org/jira/browse/XMLBEANS-463?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel \
]

Robert Liguori updated XMLBEANS-463:
------------------------------------

    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.

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

  was:
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.

Note: Double clicking on the generate JAR file (to see the contents) display a dialog \
box with the following message, "Invalid or corrupt jarfile".

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

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.

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


> Improve the "First Steps with XMLBeans" tutorial
> ------------------------------------------------
> 
> Key: XMLBEANS-463
> URL: https://issues.apache.org/jira/browse/XMLBEANS-463
> Project: XMLBeans
> Issue Type: Improvement
> Affects Versions: Version 2.5
> Environment: Tutorial: First Steps with XMLBeans
> http://xmlbeans.apache.org/documentation/tutorial_getstarted.html
> Windows Vista, JDK 1.6 update 26
> Reporter: Robert Liguori
> Priority: Minor
> 
> 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. =================================================

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@xmlbeans.apache.org
For additional commands, e-mail: dev-help@xmlbeans.apache.org


[prev in list] [next in list] [prev in thread] [next in thread]