[other] Doc review: "Using Java Persistence API Within a Visual Web Application"

[Jacek Laskowski]

Hi,

Just noticed the article "Using Java Persistence API Within a Visual
Web Application" and read it hoping I could see some really fancy
features of visual web and jpa. I must admit I'm disappointed a bit. I
could find out about visual web jsf support in NetBeans that made me
confident the article is worth to read, but I'm really disappointed
with the way JPA was presented. This is yet another article about JPA
in the outside-the-container mode which is convenient in a standalone
java application, but not in a Java EE 5 environment where one could
use JPA in a more compact approach - in JTA mode, managed by a EJB
container. That's where I think the strength of JPA lies. The
persistence.xml is shorter as well as the code needed. One could
wonder why there's some much code to persist classes and what the JPA
hype is all about. I'm still scratching my head why people use the
outside-the-container mode within a Java EE application server like
GlassFish? I would expect that the articles on NetBeans website show
the beauty of NetBeans itself *and* how it leverages Java EE 5
features to build enterprise applications. It seems I need to wait a
while.

Using Java Persistence API Within a Visual Web Application
http://www.netbeans.org/kb/60/web/web-jpa.html

1/ The table in "This article works with the following technologies
and resources" misses images:
http://www.netbeans.org/kb/images/articles/check.png
http://www.netbeans.org/kb/images/articles/spacer.png
are not found and hence the images in this article aren't displayed.

2/ "If you are using a different server, consult the Release Notes..."
and later in this section "...see the Release Notes". where Release
Notes links to http://../community/releases/60/relnotes.html that does
not exist.

3/ Inconsistent case using "Visual Web Table component" or "Visual Web
table component"

4/ Change

In addition to covering using Java Persistence API, we also showcase
some of the features of the NetBeans IDE. You'll see how to use the
IDE to

to

Besides introduction to Java Persistence API (JPA in short), you will
see how to use the IDE to:

5/ Change

Define a persistence unit, required when using Java Persistence in an
application.

to

Define a persistence unit

Optionally with "which is a mandatory configuration file for any JPA
application"

I think the entire chapter "Why Use the Java Persistence API" should
be rewritten.

6/ Change

The Java Persistence API, introduced in the Java EE 5 platform, can be
used directly by web applications and clients, both within and outside
of the Java EE platform.

to

The Java Persistence API, introduced in the Java EE 5 platform, can be
used in enterprise applications like web applications or ejbs and
their remote clients deployed onto Java EE 5 environment (e.g.
GlassFish) or outside the Java EE platform.

7/ Change

There are a number of reasons why you might want to use the Java
Persistence API. For one, it is a simple, lightweight programming
model since it treats entity objects (that is, Enterprise JavaBean
components that use container-managed persistence) as plain old Java
objects (POJOs).

to

JPA is a simple and lightweight programming model where POJOs are the
first-class citizens.

8/ Change

Treating entity objects as POJOs leads to other advantages to using
the Java Persistence API

to

Dealing with entity objects as POJOs leads to other advantages of
using the Java Persistence API

9/ Change

standard application programmer interface

to

standard application programming interface

10/ Change

you can combine different Java EE containers with different database
systems and without compromising application portability.

to

you can combine different Java EE containers with different database
systems without compromising application portability.

11/ Change

You can add a Users table to the sample Derby database included for
Visual Web applications

to

You can add the Users table to the sample Derby database using
Databases node in the Services window.

12/ Change

You can execute an SQL script from a file to create this table. Or,
you could execute each line of SQL code individually.

to

You can execute an SQL script from a file to create this table or
execute each line of SQL code individually.

13/ Change

the Services pane

to

the Services window

pane == window

14/ Change

Click the New Project icon in the toolbar

to

Click the New Project icon in the toolbar (Ctrl+Shift+N)

15/ I'd bold the menu and button names in "then select General in the
Categories column and Java Application in the Projects column. Then
click Next."

16/ The screenshots of New Java Application wizard are too small. They
should be much larger. Clicking on them should open a new popup
window.

17/ In "Creating the Projects" step 2. there's missing: "Press Finish button"

