[
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.
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.
=================================================
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.
> 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.
> =================================================
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@xmlbeans.apache.org
For additional commands, e-mail: dev-h...@xmlbeans.apache.org
