You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@openjpa.apache.org by aw...@apache.org on 2006/08/24 22:41:14 UTC
svn commit: r434517 [11/23] - in /incubator/openjpa/trunk:
openjpa-kernel/src/main/java/org/apache/openjpa/meta/
openjpa-lib/src/main/java/org/apache/openjpa/lib/meta/
openjpa-project/src/doc/manual/
Modified: incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml
URL: http://svn.apache.org/viewvc/incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml?rev=434517&r1=434516&r2=434517&view=diff
==============================================================================
--- incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml (original)
+++ incubator/openjpa/trunk/openjpa-project/src/doc/manual/jpa_tutorials.xml Thu Aug 24 13:41:12 2006
@@ -1,240 +1,251 @@
-
- <chapter id="jpa_tutorials">
- <title>JPA Tutorials</title>
- <section id="jpa_tutorials_intro">
- <title>OpenJPA Tutorials</title>
+<chapter id="jpa_tutorials">
+ <title>
+ JPA Tutorials
+ </title>
+ <section id="jpa_tutorials_intro">
+ <title>
+ OpenJPA Tutorials
+ </title>
<para>
- These tutorials provide step-by-step examples of how to use various
- facets of the OpenJPA system. They assume a general knowledge
- of JPA and Java. For more information on these subjects, see
- the following URLs:
- </para>
+These tutorials provide step-by-step examples of how to use various facets of
+the OpenJPA system. They assume a general knowledge of JPA and Java. For more
+information on these subjects, see the following URLs:
+ </para>
<itemizedlist>
- <listitem>
- <para>
- <ulink url="http://java.sun.com/">Sun's Java site</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="jpa_overview_intro">JPA Overview Document</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link linkend="jpa_resources">Links to JPA</link>
- </para>
- </listitem>
+ <listitem>
+ <para>
+<ulink url="http://java.sun.com/">Sun's Java site</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<link linkend="jpa_overview_intro">JPA Overview Document</link>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<link linkend="jpa_resources">Links to JPA</link>
+ </para>
+ </listitem>
</itemizedlist>
<section id="jpa_tutorial_requirements">
- <title>Tutorial Requirements</title>
- <para>
- These tutorials require that JDK 1.5 or greater be installed
- on your computer, and that <literal>java</literal> and
- <literal>javac</literal> are in your <literal>PATH</literal> when
- you open a command shell.
- </para>
+ <title>
+ Tutorial Requirements
+ </title>
+ <para>
+These tutorials require that JDK 1.5 or greater be installed on your computer,
+and that <literal>java</literal> and <literal>javac</literal> are in your
+<literal>PATH</literal> when you open a command shell.
+ </para>
</section>
- </section>
- <section id="jpa_tutorial">
- <title>OpenJPA Tutorial</title>
+ </section>
+ <section id="jpa_tutorial">
+ <title>
+ OpenJPA Tutorial
+ </title>
<para>
- In this tutorial you will become familiar with the basic tools and
- development processes under OpenJPA by creating a simple JPA application.
- </para>
+In this tutorial you will become familiar with the basic tools and development
+processes under OpenJPA by creating a simple JPA application.
+ </para>
<section id="jpa_tutorial_chapter1">
- <title>The Pet Shop</title>
- <para>
- Imagine that you have decided to create a software toolkit to be used
- by pet shop operators. This toolkit must provide a number of solutions
- to common problems encountered at pet shops. Industry analysts indicate
- that the three most desired features are inventory maintenance,
- inventory growth simulation, and behavioral analysis. Not one to
- question the sage advice of experts, you choose to attack these three
- problems first.
- </para>
- <para>
- According to the aforementioned experts, most pet shops focus on three
- types of animals only: dogs, rabbits, and snakes. This ontology
- suggests the following class hierarchy:
- </para>
- <para>
- <screen format="linespecific">
- Animal
- ^
- |
- +--------------------+
- | | |
- Dog Rabbit Snake
- </screen>
- </para>
- <section id="jpa_tutorial_files">
- <title>Included Files</title>
- <para>
- We have provided an implementation of <classname>Animal</classname>
- and <classname>Dog</classname> classes, plus some helper classes
- and files to create the initial schema and populate the database
- with some sample dogs. Let's take a closer look at these classes.
- </para>
- <itemizedlist>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/AnimalMaintenance.java"><classname>
- tutorial.persistence.AnimalMaintenance</classname></ulink>:
- Provides some utility methods for examining and
- manipulating the animals stored in the database. We will
- fill in method definitions in
- <xref linkend="jpa_tutorial_chapter3"/>.
- </para>
- </listitem>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/Animal.java"><classname>tutorial.persistence.Animal</classname></ulink>:
- This is the superclass of all animals that this pet store
- software can handle.
- </para>
- </listitem>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/Dog.java"><classname>tutorial.persistence.Dog</classname></ulink>:
- Contains data and methods specific to dogs.
- </para>
- </listitem>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/Rabbit.java"><classname>tutorial.persistence.Rabbit</classname></ulink>:
- Contains data and
- methods specific to rabbits. It will be used in
- <xref linkend="jpa_tutorial_chapter4"/>.
- </para>
- </listitem>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/Snake.java"><classname>tutorial.persistence.Snake</classname></ulink>:
- Contains data and
- methods specific to snakes. It will be used in
- <xref linkend="jpa_tutorial_chapter5"/>.
- </para>
- </listitem>
- <listitem>
- <para><ulink url="../../../META-INF/persistence.xml"><filename>../../META-INF/persistence.xml</filename></ulink>:
- This XML file contains OpenJPA-specific and standard JPA
- configuration settings.
- </para>
- <para>
- It is important to load all persistent entity classes at
- startup so that OpenJPA can match database discriminator values
- to entity classes. Often this happens automatically.
- Some parts of this tutorial, however, do require that all
- entity classes be loaded explicitly. The JPA
- standard includes persistent class listings in its XML
- configuration format. Add the following lines to <filename>
- ../../META-INF/persistence.xml</filename> between the
- <literal><provider></literal> and the
- <literal><properties></literal> elements:
- </para>
- <programlisting format="linespecific">
+ <title>
+ The Pet Shop
+ </title>
+ <para>
+Imagine that you have decided to create a software toolkit to be used by pet
+shop operators. This toolkit must provide a number of solutions to common
+problems encountered at pet shops. Industry analysts indicate that the three
+most desired features are inventory maintenance, inventory growth simulation,
+and behavioral analysis. Not one to question the sage advice of experts, you
+choose to attack these three problems first.
+ </para>
+ <para>
+According to the aforementioned experts, most pet shops focus on three types of
+animals only: dogs, rabbits, and snakes. This ontology suggests the following
+class hierarchy:
+ </para>
+ <para>
+<screen> Animal ^ | +--------------------+ | | | Dog Rabbit Snake</screen>
+ </para>
+ <section id="jpa_tutorial_files">
+ <title>
+ Included Files
+ </title>
+ <para>
+We have provided an implementation of <classname>Animal</classname> and
+<classname>Dog</classname> classes, plus some helper classes and files to create
+the initial schema and populate the database with some sample dogs. Let's take a
+closer look at these classes.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/AnimalMaintenance.java"><classname>
+tutorial.persistence.AnimalMaintenance</classname></ulink>: Provides some
+utility methods for examining and manipulating the animals stored in the
+database. We will fill in method definitions in
+<xref linkend="jpa_tutorial_chapter3"></xref>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/Animal.java"><classname>
+tutorial.persistence.Animal</classname></ulink>: This is the superclass of all
+animals that this pet store software can handle.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/Dog.java"><classname>
+tutorial.persistence.Dog</classname></ulink>: Contains data and methods
+specific to dogs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/Rabbit.java"><classname>
+tutorial.persistence.Rabbit</classname></ulink>: Contains data and methods
+specific to rabbits. It will be used in <xref linkend="jpa_tutorial_chapter4">
+</xref>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/Snake.java"><classname>
+tutorial.persistence.Snake</classname></ulink>: Contains data and methods
+specific to snakes. It will be used in <xref linkend="jpa_tutorial_chapter5">
+</xref>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../META-INF/persistence.xml"><filename>
+../../META-INF/persistence.xml</filename></ulink>: This XML file contains
+OpenJPA-specific and standard JPA configuration settings.
+ </para>
+ <para>
+It is important to load all persistent entity classes at startup so that OpenJPA
+can match database discriminator values to entity classes. Often this happens
+automatically. Some parts of this tutorial, however, do require that all entity
+classes be loaded explicitly. The JPA standard includes persistent class
+listings in its XML configuration format. Add the following lines to <filename>
+../../META-INF/persistence.xml</filename> between the <literal><provider>
+</literal> and the <literal><properties></literal> elements:
+ </para>
+<programlisting>
<class>tutorial.persistence.Animal</class>
<class>tutorial.persistence.Dog</class>
</programlisting>
- </listitem>
- <listitem>
- <para><ulink url="../../../tutorial/persistence/solutions"><filename>solutions</filename></ulink>: The solutions
- directory contains the complete solutions to this tutorial,
- including finished versions of the
- <filename>.java</filename> files listed above.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="jpa_tutorial_utilities">
- <title>Important Utilities</title>
- <itemizedlist>
- <listitem>
- <para><command>java</command>: Runs main methods in specified
- Java classes.
- </para>
- </listitem>
- <listitem>
- <para><command>javac</command>: Compiles <filename>.java
- </filename> files into <filename>.class</filename>
- files that can be executed by <command>java</command>.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>openjpac</primary></indexterm><command>openjpac</command>:
- Runs the OpenJPA enhancer against the specified
- classes. More information is available in
- <xref linkend="ref_guide_pc_enhance"/> of the Reference
- Guide.
- </para>
- </listitem>
- <listitem>
- <para><indexterm><primary>mappingtool</primary></indexterm><command>mappingtool</command>: A
- utility that can be used to create and maintain the
- object-relational mappings and schema of all persistent
- classes in a JDBC-compliant datastore. This functionality
- allows the underlying mappings and schema to be easily
- kept up-to-date with the Java classes in the system. See
- <xref linkend="ref_guide_mapping"/>
- of the Reference Guide for more information.
- </para>
- </listitem>
- </itemizedlist>
- </section>
+ </listitem>
+ <listitem>
+ <para>
+<ulink url="../../../tutorial/persistence/solutions"><filename>solutions
+</filename></ulink>: The solutions directory contains the complete solutions to
+this tutorial, including finished versions of the <filename>.java</filename>
+files listed above.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="jpa_tutorial_utilities">
+ <title>
+ Important Utilities
+ </title>
+ <itemizedlist>
+ <listitem>
+ <para>
+<command>java</command>: Runs main methods in specified Java classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>javac</command>: Compiles <filename>.java</filename> files into
+<filename>.class</filename> files that can be executed by <command>java
+</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ openjpac
+ </primary>
+ </indexterm>
+<command>openjpac</command>: Runs the OpenJPA enhancer against the specified
+classes. More information is available in <xref linkend="ref_guide_pc_enhance">
+</xref> of the Reference Guide.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mappingtool
+ </primary>
+ </indexterm>
+<command>mappingtool</command>: A utility that can be used to create and
+maintain the object-relational mappings and schema of all persistent classes in
+a JDBC-compliant datastore. This functionality allows the underlying mappings
+and schema to be easily kept up-to-date with the Java classes in the system. See
+<xref linkend="ref_guide_mapping"></xref> of the Reference Guide for more
+information.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
<section id="jpa_tutorial_chapter2">
- <title>Getting Started</title>
- <para>
- Let's compile the initial classes and see them in action. To do
- so, we must compile the <filename>.java</filename> files, as we would
- with any Java project, and then pass the resulting classes through
- the OpenJPA enhancer:
- </para>
- <note>
- <para><indexterm><primary>CLASSPATH</primary></indexterm>
- Be sure that your <envar>CLASSPATH</envar> is set correctly.
- Note that your OpenJPA
- install directory should be in the <envar>CLASSPATH</envar>, as
- the tutorial classes are located in the <literal>
- tutorial/persistence</literal> directory under your OpenJPA install
- directory, and are in the <literal>tutorial.persistence</literal>
- package.
- </para>
- </note>
- <orderedlist>
- <listitem>
- <para>
- Make sure you are in the <filename>
- tutorial/persistence</filename>
- directory. All examples throughout the tutorial assume that
- you are in this directory.
- </para>
- </listitem>
- <listitem>
- <para>
- Examine <filename>Animal.java</filename>,
- <filename>Dog.java</filename>, and
- <filename>SeedDatabase.java</filename>
- </para>
- <para>
- These files are good examples of the simplicity JPA
- engenders. As noted earlier, persisting an object or
- manipulating an object's persistent data requires almost no
- JPA-specific code.
- For a very simple example of creating persistent objects,
- please see the <literal>seed</literal> method of
- <filename>SeedDatabase.java</filename>. Note the objects are
- created with normal Java
- constructors. The files <filename>Animal.java</filename> and
- <filename>Dog.java</filename> are also good examples of
- how JPA allows you to manipulate persistent data
- without writing any specific JPA code, by providing
- simple annotations.
- </para>
- <para>
- Let's take a look at the <filename>Animal.java</filename> file.
- Notice that the class is a Plain Old Java Object (POJO), with
- several annotations describing how the class is mapped into
- a relational database. First, let's examine the class level
- annotations:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Getting Started
+ </title>
+ <para>
+Let's compile the initial classes and see them in action. To do so, we must
+compile the <filename>.java</filename> files, as we would with any Java project,
+and then pass the resulting classes through the OpenJPA enhancer:
+ </para>
+ <note>
+ <para>
+ <indexterm>
+ <primary>
+ CLASSPATH
+ </primary>
+ </indexterm>
+Be sure that your <envar>CLASSPATH</envar> is set correctly. Note that your
+OpenJPA install directory should be in the <envar>CLASSPATH</envar>, as the
+tutorial classes are located in the <literal> tutorial/persistence</literal>
+directory under your OpenJPA install directory, and are in the <literal>
+tutorial.persistence</literal> package.
+ </para>
+ </note>
+ <orderedlist>
+ <listitem>
+ <para>
+Make sure you are in the <filename> tutorial/persistence</filename> directory.
+All examples throughout the tutorial assume that you are in this directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Examine <filename>Animal.java</filename>, <filename>Dog.java</filename>, and
+<filename>SeedDatabase.java</filename>
+ </para>
+ <para>
+These files are good examples of the simplicity JPA engenders. As noted earlier,
+persisting an object or manipulating an object's persistent data requires almost
+no JPA-specific code. For a very simple example of creating persistent objects,
+please see the <literal>seed</literal> method of <filename>SeedDatabase.java
+</filename>. Note the objects are created with normal Java constructors. The
+files <filename>Animal.java</filename> and <filename>Dog.java</filename> are
+also good examples of how JPA allows you to manipulate persistent data without
+writing any specific JPA code, by providing simple annotations.
+ </para>
+ <para>
+Let's take a look at the <filename>Animal.java</filename> file. Notice that the
+class is a Plain Old Java Object (POJO), with several annotations describing how
+the class is mapped into a relational database. First, let's examine the class
+level annotations:
+ </para>
+<programlisting>
@Entity(name="Animal")
@Table(name="JPA_TUT_ANIMAL")
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@@ -244,67 +255,60 @@
...
}
</programlisting>
- <para>
- The annotations serve to map the class into the database. For
- more information on these and other annotations, see
- <xref linkend="jpa_overview_meta"/> and
- <xref linkend="jpa_overview_mapping"/>.
- </para>
- <orderedlist>
- <listitem>
- <para><command>@Entity</command>: This annotation indicates
- that instances of this class may be persistent entities.
- The value of the <command>name</command> attribute is
- the entity name, and is used in queries, etc.
- </para>
- </listitem>
- <listitem>
- <para><command>@Table</command>: This annotation is used
- to map the entity to a primary table. The value of the
- <command>name</command> attribute specifies the name
- of the relational table to use as the primary table.
- </para>
- </listitem>
- <listitem>
- <para><command>@Inheritance</command>: When multiple classes
- in an inheritance hierarchy are persistent entity types,
- it is important to describe how the inheritance
- hierarchy is mapped. Setting the value of the
- <command>strategy</command> attribute to
- <command>InheritanceType.SINGLE_TABLE</command>
- indicates that the primary table for all subclasses
- shall be the same table as for the superclass.
- </para>
- </listitem>
- <listitem>
- <para><command>@DiscriminatorColumn</command>: With a
- <command>SINGLE_TABLE</command> inheritance mapping
- strategy, instances of multiple classes will be stored
- in the same table. This annotation describes a column
- in that table that is used to determine the type of
- an instance whose data is stored in a particular row.
- The <command>name</command> attribute is the name of
- the column, and the <command>length</command> attribute
- indicates the size of the column. By default, the
- unqualified class name for the instance is stored
- in the discriminator column. To store a different
- value for a type, use the <command>@DiscriminatorValue
- </command> annotation.
- </para>
- </listitem>
- </orderedlist>
- <para>
- Let's take a look at our class' field annotations.
- We have chosen to use <emphasis>field access</emphasis> for
- our entities, meaning the persistence implementation will
- get and set persistent state directly through our class'
- declared fields. We could have chosen to use <emphasis>
- property access</emphasis>, in which the implementation
- accesses persistent state through our JavaBean getter and
- setter methods. In that case, we would have annotated our
- getter methods rather than our fields.
- </para>
- <programlisting format="linespecific">
+ <para>
+The annotations serve to map the class into the database. For more information
+on these and other annotations, see <xref linkend="jpa_overview_meta"></xref>
+and <xref linkend="jpa_overview_mapping"></xref>.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+<command>@Entity</command>: This annotation indicates that instances of this
+class may be persistent entities. The value of the <command>name</command>
+attribute is the entity name, and is used in queries, etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@Table</command>: This annotation is used to map the entity to a
+primary table. The value of the <command>name</command> attribute specifies the
+name of the relational table to use as the primary table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@Inheritance</command>: When multiple classes in an inheritance
+hierarchy are persistent entity types, it is important to describe how the
+inheritance hierarchy is mapped. Setting the value of the <command>strategy
+</command> attribute to <command>InheritanceType.SINGLE_TABLE</command>
+indicates that the primary table for all subclasses shall be the same table as
+for the superclass.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@DiscriminatorColumn</command>: With a <command>SINGLE_TABLE</command>
+inheritance mapping strategy, instances of multiple classes will be stored in
+the same table. This annotation describes a column in that table that is used to
+determine the type of an instance whose data is stored in a particular row. The
+<command>name</command> attribute is the name of the column, and the <command>
+length</command> attribute indicates the size of the column. By default, the
+unqualified class name for the instance is stored in the discriminator column.
+To store a different value for a type, use the <command>@DiscriminatorValue
+</command> annotation.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+Let's take a look at our class' field annotations. We have chosen to use
+<emphasis>field access</emphasis> for our entities, meaning the persistence
+implementation will get and set persistent state directly through our class'
+declared fields. We could have chosen to use <emphasis> property access
+</emphasis>, in which the implementation accesses persistent state through our
+JavaBean getter and setter methods. In that case, we would have annotated our
+getter methods rather than our fields.
+ </para>
+<programlisting>
@Id
@GeneratedValue
@Column(name="ID")
@@ -316,188 +320,184 @@
@Basic @Column(name="COST")
private float price = 0f;
</programlisting>
- <para>
- The annotations serve to map the fields into the database. For
- more information on these and other annotations, see
- <xref linkend="jpa_overview_meta"/>.
- </para>
- <orderedlist>
- <listitem>
- <para><command>@Id</command>: This annotation indicates that
- the field is to be mapped to a primary key column in
- the database.
- </para>
- </listitem>
- <listitem>
- <para><command>@GeneratedValue</command>:
- Indicates that the implementation will generate a
- value for the field automatically.
- </para>
- </listitem>
- <listitem>
- <para><command>@Column</command>: This annotation describes
- the column to which the field will be mapped. The
- <command>name</command> attribute specifies the name
- of the column.
- </para>
+ <para>
+The annotations serve to map the fields into the database. For more information
+on these and other annotations, see <xref linkend="jpa_overview_meta"></xref>.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+<command>@Id</command>: This annotation indicates that the field is to be
+mapped to a primary key column in the database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@GeneratedValue</command>: Indicates that the implementation will
+generate a value for the field automatically.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@Column</command>: This annotation describes the column to which the
+field will be mapped. The <command>name</command> attribute specifies the name
+of the column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+<command>@Basic</command>: This annotation indicates that the field is simply
+mapped into a column. There are other annotations that indicate entity
+relationships and other more complex mappings.
+ </para>
+ </listitem>
+ </orderedlist>
</listitem>
<listitem>
- <para><command>@Basic</command>: This annotation indicates
- that the field is simply mapped into a column. There
- are other annotations that indicate entity
- relationships and other more complex mappings.
- </para>
- </listitem>
- </orderedlist>
- </listitem>
- <listitem>
- <para>Compile the <filename>.java</filename> files.</para>
- <programlisting format="linespecific">
+ <para>
+Compile the <filename>.java</filename> files.
+ </para>
+<programlisting>
javac *.java
</programlisting>
- <para>
- You can use any java compiler instead of
- <command>javac</command>.
- </para>
- </listitem>
- <listitem>
- <para>Enhance the persistent classes.</para>
- <programlisting format="linespecific">
+ <para>
+You can use any java compiler instead of <command>javac</command>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Enhance the persistent classes.
+ </para>
+<programlisting>
openjpac -p persistence.xml Animal.java Dog.java
</programlisting>
- <para>
- This step runs the OpenJPA enhancer on the
- <filename>Animal.java</filename> and
- <filename>Dog.java</filename> files mentioned above.
- See <xref linkend="ref_guide_pc_enhance"/> of the Reference
- Guide for more information on the enhancer, including how to
- use automatic runtime enhancement.
- </para>
- <note>
+ <para>
+This step runs the OpenJPA enhancer on the <filename>Animal.java</filename> and
+<filename>Dog.java</filename> files mentioned above. See
+<xref linkend="ref_guide_pc_enhance"></xref> of the Reference Guide for more
+information on the enhancer, including how to use automatic runtime enhancement.
+ </para>
+ <note>
+ <para>
+The <literal>-p</literal> flag points the enhancer to your <filename>
+persistence.xml</filename> configuration file. All OpenJPA tools look for
+default configuration in a resource called <filename>openjpa.xml</filename> or
+<filename>META-INF/openjpa.xml</filename>. Thus you can avoid passing the
+<literal>-p</literal> argument to tools by using this configuration file name in
+place of <filename>persistence.xml</filename>. See
+<xref linkend="ref_guide_conf"></xref> in the Reference Guide for details on
+OpenJPA configuration.
+ </para>
+ </note>
+ </listitem>
+ </orderedlist>
+ <section id="jpa_tutorial_chapter2_datastore">
+ <title>
+ Configuring the Datastore
+ </title>
<para>
- The <literal>-p</literal> flag points the enhancer to your
- <filename>persistence.xml</filename> configuration file.
- All OpenJPA tools look for default configuration in a
- resource called <filename>openjpa.xml</filename> or
- <filename>META-INF/openjpa.xml</filename>. Thus you
- can avoid passing the <literal>-p</literal> argument to
- tools by using this configuration file name in place of
- <filename>persistence.xml</filename>. See
- <xref linkend="ref_guide_conf"/> in the Reference Guide
- for details on OpenJPA configuration.
- </para>
- </note>
- </listitem>
- </orderedlist>
- <section id="jpa_tutorial_chapter2_datastore">
- <title>Configuring the Datastore</title>
- <para>
- Now that we've compiled the source files and enhanced the
- persistent classes, we're ready to set up the database.
- <ulink url="http://hsqldb.sourceforge.net">Hypersonic SQL</ulink>,
- a pure Java relational database, is included in the OpenJPA
- distribution.
- We have included this database because it is simple to set up and
- has a small memory footprint; however, you can use this tutorial
- with any of the relational databases that we support. You can also
- write your own plugin for any database that we do not support. For
- the sake of simplicity, this tutorial only describes how to set up
- connectivity to a Hypersonic SQL database. For more
- information on how to connect to a different database or
- how to add support for other databases, see
- <xref linkend="ref_guide_dbsetup"/> of the
- Reference Guide.
- </para>
- <orderedlist>
- <listitem>
- <para><indexterm><primary>mappingtool</primary></indexterm>
- Create the object-relational mappings and database schema.
- </para>
- <programlisting format="linespecific">
+Now that we've compiled the source files and enhanced the persistent classes,
+we're ready to set up the database. <ulink url="http://hsqldb.sourceforge.net">
+Hypersonic SQL</ulink>, a pure Java relational database, is included in the
+OpenJPA distribution. We have included this database because it is simple to set
+up and has a small memory footprint; however, you can use this tutorial with any
+of the relational databases that we support. You can also write your own plugin
+for any database that we do not support. For the sake of simplicity, this
+tutorial only describes how to set up connectivity to a Hypersonic SQL database.
+For more information on how to connect to a different database or how to add
+support for other databases, see <xref linkend="ref_guide_dbsetup"></xref> of
+the Reference Guide.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>
+ mappingtool
+ </primary>
+ </indexterm>
+Create the object-relational mappings and database schema.
+ </para>
+<programlisting>
mappingtool -p persistence.xml Animal.java Dog.java
</programlisting>
- <para>
- This command propagates the necessary schema for the
- specified classes to the database configured in
- <filename>persistence.xml</filename>. If you are
- using the default Hypersonic SQL setup, the first time you
- run the mapping tool Hypersonic will create
- <filename>tutorial_database.properties</filename> and
- <filename>tutorial_database.script</filename> database
- files in your current directory. To
- delete the database, just delete these files.
- </para>
- <para>
- By default, JPA uses object-relational mapping
- information stored in annotations in your source files.
- <xref linkend="jpa_overview_mapping"/> of the
- JPA Overview will help you understand mapping
- annotations.
- Additionally, <xref linkend="ref_guide_mapping"/> of the
- Reference Guide describes your other mapping options in
- detail.
- </para>
- <para>
- </para>
- <para>
- If you are curious, you can view the schema OpenJPA
- created for the tutorial classes with OpenJPA's schema tool:
- </para>
- <programlisting format="linespecific">
+ <para>
+This command propagates the necessary schema for the specified classes to the
+database configured in <filename>persistence.xml</filename>. If you are using
+the default Hypersonic SQL setup, the first time you run the mapping tool
+Hypersonic will create <filename>tutorial_database.properties</filename> and
+<filename>tutorial_database.script</filename> database files in your current
+directory. To delete the database, just delete these files.
+ </para>
+ <para>
+By default, JPA uses object-relational mapping information stored in annotations
+in your source files. <xref linkend="jpa_overview_mapping"></xref> of the JPA
+Overview will help you understand mapping annotations. Additionally,
+<xref linkend="ref_guide_mapping"></xref> of the Reference Guide describes your
+other mapping options in detail.
+ </para>
+ <para>
+ </para>
+ <para>
+If you are curious, you can view the schema OpenJPA created for the tutorial
+classes with OpenJPA's schema tool:
+ </para>
+<programlisting>
schematool -p persistence.xml -a reflect -f tmp.schema
</programlisting>
- <para>
- This will create a <filename>tmp.schema</filename> file
- with an XML representation of the database schema. The
- XML should be self explanatory; see
- <xref linkend="ref_guide_schema_xml"/>
- of the Reference Guide for details. You may delete the
- <filename>tmp.schema</filename> file before proceeding.
- </para>
- </listitem>
- <listitem>
- <para>Populate the database with sample data.</para>
- <programlisting format="linespecific">
+ <para>
+This will create a <filename>tmp.schema</filename> file with an XML
+representation of the database schema. The XML should be self explanatory; see
+<xref linkend="ref_guide_schema_xml"></xref> of the Reference Guide for details.
+You may delete the <filename>tmp.schema</filename> file before proceeding.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Populate the database with sample data.
+ </para>
+<programlisting>
java tutorial.persistence.SeedDatabase
</programlisting>
- </listitem>
- </orderedlist>
- <para>
- Congratulations! You have now created an JPA-accessible
- persistent store, and seeded it with some sample data.
- </para>
- </section>
+ </listitem>
+ </orderedlist>
+ <para>
+Congratulations! You have now created an JPA-accessible persistent store, and
+seeded it with some sample data.
+ </para>
+ </section>
</section>
<section id="jpa_tutorial_chapter3">
- <title>Inventory Maintenance</title>
- <para>
- The most important element of a successful pet store product, say the
- experts, is an inventory maintenance mechanism. So, let's work on the
- <classname>Animal</classname> and <classname>Dog</classname> classes a
- bit to permit user interaction with the database.
- </para>
- <para>
- This chapter should familiarize you with some of the basics of the
- <ulink url="../../ejb-3_0-pr-spec-persistence.pdf">JPA
- specification</ulink> and the mechanics of compiling and enhancing
- persistent classes. You will also become familiar with the mapping
- tool for propagating the persistent schema into the database.
- </para>
- <para>
- First, let's add some code to
- <filename>AnimalMaintenance.java</filename> that allows us to examine
- the animals currently in the database.
- </para>
- <orderedlist>
- <listitem>
- <para>
- Add code to <filename>AnimalMaintenance.java</filename>.
- </para>
- <para>
- Modify the <methodname>getAnimals</methodname> method of
- <filename>AnimalMaintenance.java</filename> to look like this:
- </para>
- <programlisting format="linespecific">
+ <title>
+ Inventory Maintenance
+ </title>
+ <para>
+The most important element of a successful pet store product, say the experts,
+is an inventory maintenance mechanism. So, let's work on the <classname>Animal
+</classname> and <classname>Dog</classname> classes a bit to permit user
+interaction with the database.
+ </para>
+ <para>
+This chapter should familiarize you with some of the basics of the
+<ulink url="../../ejb-3_0-pr-spec-persistence.pdf">JPA specification</ulink> and
+the mechanics of compiling and enhancing persistent classes. You will also
+become familiar with the mapping tool for propagating the persistent schema into
+the database.
+ </para>
+ <para>
+First, let's add some code to <filename>AnimalMaintenance.java</filename> that
+allows us to examine the animals currently in the database.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Add code to <filename>AnimalMaintenance.java</filename>.
+ </para>
+ <para>
+Modify the <methodname>getAnimals</methodname> method of <filename>
+AnimalMaintenance.java</filename> to look like this:
+ </para>
+<programlisting>
/**
* Return a list of animals that match the specified query filter.
*
@@ -512,82 +512,79 @@
return query.getResultList ();
}
</programlisting>
- </listitem>
- <listitem>
- <para>
- Compile <filename>AnimalMaintenance.java</filename>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Compile <filename>AnimalMaintenance.java</filename>.
+ </para>
+<programlisting>
javac AnimalMaintenance.java
</programlisting>
- </listitem>
- <listitem>
- <para>Take a look at the animals in the database.</para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Take a look at the animals in the database.
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance list Animal
</programlisting>
- <para>
- Notice that <methodname>list</methodname> optionally takes a
- query filter. Let's explore the database some more, this time
- using filters:
- </para>
- <programlisting format="linespecific">
+ <para>
+Notice that <methodname>list</methodname> optionally takes a query filter. Let's
+explore the database some more, this time using filters:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance list "select a from Animal a where a.name = 'Binney'"
java tutorial.persistence.AnimalMaintenance list "select a from Animal a where a.price <= 50"
</programlisting>
- <para>
- The Java Persistence Query Language (JPQL) is designed to look
- and behave much like an object oriented SQL dialect. The
- <literal>name</literal> and <literal>price</literal> fields
- identified in the above queries map to the member fields of
- those names in <classname>
- tutorial.persistence.Animal</classname>.
- More details on JPQL syntax is available in
- <xref linkend="jpa_overview_query"/> of the JPA Overview.
- </para>
- </listitem>
- </orderedlist>
- <para>
- Great! Now that we can see the contents of the database,
- let's add some code that lets us add and remove animals.
- </para>
- <section id="jpa_tutorial_chapter3_persist">
- <title>Persisting Objects</title>
- <para>
- As new dogs are born or acquired, the store owner will
- need to add new records to the inventory database. In this
- section, we'll write the code to handle additions through
- the <classname>tutorial.persistence.AnimalMaintenance</classname>
- class.
- </para>
- <para>
- This section will familiarize you with the mechanism for
- storing persistent instances in a JPA entity
- manager. We will create a new dog, obtain a
- <classname>Transaction</classname> from a
- <classname>EntityManager</classname>, and, within the
- transaction, make the new dog object persistent.
- </para>
- <para><classname>tutorial.persistence.AnimalMaintenance</classname>
- provides a reflection-based facility for creating any type of
- animal, provided that the animal has a two-argument constructor
- whose first argument corresponds to the name of the animal
- and whose second argument is an implementation-specific
- primitive. This reflection-based system is in place to keep this
- tutorial short and remove repetitive creation mechanisms. It is
- not a required part of the JPA specification.
- </para>
- <orderedlist>
- <listitem>
- <para>Add the following code to <filename>
- AnimalMaintenance.java</filename>.
- </para>
- <para>
- Modify the <methodname>persistObject</methodname> method of
- <filename>AnimalMaintenance.java</filename> to look like
- this:
- </para>
- <programlisting format="linespecific">
+ <para>
+The Java Persistence Query Language (JPQL) is designed to look and behave much
+like an object oriented SQL dialect. The <literal>name</literal> and <literal>
+price</literal> fields identified in the above queries map to the member fields
+of those names in <classname> tutorial.persistence.Animal</classname>. More
+details on JPQL syntax is available in <xref linkend="jpa_overview_query">
+</xref> of the JPA Overview.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+Great! Now that we can see the contents of the database, let's add some code
+that lets us add and remove animals.
+ </para>
+ <section id="jpa_tutorial_chapter3_persist">
+ <title>
+ Persisting Objects
+ </title>
+ <para>
+As new dogs are born or acquired, the store owner will need to add new records
+to the inventory database. In this section, we'll write the code to handle
+additions through the <classname>tutorial.persistence.AnimalMaintenance
+</classname> class.
+ </para>
+ <para>
+This section will familiarize you with the mechanism for storing persistent
+instances in a JPA entity manager. We will create a new dog, obtain a
+<classname>Transaction</classname> from a <classname>EntityManager</classname>,
+and, within the transaction, make the new dog object persistent.
+ </para>
+ <para>
+<classname>tutorial.persistence.AnimalMaintenance</classname> provides a
+reflection-based facility for creating any type of animal, provided that the
+animal has a two-argument constructor whose first argument corresponds to the
+name of the animal and whose second argument is an implementation-specific
+primitive. This reflection-based system is in place to keep this tutorial short
+and remove repetitive creation mechanisms. It is not a required part of the JPA
+specification.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Add the following code to <filename> AnimalMaintenance.java</filename>.
+ </para>
+ <para>
+Modify the <methodname>persistObject</methodname> method of <filename>
+AnimalMaintenance.java</filename> to look like this:
+ </para>
+<programlisting>
/**
* Performs the actual JPA work of putting <code>object</code>
* into the data store.
@@ -607,75 +604,68 @@
System.out.println ("Added " + object);
}
</programlisting>
- <note>
- <para>In the above code, we pass in an
- <classname>EntityManager</classname>.
- <classname>EntityManager</classname>s may be either
- container managed or application managed. In this tutorial,
- because we're operating outside a container, we're using
- application managed <classname>EntityManager</classname>s.
- In managed environments,
- <classname>EntityManager</classname>s are typically
- container managed, and thus injected or looked up via JNDI.
- Application managed <classname>EntityManager</classname>s
- can be used in both managed and unmanaged environments, and
- are created by an
- <classname>EntityManagerFactory</classname>. An
- <classname>EntityManagerFactory</classname> can be obtained
- from the
- <classname>javax.persistence.Persistence</classname> class.
- This class provides some convenience methods for
- obtaining an <classname>EntityManagerFactory</classname>.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>
- Recompile <filename>AnimalMaintenance.java</filename>.
- </para>
- <programlisting format="linespecific">
+ <note>
+ <para>
+In the above code, we pass in an <classname>EntityManager</classname>.
+<classname>EntityManager</classname>s may be either container managed or
+application managed. In this tutorial, because we're operating outside a
+container, we're using application managed <classname>EntityManager</classname>
+s. In managed environments, <classname>EntityManager</classname>s are typically
+container managed, and thus injected or looked up via JNDI. Application managed
+<classname>EntityManager</classname>s can be used in both managed and unmanaged
+environments, and are created by an <classname>EntityManagerFactory</classname>
+. An <classname>EntityManagerFactory</classname> can be obtained from the
+<classname>javax.persistence.Persistence</classname> class. This class provides
+some convenience methods for obtaining an <classname>EntityManagerFactory
+</classname>.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+Recompile <filename>AnimalMaintenance.java</filename>.
+ </para>
+<programlisting>
javac AnimalMaintenance.java
</programlisting>
- </listitem>
- </orderedlist>
- <para>
- You now have a mechanism for adding new dogs to the database. Go
- ahead and add some by running
- <command>java tutorial.persistence.AnimalMaintenance add Dog <name> <price></command>
- For example:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ </orderedlist>
+ <para>
+You now have a mechanism for adding new dogs to the database. Go ahead and add
+some by running <command>java tutorial.persistence.AnimalMaintenance add Dog
+<name> <price></command> For example:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance add Dog Fluffy 35
</programlisting>
- <para>
- You can view the contents of the database with:
- </para>
- <programlisting format="linespecific">
+ <para>
+You can view the contents of the database with:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance list Dog
</programlisting>
- </section>
- <section id="jpa_tutorial_chapter3_delete">
- <title>Deleting Objects</title>
- <para>
- What if someone decides to buy one of the dogs? The store owner
- will need to remove that animal from the database, since it is no
- longer in the inventory.
- </para>
- <para>
- This section demonstrates how to remove data from the datastore.
- </para>
- <orderedlist>
- <listitem>
+ </section>
+ <section id="jpa_tutorial_chapter3_delete">
+ <title>
+ Deleting Objects
+ </title>
<para>
- Add the following code to <filename>AnimalMaintenance.java
- </filename>.
- </para>
- <para>
- Modify the <methodname>deleteObjects</methodname> method of
- <filename>AnimalMaintenance.java</filename> to look like
- this:
- </para>
- <programlisting format="linespecific">
+What if someone decides to buy one of the dogs? The store owner will need to
+remove that animal from the database, since it is no longer in the inventory.
+ </para>
+ <para>
+This section demonstrates how to remove data from the datastore.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Add the following code to <filename>AnimalMaintenance.java</filename>.
+ </para>
+ <para>
+Modify the <methodname>deleteObjects</methodname> method of <filename>
+AnimalMaintenance.java</filename> to look like this:
+ </para>
+<programlisting>
/**
* Performs the actual JPA work of removing
* <code>objects</code> from the datastore.
@@ -700,283 +690,280 @@
em.getTransaction ().commit ();
}
</programlisting>
- </listitem>
- <listitem>
- <para>
- Recompile <filename>AnimalMaintenance.java</filename>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Recompile <filename>AnimalMaintenance.java</filename>.
+ </para>
+<programlisting>
javac AnimalMaintenance.java
</programlisting>
- </listitem>
- <listitem>
- <para>Remove some animals from the database.</para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Remove some animals from the database.
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance remove <query>
</programlisting>
+ <para>
+Where <replaceable><query></replaceable> is a query string like those used
+for listing animals above.
+ </para>
+ </listitem>
+ </orderedlist>
<para>
- Where <replaceable><query></replaceable> is a query
- string like those used for listing animals above.
- </para>
- </listitem>
- </orderedlist>
- <para>
- All right. We now have a basic pet shop inventory
- management system. From this base, we will add some of the
- more advanced features suggested by our industry experts.
- </para>
- </section>
+All right. We now have a basic pet shop inventory management system. From this
+base, we will add some of the more advanced features suggested by our industry
+experts.
+ </para>
+ </section>
</section>
<section id="jpa_tutorial_chapter4">
- <title>Inventory Growth</title>
- <para>
- Now that we have the basic pet store framework in place, let's add
- support for the next pet in our list: the rabbit. The rabbit is a bit
- different than the dog; pet stores sell them all for the same price,
- but gender is critically important since rabbits reproduce rather
- easily and quickly. Let's put together a class representing a rabbit.
- </para>
- <para>
- In this chapter, you will see some more queries and write a
- bidirectional relation between objects.
- </para>
- <para>
- Provided with this tutorial is a file called
- <filename>Rabbit.java</filename> which contains a sample
- <classname>Rabbit</classname> implementation.
- </para>
- <orderedlist>
- <listitem>
- <para>
- Examine <filename>Rabbit.java</filename>.
- </para>
- </listitem>
- <listitem>
- <para>
- The Rabbit class above contains a bidirectional
- relationship between parents and children. From the Java side
- of things, a bidirectional relationship is simply a
- pair of fields that are conceptually linked. There is no
- special Java work necessary to express bidirectionality.
- However, you must identify the relationship as bidirectional
- using JPA <link linkend="jpa_overview_meta">
- annotations</link> so the mapping tool can create the most
- efficient schema.
- </para>
- <para>
- Insert this snippet of code immediately
- <emphasis>before</emphasis> the <literal>children</literal>
- field declaration in the <filename>Rabbit.java</filename> file.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Inventory Growth
+ </title>
+ <para>
+Now that we have the basic pet store framework in place, let's add support for
+the next pet in our list: the rabbit. The rabbit is a bit different than the
+dog; pet stores sell them all for the same price, but gender is critically
+important since rabbits reproduce rather easily and quickly. Let's put together
+a class representing a rabbit.
+ </para>
+ <para>
+In this chapter, you will see some more queries and write a bidirectional
+relation between objects.
+ </para>
+ <para>
+Provided with this tutorial is a file called <filename>Rabbit.java</filename>
+which contains a sample <classname>Rabbit</classname> implementation.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Examine <filename>Rabbit.java</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+The Rabbit class above contains a bidirectional relationship between parents and
+children. From the Java side of things, a bidirectional relationship is simply a
+pair of fields that are conceptually linked. There is no special Java work
+necessary to express bidirectionality. However, you must identify the
+relationship as bidirectional using JPA <link linkend="jpa_overview_meta">
+annotations</link> so the mapping tool can create the most efficient schema.
+ </para>
+ <para>
+Insert this snippet of code immediately <emphasis>before</emphasis> the
+<literal>children</literal> field declaration in the <filename>Rabbit.java
+</filename> file.
+ </para>
+<programlisting>
@ManyToMany
@JoinTable(name="RABBIT_CHILDREN",
joinColumns=@JoinColumn(name="PARENT_ID"),
inverseJoinColumns=@JoinColumn(name="CHILD_ID"))
</programlisting>
- <para>
- The <literal>@ManyToMany</literal> annotation indicates that
- <literal>children</literal> is one side of a many-to-many
- relation. <literal>@JoinTable</literal> describes how this
- relation maps to a database join table. The annotation's
- <literal>joinColumns</literal> name the join table's foreign
- key columns linking to the owning instance (the parent). In
- this case, column <literal>RABBIT_CHILDREN.PARENT_ID</literal>
- is a foreign key to the parent's <literal>ID</literal> primary
- key column. Similarly, the <literal>inverseJoinColumns
- </literal> attribute denotes the foreign key columns linking to
- the collection elements (the children).
- For more details on the <literal>@JoinTable</literal>
- annotation, see <xref linkend="jpa_overview_mapping"/> of the
- JPA Overview.
- </para>
- <para>
- Now we'll map the other side of this bidirectional relation,
- the <literal>parents</literal> field.
- Insert the following snippet of code immediately
- <emphasis>before</emphasis> the <command>parents</command>
- field declaration in the <filename>Rabbit.java</filename> file.
- The <literal>mappedBy</literal> attribute identifies the name
- of the owning side of the relation.
- </para>
- <programlisting format="linespecific">
+ <para>
+The <literal>@ManyToMany</literal> annotation indicates that <literal>children
+</literal> is one side of a many-to-many relation. <literal>@JoinTable</literal>
+describes how this relation maps to a database join table. The annotation's
+<literal>joinColumns</literal> name the join table's foreign key columns linking
+to the owning instance (the parent). In this case, column <literal>
+RABBIT_CHILDREN.PARENT_ID</literal> is a foreign key to the parent's <literal>
+ID</literal> primary key column. Similarly, the <literal>inverseJoinColumns
+</literal> attribute denotes the foreign key columns linking to the collection
+elements (the children). For more details on the <literal>@JoinTable</literal>
+annotation, see <xref linkend="jpa_overview_mapping"></xref> of the JPA
+Overview.
+ </para>
+ <para>
+Now we'll map the other side of this bidirectional relation, the <literal>
+parents</literal> field. Insert the following snippet of code immediately
+<emphasis>before</emphasis> the <command>parents</command> field declaration in
+the <filename>Rabbit.java</filename> file. The <literal>mappedBy</literal>
+attribute identifies the name of the owning side of the relation.
+ </para>
+<programlisting>
@ManyToMany(mappedBy="children")
</programlisting>
- </listitem>
- <listitem>
- <para>
- Compile <filename>Rabbit.java</filename>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Compile <filename>Rabbit.java</filename>.
+ </para>
+<programlisting>
javac Rabbit.java
</programlisting>
- </listitem>
- <listitem>
- <para>
- Enhance the <classname>Rabbit</classname> class.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Enhance the <classname>Rabbit</classname> class.
+ </para>
+<programlisting>
openjpac -p persistence.xml Rabbit.java
</programlisting>
- </listitem>
- <listitem>
- <para>
- Refresh the object-relational mappings and database schema.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Refresh the object-relational mappings and database schema.
+ </para>
+<programlisting>
mappingtool -p persistence.xml Rabbit.java
</programlisting>
- </listitem>
- </orderedlist>
- <para>
- Now that we have a Rabbit class, let's get some preliminary rabbit
- data into the database.
- </para>
- <orderedlist>
- <listitem>
- <para>
- Add a <literal><class></literal> entry for <classname>
- Rabbit</classname> to
- <filename>../../META-INF/persistence.xml</filename>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ </orderedlist>
+ <para>
+Now that we have a Rabbit class, let's get some preliminary rabbit data into the
+database.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Add a <literal><class></literal> entry for <classname> Rabbit</classname>
+to <filename>../../META-INF/persistence.xml</filename>.
+ </para>
+<programlisting>
<class>tutorial.persistence.Rabbit</class>
</programlisting>
- </listitem>
- <listitem>
- <para>Create some rabbits.</para>
- <para>
- Run the following commands a few times to add some male
- and female rabbits to the database:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Create some rabbits.
+ </para>
+ <para>
+Run the following commands a few times to add some male and female rabbits to
+the database:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance add Rabbit <name> false
java tutorial.persistence.AnimalMaintenance add Rabbit <name> true
</programlisting>
- <para>
- Now run some breeding iterations.
- </para>
- <programlisting format="linespecific">
+ <para>
+Now run some breeding iterations.
+ </para>
+<programlisting>
java tutorial.persistence.Rabbit breed 2
</programlisting>
- </listitem>
- <listitem>
- <para>Look at your new rabbits.</para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Look at your new rabbits.
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance list Rabbit
java tutorial.persistence.AnimalMaintenance details "select r from Rabbit r where r.name = '<name>'"
</programlisting>
- </listitem>
- </orderedlist>
+ </listitem>
+ </orderedlist>
</section>
<section id="jpa_tutorial_chapter5">
- <title>Behavioral Analysis</title>
- <para>
- Often, pet stores sell snakes as well as rabbits and dogs. Pet stores
- are primarily concerned with a snake's length; much like rabbits, pet
- store operators usually sell them all for a flat rate.
- </para>
- <para>
- This chapter demonstrates more queries, schema manipulation,
- and additional relation types.
- </para>
- <para>
- Provided with this tutorial is a file called <filename>Snake.java
- </filename> which contains a sample <classname>Snake</classname>
- implementation. Let's get it compiled and loaded:
- </para>
- <orderedlist>
- <listitem>
- <para>
- Examine and compile <filename>Snake.java</filename>.
- </para>
- <programlisting format="linespecific">
+ <title>
+ Behavioral Analysis
+ </title>
+ <para>
+Often, pet stores sell snakes as well as rabbits and dogs. Pet stores are
+primarily concerned with a snake's length; much like rabbits, pet store
+operators usually sell them all for a flat rate.
+ </para>
+ <para>
+This chapter demonstrates more queries, schema manipulation, and additional
+relation types.
+ </para>
+ <para>
+Provided with this tutorial is a file called <filename>Snake.java</filename>
+which contains a sample <classname>Snake</classname> implementation. Let's get
+it compiled and loaded:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Examine and compile <filename>Snake.java</filename>.
+ </para>
+<programlisting>
javac Snake.java
</programlisting>
- </listitem>
- <listitem>
- <para>Enhance the class.</para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Enhance the class.
+ </para>
+<programlisting>
openjpac -p persistence.xml Snake.java
</programlisting>
- </listitem>
- <listitem>
- <para>Refresh the mappings and database.</para>
- <para>
- As we have created a new persistent class, we must
- map it to the database and change the schema to match. So
- run the mapping tool:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Refresh the mappings and database.
+ </para>
+ <para>
+As we have created a new persistent class, we must map it to the database and
+change the schema to match. So run the mapping tool:
+ </para>
+<programlisting>
mappingtool -p persistence.xml Snake.java
</programlisting>
- </listitem>
- <listitem>
- <para>
- Add a <literal><class></literal> entry for <classname>
- Snake</classname> to
- <filename>../../META-INF/persistence.xml</filename>.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Add a <literal><class></literal> entry for <classname> Snake</classname>
+to <filename>../../META-INF/persistence.xml</filename>.
+ </para>
+<programlisting>
<class>tutorial.persistence.Snake</class>
</programlisting>
- </listitem>
- </orderedlist>
- <para>
- Once you have compiled everything, add a few snakes to the database
- using:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ </orderedlist>
+ <para>
+Once you have compiled everything, add a few snakes to the database using:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance add Snake "name" <length>
</programlisting>
- <para>
- Where <replaceable><length></replaceable> is the length in feet
- for the new snake. To see the new snakes in the database, run:
- </para>
- <programlisting format="linespecific">
+ <para>
+Where <replaceable><length></replaceable> is the length in feet for the
+new snake. To see the new snakes in the database, run:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance list Snake
</programlisting>
- <para>
- Unfortunately for the massively developing rabbit population, snakes
- often eat rabbits. Any good inventory system should be able to capture
- this behavior. So, let's add some code to <filename>Snake.java
- </filename> to support the snake's eating behavior.
- </para>
- <para>
- First, let's modify <filename>Snake.java</filename> to contain a
- list of eaten rabbits.
- </para>
- <orderedlist>
- <listitem>
- <para>
- Add the following code snippets to
- <filename>Snake.java</filename>.
- </para>
- <programlisting format="linespecific">
+ <para>
+Unfortunately for the massively developing rabbit population, snakes often eat
+rabbits. Any good inventory system should be able to capture this behavior. So,
+let's add some code to <filename>Snake.java</filename> to support the snake's
+eating behavior.
+ </para>
+ <para>
+First, let's modify <filename>Snake.java</filename> to contain a list of eaten
+rabbits.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+Add the following code snippets to <filename>Snake.java</filename>.
+ </para>
+<programlisting>
// This list will be persisted into the database as
// a one-to-many relation.
@OneToMany(mappedBy="eater")
private Set<Rabbit> giTract = new HashSet<Rabbit> ();
</programlisting>
- <para>
- Note that we specified a <literal>mappedBy</literal>
- attribute in this example. This is because the relation is
- bidirectional; that is, the rabbit has knowledge of which
- snake ate it. We could have left out the
- <literal>eater</literal> field and instead created a
- standard unidirectional relation. In fact, in a bidirectional
- many-to-one relation, the many side must always be the owner.
- </para>
- <para>
- For more information on types of relations, see
- <xref linkend="jpa_overview_mapping_field"/> of the
- JPA Overview.
- </para>
- <para>
- Modify the <literal>toString (boolean)</literal> method to
- output the giTract list.
- </para>
- <programlisting format="linespecific">
+ <para>
+Note that we specified a <literal>mappedBy</literal> attribute in this example.
+This is because the relation is bidirectional; that is, the rabbit has knowledge
+of which snake ate it. We could have left out the <literal>eater</literal> field
+and instead created a standard unidirectional relation. In fact, in a
+bidirectional many-to-one relation, the many side must always be the owner.
+ </para>
+ <para>
+For more information on types of relations, see
+<xref linkend="jpa_overview_mapping_field"></xref> of the JPA Overview.
+ </para>
+ <para>
+Modify the <literal>toString (boolean)</literal> method to output the giTract
+list.
+ </para>
+<programlisting>
public String toString (boolean detailed)
{
StringBuffer buf = new StringBuffer (1024);
@@ -996,10 +983,10 @@
return buf.toString ();
}
</programlisting>
- <para>
- Add the following methods.
- </para>
- <programlisting format="linespecific">
+ <para>
+Add the following methods.
+ </para>
+<programlisting>
/**
* Kills the specified rabbit and eats it.
*/
@@ -1075,13 +1062,13 @@
+ "\"snakequery\"");
}
</programlisting>
- </listitem>
- <listitem>
- <para>
- Add an <literal>eater</literal> field to
- <filename>Rabbit.java</filename>, and a getter and setter.
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Add an <literal>eater</literal> field to <filename>Rabbit.java</filename>, and
+a getter and setter.
+ </para>
+<programlisting>
@ManyToOne @JoinColumn(name="EATER_ID")
private Snake eater;
@@ -1098,607 +1085,443 @@
eater = snake;
}
</programlisting>
- <para>
- The <literal>@ManyToOne</literal> annotation indicates that this
- is the many side of the bidirectional relation. The many side
- must always be the owner in this type of relation. The
- <literal>@JoinColumn</literal> describes the foreign key
- that joins the rabbit table to the snake table. The rabbit
- table has an <literal>EATER_ID</literal> column that is a
- foreign key to the <literal>ID</literal> primary key column
- of the snake table.
- </para>
- </listitem>
- <listitem>
- <para>
- Compile <filename>Snake.java</filename> and
- <filename>Rabbit.java</filename> and enhance the classes.
- </para>
- <programlisting format="linespecific">
+ <para>
+The <literal>@ManyToOne</literal> annotation indicates that this is the many
+side of the bidirectional relation. The many side must always be the owner in
+this type of relation. The <literal>@JoinColumn</literal> describes the foreign
+key that joins the rabbit table to the snake table. The rabbit table has an
+<literal>EATER_ID</literal> column that is a foreign key to the <literal>ID
+</literal> primary key column of the snake table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Compile <filename>Snake.java</filename> and <filename>Rabbit.java</filename> and
+enhance the classes.
+ </para>
+<programlisting>
javac Snake.java Rabbit.java
openjpac -p persistence.xml Snake.java Rabbit.java
</programlisting>
- </listitem>
- <listitem>
- <para>Refresh the mappings and database.</para>
- <programlisting format="linespecific">
+ </listitem>
+ <listitem>
+ <para>
+Refresh the mappings and database.
+ </para>
+<programlisting>
mappingtool -p persistence.xml Snake.java Rabbit.java
</programlisting>
- </listitem>
- </orderedlist>
- <para>
- Now, experiment with the following commands:
- </para>
- <programlisting format="linespecific">
+ </listitem>
+ </orderedlist>
+ <para>
+Now, experiment with the following commands:
+ </para>
+<programlisting>
java tutorial.persistence.Snake eat "select s from Snake s where s.name = '<name>'"
java tutorial.persistence.AnimalMaintenance details "select s from Snake s where s.name = '<name>'"
</programlisting>
- <section id="jpa_tutorial_chapter5_query">
- <title>Complex Queries</title>
- <para>
- Imagine that one of the snakes in the database was named Killer.
- To find out which rabbits Killer ate, we could run either of the
- following two queries:
- </para>
- <programlisting format="linespecific">
+ <section id="jpa_tutorial_chapter5_query">
+ <title>
+ Complex Queries
+ </title>
+ <para>
+Imagine that one of the snakes in the database was named Killer. To find out
+which rabbits Killer ate, we could run either of the following two queries:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance details "select s from Snake s where s.name = 'Killer'"
java tutorial.persistence.AnimalMaintenance list "select r from Rabbit r where r.eater.name = 'Killer'"
</programlisting>
- <para>
- The first query is snake-centric - the query runs against the
- <classname>Snake</classname> class, looking for all snakes named
- Killer and providing a detailed listing of them. The second is
- rabbit-centric - it examines the rabbits in the database for
- instances whose <literal>eater</literal> is named Killer.
- This second query demonstrates the that simple java 'dot' syntax
- is used when traversing an to-one field in a query.
- </para>
- <para>
- It is also possible to traverse collection fields. Imagine that
- there was a rabbit called Roger in the datastore and that one of
- the snakes ate it. In order to determine who ate Roger Rabbit, you
- could run a query like this:
- </para>
- <programlisting format="linespecific">
+ <para>
+The first query is snake-centric - the query runs against the <classname>Snake
+</classname> class, looking for all snakes named Killer and providing a detailed
+listing of them. The second is rabbit-centric - it examines the rabbits in the
+database for instances whose <literal>eater</literal> is named Killer. This
+second query demonstrates the that simple java 'dot' syntax is used when
+traversing an to-one field in a query.
+ </para>
+ <para>
+It is also possible to traverse collection fields. Imagine that there was a
+rabbit called Roger in the datastore and that one of the snakes ate it. In order
+to determine who ate Roger Rabbit, you could run a query like this:
+ </para>
+<programlisting>
java tutorial.persistence.AnimalMaintenance details "select s from Snake s inner join s.giTract r where r.name = 'Roger'"
</programlisting>
- </section>
+ </section>
</section>
<section id="jpa_tutorial-chapter6">
- <title>Extra Features</title>
- <para>
- Congratulations! You are now the proud author of a pet store inventory
- suite. Now that you have all the major features of the pet store
- software implemented, it's time to add some extra features. You're on
- your own; think of some features that you think a pet store should have,
- or just explore the features of JPA.
- </para>
- <para>
- Here are a couple of suggestions to get you started:
- </para>
- <itemizedlist>
- <listitem>
- <para>Animal pricing.</para>
- <para>
- Modify <classname>Animal</classname> to contain an inventory
- cost and a resale price. Calculate the real dollar amount
- eaten by the snakes (the sum of the inventory costs of all the
- consumed rabbits), and the cost assuming that all the eaten
- rabbits would have been sold had they been alive. Ignore the
- fact that the rabbits, had they lived, would have created more
- rabbits, and the implications of the reduced food costs due to
- the not-quite-as-hungry snakes and the smaller number of
- rabbits.
- </para>
- </listitem>
- <listitem>
- <para>Dog categorization.</para>
- <para>
- Modify <classname>Dog</classname> to have a
- relation to a new class called <classname>Breed</classname>,
- which contains a name identifying the breed of the dog and a
- description of the breed. Put together an admin tool for
- breeds and for associating dogs and breeds.
- </para>
- </listitem>
- </itemizedlist>
+ <title>
+ Extra Features
+ </title>
+ <para>
+Congratulations! You are now the proud author of a pet store inventory suite.
+Now that you have all the major features of the pet store software implemented,
+it's time to add some extra features. You're on your own; think of some features
+that you think a pet store should have, or just explore the features of JPA.
+ </para>
+ <para>
+Here are a couple of suggestions to get you started:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+Animal pricing.
+ </para>
+ <para>
+Modify <classname>Animal</classname> to contain an inventory cost and a resale
+price. Calculate the real dollar amount eaten by the snakes (the sum of the
+inventory costs of all the consumed rabbits), and the cost assuming that all the
+eaten rabbits would have been sold had they been alive. Ignore the fact that the
+rabbits, had they lived, would have created more rabbits, and the implications
+of the reduced food costs due to the not-quite-as-hungry snakes and the smaller
+number of rabbits.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+Dog categorization.
+ </para>
+ <para>
+Modify <classname>Dog</classname> to have a relation to a new class called
+<classname>Breed</classname>, which contains a name identifying the breed of
+the dog and a description of the breed. Put together an admin tool for breeds
+and for associating dogs and breeds.
+ </para>
+ </listitem>
+ </itemizedlist>
</section>
- </section>
-<!-- ### EJBDOC
- &ejb3-reverse-tutorial.xml;
- -->
- <section id="jpa_j2ee_tutorial">
- <title>J2EE Tutorial</title>
+ </section>
+ <section id="jpa_j2ee_tutorial">
+ <title>
+ J2EE Tutorial
+ </title>
<para>
- By deploying OpenJPA into a J2EE environment, you can maintain the
- simplicity and performance of OpenJPA, while leveraging J2EE
- technologies such as container managed transactions (JTA/JTS),
- enterprise objects with remote invocation (EJB), and managed
- deployment of multi-tiered applications via an application
- server. This tutorial will demonstrate how to deploy OpenJPA-based
- J2EE applications and showcase some basic enterprise JPA
- design techniques. The tutorial's sample application models
- a basic garage catalog system. While the application is
- relatively trivial, the code has been constructed to illustrate
- simple patterns and solutions to common problems when using
- OpenJPA in an enterprise environment.
- </para>
+By deploying OpenJPA into a J2EE environment, you can maintain the simplicity
+and performance of OpenJPA, while leveraging J2EE technologies such as container
+managed transactions (JTA/JTS), enterprise objects with remote invocation (EJB),
+and managed deployment of multi-tiered applications via an application server.
+This tutorial will demonstrate how to deploy OpenJPA-based J2EE applications and
+showcase some basic enterprise JPA design techniques. The tutorial's sample
+application models a basic garage catalog system. While the application is
+relatively trivial, the code has been constructed to illustrate simple patterns
+and solutions to common problems when using OpenJPA in an enterprise
+environment.
+ </para>
<section id="jpa_j2ee_tutorial_requirements">
- <title>Prerequisites for the OpenJPA J2EE Tutorial</title>
- <para>
- This tutorial assumes that you have installed OpenJPA and
- setup your classpath according to the installation instructions
- appropriate for your platform. In addition, this
- tutorial requires that you have installed and configured a
- J2EE-compliant application server, such as WebLogic or JBoss,
- running on JDK 1.5. If you use a different
- application server not listed here, this tutorial may be adaptable to
- your application server with small changes; refer to your application
- server's documentation for any specific classpath and deployment
- descriptor requirements.
- </para>
- <para>
- This tutorial assumes a reasonable level of experience with
[... 757 lines stripped ...]