18/ Packages names are not always highlighted in the text.

19/ Add "Press Finish" to step 5 of "Creating the Projects"

20/ Change

to be a dependent project to the TestWebApp project

to

to be a dependency of the TestWebApp project

21/ Change

You use the Java Persistence API to bind a table that is displayed in
the application to a database table.

to

You use the Java Persistence API to convey information back and forth
from a database table to the table visual component that's used in the
Visual Web JSF application.

22/ Change

From the Services pane

to

From the Services window

23/ Change

Each entity class contains a set of annotations (identified by a
leading @ sign) that define the table's relationships and keys.

to

JPA uses Java language annotation feature to mark POJOs as JPA
entities with information on object-relation mapping.

24/ A screenshot would help a lot in " Creating a Java Persistence
Entity Class Representing the Users Database Table" step 1.

25/ Remove

Notice that the listing includes code lines that begin with an @ sign
followed by some text, such as @Id or @Column(name = "PASSWORD"). The
@ sign marks those lines that are Java Persistence annotations.

26/ Replace "the Users.java entity class" with "create the Users entity class"

27/ Remove the section Generated Type Strategies as it unnecessarily
widens the article that might scare people of its length.

28/ In "Creating a Property in the Session Bean" section, there should
be some introductory text about where to find the SessionBean1 managed
bean.

29/ A typo in "The INsert Code action"

30/ Add "Press OK" in step 3 of "Binding the Property to the Table Component".

31/ Change "that data should displays as shown here" to "that data
should be displayed as shown here"

Jacek

--
Jacek Laskowski
http://www.JacekLaskowski.pl

[Geertjan Wielenga]

Jacek Laskowski wrote:

