Scott, this looks like a great tutorial, but any files stored on ASF
servers must follow our license requirements, which includes all source
files must include the appropriate ASF License header.
So, I would ask two things of you:
1) update the tutorial files to include the required headers
http://www.apache.org/legal/src-headers.html
2) open a JIRA and attach the zip as an attachment and select the "Grant
license to ASF for inclusion in ASF works"
https://issues.apache.org/jira/browse/OPENJPA
Thanks,
Donald
On 1/21/10 5:38 PM, [email protected] wrote:
>
>
>
> Begin using OpenJPA - The Basics
>
> <http://cwiki.apache.org/confluence/display/openjpa/Begin+using+OpenJPA+-+The+Basics>
>
>
> Page *edited* by Scott Matthew Quint
> <http://cwiki.apache.org/confluence/display/[email protected]>
>
>
> Introduction
>
> OpenJPA is an open source implementation of the Java JPA (Java
> Persistence API) specification from Apache. JPA provides an agnostic
> Java-based API for storing and retrieving information to a backend
> database. It has a canonical query language named Java Persistence Query
> Language, or JPQL, that blends with the programming methods of Java and
> eliminates the need to tailor database queries for a particular
> database. However, JPA also supports native SQL which can be used for
> quick ports with a known backend database. This tutorial is designed to
> walk you through the steps of setting up a simple web application to use
> OpenJPA Geronimo and to transact the derby database that comes with
> Geronimo. The tutorial code uses a simple Java Server Page (JSP), backed
> up by some basic classes. It displays a table of inventory items and
> categories. In this tutorial, we will not dive into details regarding
> the JSP code. Its purpose is to be a window through which you can
> examine OpenJPA. The intended audience for this tutorial is those with
> some knowledge and understanding of the Java programming language and
> who are just beginning with OpenJPA. To start, you must download the
> following requirements and install them on your computer. For the
> purposes of this tutorial, we are using Eclipse as the IDE and Microsoft
> Windows as the operating system of choice.
>
>
> Prerequisites
>
> *Geronimo V2.2:* You can get it here
> <http://www.apache.org/dyn/closer.cgi/geronimo/2.2/geronimo-tomcat6-javaee5-2.2-bin.zip>.
> Download this file and unzip it to a permanent location. There is no
> installer. The server will run from the command line.
>
> *Java (J2SE) V1.6:* This tutorial was developed and tested with Java
> V1.6. If you don't already have Java V1.6 you can get the IBM JDK here
> <http://www.ibm.com/developerworks/java/jdk/> or the Sun JDK here
> <https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/viewproductdetail-start?productref=jdk-6u16-oth-...@cds-cds_developer>.
>
> *Eclipse V3.2 or later:* This version has annotation support included.
> Annotations play a large role in OpenJPA. Download
> <http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/galileo/SR1/eclipse-jee-galileo-SR1-win32.zip>Eclipse
> 3.2 or later.
>
> *Apache OpenJPA library:* For the purpose of implementing this tutorial
> you can select
> OpenJPA v1.2 or greater. You can download Apache OpenJPA
> <http://openjpa.apache.org/downloads.html> from the Apache site. Note
> that the Milestone (openjpa-all-2.0.0-M3.jar as of this writing) is an
> early release of OpenJPA 2.0 and may have some instabilities. No issues
> have been noted for the usage in this tutorial.
>
> *The tutorial code files*: These files
> </confluence/download/attachments/12320826/OpenJPAWebAppTutorial.zip?version=1>
> are provided with this tutorial. You will add them to your Eclipse project.
>
>
> Setup and Running the Sample
>
> Now, that you have all the prerequisites for this tutorial downloaded
> and installed, the following sections will walk you through the Eclipse
> project setup and the OpenJPA configuration. Make sure you read through
> and follow each part carefully.
>
>
> Setting up Eclipse
>
> After installing Eclipse, create a new project in a dedicated workspace
> for the tutorial. Complete the following setup instructions: First, make
> sure your Eclipse environment is updated and has the Geronimo plugin. If
> you do not know how to do that, follow the instructions found at the
> Geronimo website
> <http://geronimo.apache.org/geronimo-eclipse-plugin-installation-instructions.html>.
>
> 1. Create a new Java project in Eclipse called, *"OpenJPATutorial"*.
> * From the menu, select: *File->New->Enterprise Application
> Project*. (If *Enterprise Application Project* is not
> available as an option, select *Project* and then choose
> *Enterprise Application Project* from the list. Then click
> on the *Next* button).
> When the New Project settings dialog appears, use the
> following settings:
>
>
>
> 2. Under the *Target Runtime* section, select *Apache Geronimo v2.2*.
> * If you do not already have Geronimo setup in Eclipse then
> you will have to do so now. Click on the *New...* button.
> * If Apache Geronimo v2.2 does not appear in the list under
> *Apache*, click the *Download additional server adapters*
> link at the top right of the dialog. If the adapter does not
> appear in that list then follow the directions from the
> Geronimo site
>
> <http://geronimo.apache.org/geronimo-eclipse-plugin-installation-instructions.html>.
>
>
>
>
> * Select *Apache->Apache Geronimo v2.2*
> * Click *Next*.
>
>
>
> * Set the JRE to *jre6* if it is not already set.
> * Browse for the install directory of Geronimo v2.2 on your
> system.
> * Click *Finish*. You should see the following:
>
>
>
> 3. Now, click the *Next* button. You should see this:
>
>
>
> * Check the *Generate application.xml deployment descriptor*
> option.
> * Click the *New Module...* button:
>
>
>
> * De-select *Create default modules*.
> * Select the *Web* option.
> * Click *Next*.
>
>
>
> * Click *Finish*. You will see the following:
>
>
>
> * Click *Finish*.
>
> 4. Now, your Project Explorer should look like this (partially
> expanded):
>
>
>
> * If you double-click on the *Deployment Descriptor:
> OpenJPATutorial*, you should see the application.xml open:
>
>
>
> 5. Now we will bring in the sample code. The easiest way to add the
> sample code is to find the source provided with this tutorial and
> copy it to the src folder under the *OpenJPATutorialWeb* folder in
> your project directory in Windows Explorer:
>
>
>
> * Now go back to Eclipse. Right-click on the
> *OpenJPATutorialWeb* folder in the Project Explorer view and
> select *Refresh,* or press the *F5* key on your keyboard.
> Now you will see this:
>
>
>
> Notice that all the source files compile without error. That
> is because Geronimo comes with OpenJPA v1.1 built in.
>
> 6. Now copy the index.jsp file from the tutorial into the Web Content
> directory under the Project directory in Windows Explorer:
>
>
>
> * Got to the Project Explorer and refresh the project. You
> should see this:
>
>
>
>
> Running and Configuring Geronimo and Derby
>
> Geronimo has no installer and runs from the command line. Here are some
> quick instructions to get you started.
>
> 1. In Windows, open a command prompt and navigate to the Geronimo
> *bin* directory.
> 2. Type the command:
>
> start-server
>
>
>
>
>
> Press the *Enter* key.
>
>
>
> 3. Open a web browser and go to the address:
>
> http://localhost:8080/console
>
>
>
>
>
> The default password is /manager/.
>
> 4. You will come to the Welcome page. On the left menu, at the
> bottom, find the section for the Embedded DB. This is the Derby
> database control page.
>
>
>
>
> 5. Click on the link for the *DB Manager*.
> 6. You will see two sections: *DB Viewer* and *Run SQL*.
> 7. In the Run SQL section, in the text field labeled Create DB, type
> in *StoreSystem*. This is the name of the database that the
> OpenJPA sample is configured to transact.
>
>
>
>
> 8. Click on the *Create* button. You should now see the *StoreSystem*
> database appear in the*DB Viewer* section.
>
>
>
>
> 9. We are now ready to deploy and run the sample code.
>
>
> Running and Deploying the Sample Code in Geronimo
>
> The sample code provided with this tutorial is working code. It is a
> simple inventory database program that shows items and categories. But
> even this simple example requires the ability to add, edit and delete
> entries. It requires the ability to sort and filter database queries and
> it requires the identification of the relationship of the items to the
> categories. In this example, the relationship is *one to many*. Knowing
> that relationship is important to how the code is written. Before we
> analyze the code and OpenJPA, we will first deploy the sample and see it
> work. To deploy the sample code follow these instructions:
>
> 1. In Eclipse, in the Project Explorer, right click on the
> OpenJPATutorial project and select: *Export->EAR file*.
>
>
>
>
> 2. In the Ear Export dialog, find a convenient place to put the
> exported EAR file.
> 3. Check the *Overwrite existing file* check box.
>
>
>
>
> 4. Click *Finish*.
> 5. Go out to Windows Explorer and copy the file
> *TutorialDeploymentPlan.xml* to the location of the exported ear.
> This is the deployment plan that Geronimo requires to deploy the
> application.
>
>
>
>
> 6. Open the Geronimo console in a web browser and log in.
> 7. In the Console Navigation menu on the left, under the
> *Applications* section, click on the *Deploy New* item.
> 8. Browse to the location of the exported EAR file and the deployment
> plan XML file.
>
>
>
>
> 9. Click on the *Install* button. You should see this.
>
>
>
>
> 10. In the Console Navigation menu on the left, under the
> *Applications* section, click on the *Web App WARs* item.
> * Notice that the OpenJPATutorial application is now listed
> and that there is a clickable link under the URL heading:
>
>
>
>
> 11. Click on the link *OpenJPATutorial* and now you should see this:
>
>
>
>
> Each of the buttons will execute OpenJPA code. The lists are
> filled by running queries on the Derby database.
> 1. Add a some categories and items
> 2. Make sure you test each of the buttons and see the results.
>
>
> Examining the Sample Code
>
> Now that everything is set up and you have seen it work, let's look more
> closely at the parts of the code that use OpenJPA. The JSP code is just
> a prop to explore OpenJPA and we will not examine it.The sample
> application source code is provided for this tutorial and you may run
> as-is with no customizations. However, you have the option of
> reproducing the code manually using the following explanations.
> Whichever method you choose, locate the code that corresponds to
> explanations as you follow along.
>
> * Java code: This tutorial comes with the following java source files:
> o index.jsp: This is the interface code only. It does call
> into other classes but it does not use any OpenJPA code
> directly.
> o InventoryEntityBroker.java: This class contains methods that
> encapsulate the OpenJPA handling code. It is provided as a
> way to separate OpenJPA functionality from the web interface.
> o InventoryItem.java: This is an OpenJPA Entity class file.
> This file is an example of a simple OpenJPA Entity with a
> relationship.
> o InventoryCategory.java: This is an OpenJPA Entity class
> file. This file is an example of a simple OpenJPA Entity
> with a relationship.
> * Persistence code: Each entity concept that would be a database
> table will be its own class. In this case, the tables are called
> "InventoryItem" and "InventoryCategory". Annotations in the Java
> file will associate the properties with the database columns. The
> annotation, @Column, maps the property name to the column name for
> synchronization with the database. If the table corresponding
> tables do not exist, OpenJPA can use these annotations to create
> the tables' schema dynamically based on the property type and length.
>
> *InventoryCategory.java*
>
> package tutorial;
> import java.util.List;
>
> import javax.persistence.CascadeType;
> import javax.persistence.Column;
> import javax.persistence.Entity;
> import javax.persistence.GeneratedValue;
> import javax.persistence.GenerationType;
> import javax.persistence.Id;
> import javax.persistence.OneToMany;
> import javax.persistence.Version;
>
> @Entity
> public class InventoryCategory
> {
> private int version;
> private int id;
>
> private String categoryName;
> private String categoryDescription;
>
> List<InventoryItem> items;
>
> public InventoryCategory(){}
>
> @Column(name = "categoryName")
> public String getCategoryName()
> {
> return categoryName;
> }
>
> public void setCategoryName(String name)
> {
> this.categoryName = name;
> }
>
> @Column(name = "itemDescription")
> public String getCategoryDescription()
> {
> return categoryDescription;
> }
>
> public void setCategoryDescription(String description)
> {
> this.categoryDescription = description;
> }
>
> @Version
> @Column(name = "version_field")
> // not required
> public int getVersion()
> {
> return version;
> }
>
> public void setVersion(int version)
> {
> this.version = version;
> }
>
> @Id
> @GeneratedValue(strategy = GenerationType.AUTO)
> public int getId()
> {
> return id;
> }
>
> public void setId(int id)
> {
> this.id = id;
> }
>
> @OneToMany(targetEntity=tutorial.InventoryItem.class,
> cascade=CascadeType.ALL,
> mappedBy="category")
> public List<InventoryItem> getItems()
> {
> return items;
> }
>
> public void setItems(List<InventoryItem> items)
> {
> this.items = items;
> }
>
> public void addItem(InventoryItem item)
> {
> this.items.add(item);
> }
> }
>
>
> *Note*
>
> In this example, the property annotations ( @Column,@Version, and @Id)
> are placed on the getter methods. They can alternatively be placed on
> the property declarations. For more information on these annotations and
> to see what other annotations are in OpenJPA, see the Apache OpenJPA 2.0
> User's Guide: Chapter 5
> <http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_meta.html>
>
> * The annotated class and property declarations are all that are
> required.
> * The *...@id* annotation is needed as the unique identifier (primary
> key) for each record.
> * The *...@version* annotation is common practice. It ensures data
> integrity during merges and acts as an optimistic concurrency control.
> * Every property must have both a getter and a setter and the
> standard case convention must be observed.
> ° Correct: *public* *void* setCategoryName(String name)
> ° Incorrect: *public* *void* setcategoryname(String name)
>
>
> * Persistence.xml: JPA requires the use of a XML file called the
> "persistence.xml" that describes how to access the data. The XML
> file must be created in the META-INF directory. The META-INF
> directory containing the persistence.xml must be located with the
> source files.
>
>
>
>
> In the following example, the file only requires a few fields.
>
> *META-INF/persistence.xml*
>
> <persistence xmlns=http://java.sun.com/xml/ns/persistence
> xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
> version="1.0">
> <persistence-unit name="InventorySystem"
> transaction-type="RESOURCE_LOCAL">
> <class>tutorial.InventoryItem</class>
> <class>tutorial.InventoryCategory</class>
> <properties>
> <property name="openjpa.jdbc.SynchronizeMappings"
> value="buildSchema"/>
> <property name="openjpa.ConnectionURL"
> value="jdbc:derby://localhost:1527/StoreSystem"/>
> <property name="openjpa.ConnectionDriverName"
> value="org.apache.derby.jdbc.ClientDriver"/>
> </properties>
> </persistence-unit>
> </persistence>
>
>
>
> * The following elements are specific to this tutorial:
> o *persistence-unit*: the *name* is the table name to bind. In
> this case it is 'person'.
> o *class*: the java class that is bound to the table 'person'.
> o *property:* openjpa.jdbc.SynchronizeMappings: This tells
> OpenJPA to automatically create the table with the class
> definition if a table does not already exist.
> o *property:* openjpa.ConnectionURL: The URL of the database
> connection.
> o *property:* openjpa.ConnectionDriverName: the class name of
> the JDBC driver for Derby. This must be available via the
> classpath. In this tutorial, the driver is built into
> Geronimo so no extra actions are needed.
> * A complete explanation of the persistence.xml is in the Apache
> OpenJPAV2.0 user's Guide: Chapter 6
>
> <http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_persistence.html>
>
> * Create the Entity Manager. In the provided code, the EntityManager
> is a property of the InventoryEntityBroker class. The Entity
> Manager controls the interaction with the database. You must use
> the Entity Manager to start or access transactions or to send
> queries.
> o The following code must be added before using any of the
> persistence APIs (If you are using the provided sample code,
> this is already included):
>
> EntityManagerFactory factory =
> Persistence.createEntityManagerFactory("InventorySystem",
> System.getProperties());
>
> EntityManager em = factory.createEntityManager();
>
> o Note that the name, "InventorySystem", is the same one
> identified in the persistence.xml.
> o This code can be placed just before a query or transaction
> or they can be class properties.
> o Regardless of the scope, the EntityManager and the
> EntityManagerFactory should be closed when they are no
> longer needed:
>
> ...
> em.close();
> factory.close();
> ...
>
> o The EntityManagerFactory and EntityManager full descriptions
> are in the following OpenJPA documentation:
> + EntityManagerFactory:
>
> http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_emfactory.html
> + EntityManager:
>
> http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_em.html
>
> * DB interface class. In this example, the InventoryEntityBroker
> class contains all the OpenJPA database interaction code. This is
> not required but it is a good idea for keeping the functionality
> componentized. For example, if you want to pull all of the records
> from the InventoryItem table, the code would look like this:
> *InventoryEntityBroker.java*
>
> ...
> List<Person> getAllItems()
> {
> Query q = em.createQuery("SELECT item FROM InventoryItem item");
>
> return (List<InventoryItem>)q.getResultList();
> }
> ...
>
> *index.jsp*
>
> ...
> List<InventoryItem> itemList = getAllItems();
> ...
>
> o All of the specific APIs are described in the OpenJPA
> javadoc
> <http:/openjpa.apache.org/builds/latest/docs/javadoc/index.html>
> o Notice that the Query is not standard SQL. It is actually
> JPQL, which is a specialized form of query language
> specifically designed for JPA.
> + In the JPQL statement, "SELECT item FROM InventoryItem
> item", notice that InventoryItem has the same case as
> the class InventoryItem.
> + JPQL uses java objects in the query and not the
> database table names. The statement identifies the
> variable for InventoryItem as "item".
> + JPQL provides an object oriented query language that
> is independent of the database being queried. So,
> regardless of which database being used, the JPQL does
> not change. The JPA runtime takes care of doing the
> translation from the object world to the desired
> relational database.
> + For more information on JPQL, check out this Java
> Persistence Querly Language reference.
>
> <http://java.sun.com/javaee/5/docs/tutorial/backup/update3/doc/QueryLanguage.html>
>
> * Also in the InventoryEntityBroker is code to add entries the
> database tables. Since you did not create a table for
> InventoryItem in the StoreSystem database in Derby, OpenJPA 2.0
> will create the table the first time an /"add"/ is attempted.
> o Consider the following code:
> *InventoryEntityBroker*
>
> ...
> void addItem(String name, String description, float price, int
> categoryID)
> {
> InventoryItem item = new InventoryItem();
> item.setName(name);
> item.setDescription(description);
> ...
>
> em.persist(item);
> }
> ...
>
> You can then call the addItem() method in another part of
> the code. The EntityManager.persist() method will throw an
> exception if a transaction has not been started. The
> transaction must be committed by calling the
> Transaction.commit() method after all updates have been
> applied or else the changes will not be saved to the database:
>
> ...
> em.getTransaction().begin();
>
> addItem(...);
>
> em.getTransaction().commit();
> ...
>
> + When this is executed the first time it will use the
> annotations to create the Person table, then OpenJPA
> 2.0 will populate it with the provided data.
> + Note the use of the getTransaction() method to start
> an update and then to commit it. The concept is the
> same as in any database transaction processing.
> + Also note that while the getAllItems() function
> requires a JPQL SELECT query, the update type actions
> have APIs.
> + Take a look in the InventoryEntityBroker code at the
> addItem(), updateItem() and deleteItem() functions and
> note the simplicity of these operations.
>
> * An important aspect of relational databases is, of course, the
> relationships. The basic relationship types are: one to many, many
> to one, and many to many. OpenJPA provides annotations to identify
> the related fields.
> Open the source file, InventoryCategory.java in Eclipse and find
> the following code:
> *InventoryCategory.java*
>
> ...
> @OneToMany(targetEntity=tutorial.InventoryItem.class,
> cascade=CascadeType.ALL,
> mappedBy="category")
> public List<InventoryItem> getItems()
> {
> return items;
> }
> ...
>
> o The annotation @OneToMany identifies that:
> + This object has a one-to-many relationship with
> targetEntity=tutorial.InventoryItem.class. Meaning
> that one InventoryCategory can have many
> InventoryItems associated with it.
> + The property of InventoryItem that specifies the
> InventoryCategory it is associated with is
> mappedBy="category". In other words, InventoryItem has
> a class property of type InventoryCategory named
> "category".
> Now open the source file, InventoryItem.java and find
> the following code:
> *InventoryItem.java*
>
> ...
> @ManyToOne
> @JoinColumn(name="CAT_ID", nullable=false)
> public InventoryCategory getCategory()
> {
> return category;
> }
> ...
>
> + The annotation @ManyToOne identifies that:
> + This object has a many-to-one relationship with the
> InventoryCategory object. Meaning that there many
> InventoryItems can reference the same InventoryCategory
> o The annotation @JoinColumn identifies that:
> + The column in the database table that holds the
> InventoryCategory reference by the attribute:
> name="CAT_ID".
> *Remember*
>
> These annotations contribute to the creation of the
> tables and the relationships. It is important to put
> as much thought into how these objects relate to each
> other as you would if you were designing the database
> tables because you are designing the database tables.
> You can see more about the relationship annotations at
> the Apache OpenJPA site. The documentation is here
>
> <http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_meta_field.html>.
>
>
> Summary
>
> This was a very basic example of how to use OpenJPA with Geronimo and
> Derby. However, many applications that require database persistence do
> not use much more than the basic functionality demonstrated in this
> tutorial. The purpose of this was to be a primer. Aside from the setup
> of the server and database, we went through the creation of a
> persistence.xml file, the basics of the OpenJPA Entity, and
> EntityManager and some of the functionality.
> *Exercises*
> Using this sample code as a base, try to do some of the following:
>
> * Add additional fields to the InventoryItem Entity.
> * Create a Customer Entity and establish a one-to-many relationship
> with the InventoryItems as one customer having purchased many items.
> * Since several customers could have purchased the same items and an
> item could have been purchased by many customers, use the
> documentation to create a many-to-many relationship using
> @ManyToMany*.
>
> _*To make these changes you may have to delete the existing database
> tables so that they can recreated with the new relationship fields.
>
>
> References
>
> * *Java J2SE 1.6*
> o Download
>
> <https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/viewproductdetail-start?productref=jdk-6u16-oth-...@cds-cds_developer>
> * *
> * *Apache Sources*
> o *Geronimo*
> + Geronimo Homepage <http://geronimo.apache.org/>
> + Geronimo V2.2 Server Documentation
> <http://cwiki.apache.org/GMOxDOC22/documentation.html>
> + Geronimo V2.2 Server download
>
> <http://www.apache.org/dyn/closer.cgi/geronimo/2.2/geronimo-tomcat6-javaee5-2.2-bin.zip>
> o *JPA*
> + Apache OpenJPA home page <http://openjpa.apache.org/>
> + Apache OpenJPA download
> <http://openjpa.apache.org/downloads.html>
> + Apache OpenJPA documentation
> <http://openjpa.apache.org/documentation.html>
>
> * *Annotations*
> o Documentation for Java Annotations
>
> <http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html>
> * *JPQL*
> o A reference for JPQL
>
> <http://java.sun.com/javaee/5/docs/tutorial/backup/update3/doc/QueryLanguage.html>
> * *Blogs*
> o Discussion on The Server Side
> <http://www.theserverside.com/news/thread.tss?thread_id=58343>
> o Websphere & OpenJPA blog on blogspot
> <http://bit.ly/JPATutBlogApache>
> o JPA Blog on developerWorks <http://bit.ly/JPATutApachedwBlog>
> * *Implementation Sites*
> o IBM WebSphere Application Server V7 Java Persistence API
> (JPA) 2.0 Open Alpha <http://bit.ly/JPATutBlogApache>
>
> Change Notification Preferences
> <http://cwiki.apache.org/confluence/users/viewnotifications.action>
> View Online
> <http://cwiki.apache.org/confluence/display/openjpa/Begin+using+OpenJPA+-+The+Basics>
> | View Change
> <http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=12320826&revisedVersion=5&originalVersion=4>
> | Add Comment
> <http://cwiki.apache.org/confluence/display/openjpa/Begin+using+OpenJPA+-+The+Basics?showComments=true&showCommentArea=true#addcomment>
>