> Hi,
>
> Just noticed the article "Using Java Persistence API Within a Visual
> Web Application" and read it hoping I could see some really fancy
> features of visual web and jpa. I must admit I'm disappointed a bit. I
> could find out about visual web jsf support in NetBeans that made me
> confident the article is worth to read, but I'm really disappointed
> with the way JPA was presented. This is yet another article about JPA
> in the outside-the-container mode which is convenient in a standalone
> java application, but not in a Java EE 5 environment where one could
> use JPA in a more compact approach - in JTA mode, managed by a EJB
> container. That's where I think the strength of JPA lies. The
> persistence.xml is shorter as well as the code needed. One could
> wonder why there's some much code to persist classes and what the JPA
> hype is all about. I'm still scratching my head why people use the
> outside-the-container mode within a Java EE application server like
> GlassFish? I would expect that the articles on NetBeans website show
> the beauty of NetBeans itself *and* how it leverages Java EE 5
> features to build enterprise applications. It seems I need to wait a
> while.
>
> Using Java Persistence API Within a Visual Web Application
> http://www.netbeans.org/kb/60/web/web-jpa.html
>
> 1/ The table in "This article works with the following technologies
> and resources" misses images:
> http://www.netbeans.org/kb/images/articles/check.png
> http://www.netbeans.org/kb/images/articles/spacer.png
> are not found and hence the images in this article aren't displayed.
>
> 2/ "If you are using a different server, consult the Release Notes..."
> and later in this section "...see the Release Notes". where Release
> Notes links to http://../community/releases/60/relnotes.html that does
> not exist.
>
> 3/ Inconsistent case using "Visual Web Table component" or "Visual Web
> table component"
>
> 4/ Change
>
> In addition to covering using Java Persistence API, we also showcase
> some of the features of the NetBeans IDE. You'll see how to use the
> IDE to
>
> to
>
> Besides introduction to Java Persistence API (JPA in short), you will
> see how to use the IDE to:
>
> 5/ Change
>
> Define a persistence unit, required when using Java Persistence in an
> application.
>
> to
>
> Define a persistence unit
>
> Optionally with "which is a mandatory configuration file for any JPA
> application"
>
> I think the entire chapter "Why Use the Java Persistence API" should
> be rewritten.
>
> 6/ Change
>
> The Java Persistence API, introduced in the Java EE 5 platform, can be
> used directly by web applications and clients, both within and outside
> of the Java EE platform.
>
> to
>
> The Java Persistence API, introduced in the Java EE 5 platform, can be
> used in enterprise applications like web applications or ejbs and
> their remote clients deployed onto Java EE 5 environment (e.g.
> GlassFish) or outside the Java EE platform.
>
> 7/ Change
>
> There are a number of reasons why you might want to use the Java
> Persistence API. For one, it is a simple, lightweight programming
> model since it treats entity objects (that is, Enterprise JavaBean
> components that use container-managed persistence) as plain old Java
> objects (POJOs).
>
> to
>
> JPA is a simple and lightweight programming model where POJOs are the
> first-class citizens.
>
> 8/ Change
>
> Treating entity objects as POJOs leads to other advantages to using
> the Java Persistence API
>
> to
>
> Dealing with entity objects as POJOs leads to other advantages of
> using the Java Persistence API
>
> 9/ Change
>
> standard application programmer interface
>
> to
>
> standard application programming interface
>
> 10/ Change
>
> you can combine different Java EE containers with different database
> systems and without compromising application portability.
>
> to
>
> you can combine different Java EE containers with different database
> systems without compromising application portability.
>
> 11/ Change
>
> You can add a Users table to the sample Derby database included for
> Visual Web applications
>
> to
>
> You can add the Users table to the sample Derby database using
> Databases node in the Services window.
>
> 12/ Change
>
> You can execute an SQL script from a file to create this table. Or,
> you could execute each line of SQL code individually.
>
> to
>
> You can execute an SQL script from a file to create this table or
> execute each line of SQL code individually.
>
> 13/ Change
>
> the Services pane
>
> to
>
> the Services window
>
> pane == window
>
> 14/ Change
>
> Click the New Project icon in the toolbar
>
> to
>
> Click the New Project icon in the toolbar (Ctrl+Shift+N)
>
> 15/ I'd bold the menu and button names in "then select General in the
> Categories column and Java Application in the Projects column. Then
> click Next."
>
> 16/ The screenshots of New Java Application wizard are too small. They
> should be much larger. Clicking on them should open a new popup
> window.
>
> 17/ In "Creating the Projects" step 2. there's missing: "Press Finish button"
>
> 18/ Packages names are not always highlighted in the text.
>
> 19/ Add "Press Finish" to step 5 of "Creating the Projects"
>
> 20/ Change
>
> to be a dependent project to the TestWebApp project
>
> to
>
> to be a dependency of the TestWebApp project
>
> 21/ Change
>
> You use the Java Persistence API to bind a table that is displayed in
> the application to a database table.
>
> to
>
> You use the Java Persistence API to convey information back and forth
> from a database table to the table visual component that's used in the
> Visual Web JSF application.
>
> 22/ Change
>
> From the Services pane
>
> to
>
> From the Services window
>
> 23/ Change
>
> Each entity class contains a set of annotations (identified by a
> leading @ sign) that define the table's relationships and keys.
>
> to
>
> JPA uses Java language annotation feature to mark POJOs as JPA
> entities with information on object-relation mapping.
>
> 24/ A screenshot would help a lot in " Creating a Java Persistence
> Entity Class Representing the Users Database Table" step 1.
>
> 25/ Remove
>
> Notice that the listing includes code lines that begin with an @ sign
> followed by some text, such as @Id or @Column(name = "PASSWORD"). The
> @ sign marks those lines that are Java Persistence annotations.
>
> 26/ Replace "the Users.java entity class" with "create the Users entity class"
>
> 27/ Remove the section Generated Type Strategies as it unnecessarily
> widens the article that might scare people of its length.
>
> 28/ In "Creating a Property in the Session Bean" section, there should
> be some introductory text about where to find the SessionBean1 managed
> bean.
>
> 29/ A typo in "The INsert Code action"
>
> 30/ Add "Press OK" in step 3 of "Binding the Property to the Table Component".
>
> 31/ Change "that data should displays as shown here" to "that data
> should be displayed as shown here"
>
> Jacek
>
>  

Passing this on to James Branam, I think he might be able to respond or
integrate your comments on this tutorial.

Gj