Mailing-List: contact commits-help@openjpa.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@openjpa.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Subject: svn commit: r1409057 [5/25] - in /openjpa/site: branches/ trunk/
 trunk/cgi-bin/ trunk/content/ trunk/content/images/ trunk/lib/
 trunk/resources/ trunk/templates/
Date: Wed, 14 Nov 2012 01:50:14 -0000
To: commits@openjpa.apache.org
From: mikedd@apache.org
Message-Id: <20121114015036.8B1C72388ABB@eris.apache.org>

Added: openjpa/site/trunk/content/begin-using-openjpa---the-basics.cwiki
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/begin-using-openjpa---the-basics.cwiki?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/begin-using-openjpa---the-basics.cwiki (added)
+++ openjpa/site/trunk/content/begin-using-openjpa---the-basics.cwiki Wed Nov 14 01:49:37 2012
@@ -0,0 +1,488 @@
+h1. 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 {color:black}web application{color} 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. &nbsp;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.&nbsp;
+
+h2. 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-JPR@CDS-CDS_Developer].
+
+*Eclipse V3.2 or later:* This version has annotation support included. Annotations play a large role in OpenJPA.&nbsp; [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|^OpenJPAWebAppTutorial.zip|attached source files] are provided with this tutorial. You will add them to your Eclipse project.
+
+h1. 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. &nbsp;
+
+h2. 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].
+
+# 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:
+\\
+\\  !image001.jpg!\\
+\\
+# 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].
+\\
+\\  !image002.jpg!\\
+\\
+#* Select *Apache->Apache Geronimo v2.2*
+#* Click *Next*.
+\\
+\\  !image003.jpg!\\
+\\
+#* 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:
+\\
+\\  !image001.jpg!\\
+\\
+# Now, click the *Next* button. You should see this:
+\\
+\\  !image004.jpg!\\
+\\
+#* Check the *Generate application.xml deployment descriptor* option.
+#* Click the *New Module...* button:
+\\
+\\  !image005.jpg!\\
+\\
+#* De-select *Create default modules*.
+#* Select       the *Web* option.
+#* Click *Next*.
+\\
+\\  !image006.jpg!\\
+\\
+#* Click *Finish*. You will see the following:
+\\
+\\  !image007.jpg!\\
+\\
+#* Click *Finish*.
+\\
+\\
+# Now, your Project Explorer should look like this (partially expanded):
+\\
+\\  !image008.jpg!\\
+\\
+#* If you double-click on the *Deployment Descriptor: OpenJPATutorial*, you should see the application.xml open:
+\\
+\\  !image009.jpg!\\
+\\
+# 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:
+\\
+\\  !image010.jpg!\\
+\\
+#* 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:
+\\
+\\  !image011.jpg!\\
+\\
+Notice that all the source files compile without error. That is because Geronimo comes with OpenJPA v1.1 built in.
+\\
+\\
+# {color:black}Now copy the index.jsp file from the tutorial into the Web Content directory under the Project directory in Windows Explorer:{color}\\
+\\  !image012.jpg!\\
+\\
+#* {color:black}Got to the Project Explorer and refresh the project. You should see this:{color}\\
+\\
+\\  !image013.jpg!\\
+\\
+
+h2. 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.
+# In Windows, open a command prompt and navigate to the Geronimo *bin* directory.
+# Type the command:
+{code}
+start-server
+{code}
+\\
+\\  !image014.jpg!\\
+\\
+Press the *Enter* key.
+\\
+\\  !image015.jpg!\\
+\\
+# Open a web browser and go to the address:
+\\
+\\
+[http://localhost:8080/console|http://localhost:8080/console]\\
+\\
+\\  !image016.jpg!\\
+\\
+\\
+The default password is _manager_.
+\\
+\\
+# 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.
+\\
+\\
+\\  !image017.jpg!\\
+\\
+# {color:black}Click on the link for the{color} {color:black}{*}DB Manager{*}{color}{color:black}.{color}
+# You will see two sections: *DB Viewer* and *Run SQL*.
+# 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.
+\\
+\\
+\\  !image018.jpg!\\
+\\
+# {color:black}Click on the{color} {color:black}{*}Create{*}{color} {color:black}button. You should now see the{color} {color:black}{*}StoreSystem{*}{color} {color:black}database appear in the{color}{color:black}{*}DB Viewer{*}{color} {color:black}section{color}.
+\\
+\\
+\\  !image019.jpg!\\
+\\
+# {color:black}We are now ready to deploy and run the sample code.{color}
+
+\\
+
+h2. 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:
+# In Eclipse, in the Project Explorer, right click on the OpenJPATutorial project and select: *Export->EAR file*.
+\\
+\\
+\\  !image020.jpg!\\
+\\
+# In the      Ear Export dialog, find a convenient place to put the exported EAR file.
+# Check      the *Overwrite existing file* check box.
+\\
+\\
+\\  !image021.jpg!\\
+\\
+# Click *Finish*.
+# 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.
+\\
+\\
+\\  !image022.jpg!\\
+\\
+# Open the Geronimo console in a web browser and log in.
+# In the Console Navigation menu on the left, under the *Applications* section, click on the *Deploy New* item.
+# Browse to the location of the exported EAR file and the deployment plan XML file.
+\\
+\\
+\\  !image023.jpg!\\
+\\
+# Click on the *Install* button. You should see this.
+\\
+\\
+\\  !image024.jpg!\\
+\\
+# 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:
+\\
+\\
+\\  !image025.jpg!\\
+\\
+# Click on the link *OpenJPATutorial* and now you should see this:
+\\
+\\
+\\  !image026.jpg!\\
+\\
+Each of the buttons will execute OpenJPA code. The lists are filled by running queries on the Derby database.
+## Add a some categories and items
+## Make sure you test each of the buttons and see the results.
+\\
+
+h1. 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:
+** index.jsp: This is the interface code only. It does call into other classes but it does not use any OpenJPA code directly.
+** InventoryEntityBroker.java:&nbsp;This class contains methods that encapsulate the OpenJPA handling code. It is provided as a way to separate OpenJPA functionality from the web interface.
+** InventoryItem.java: This is an OpenJPA Entity class file. This file is an example of a simple OpenJPA Entity with a relationship.
+** 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, {color:#646464}@Column{color}, 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.
+
+{code:title=InventoryCategory.java|borderStyle=solid}
+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);
+   }
+}
+{code}
+\\
+{info:title=Note}
+In this example, the property annotations ( {color:#646464}@Column{color},{color:#646464}@Version{color}, and {color:#646464}@Id{color}) 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 {color:#646464}*@Id{*}{color} annotation is needed as the unique identifier (primary key) for each record.
+* The {color:#646464}*@Version{*}{color} 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.
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;°&nbsp; Correct: {color:#7f0055}{*}public{*}{color} {color:#7f0055}{*}void{*}{color} {color:black}setCategoryName(String name){color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;°&nbsp; Incorrect: {color:#7f0055}{*}public{*}{color} {color:#7f0055}{*}void{*}{color} {color:black}setcategoryname(String name){color}
+{info}
+\\
+* 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.
+\\
+\\
+\\  !image027.jpg!\\
+\\
+In the following example, the file only requires a few fields.
+\\
+\\
+{code:xml|title=META-INF/persistence.xml|borderStyle=solid}
+<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>
+{code}
+\\
+\\
+* The following elements are specific to this tutorial:
+** *persistence-unit*: the *name* is the table name to bind. In this case it is        'person'.
+** *class*: the java class that is bound to the table 'person'.
+** *property:* openjpa.jdbc.SynchronizeMappings: This tells OpenJPA to automatically create the table with the class definition if a table does not already exist.
+** *property:* openjpa.ConnectionURL: The URL of the database connection.
+** *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.
+** 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):
+{code:java}
+EntityManagerFactory factory = 	Persistence.createEntityManagerFactory("InventorySystem",
+      System.getProperties());
+
+EntityManager em = factory.createEntityManager();
+{code}
+** Note that the name, {color:#2a00ff}"InventorySystem"{color}, is the same one identified in the persistence.xml.
+** This code can be placed just before a query or transaction or they can be class properties.
+** Regardless of the scope, the EntityManager and the EntityManagerFactory should be closed when they are no longer needed:
+\\
+{code:java}
+...
+em.close();
+factory.close();
+...
+{code}
+** 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|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|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:
+\\
+{code:java|title=InventoryEntityBroker.java}
+...
+List<Person> getAllItems()
+{
+     Query q = em.createQuery("SELECT item FROM InventoryItem item");
+
+     return (List<InventoryItem>)q.getResultList();
+}
+...
+{code}
+{code:java|title=index.jsp}
+...
+List<InventoryItem> itemList = getAllItems();
+...
+{code}
+** All of the specific APIs are described in the OpenJPA [javadoc|http:/openjpa.apache.org/builds/latest/docs/javadoc/index.html]
+** 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, "{color:#2a00ff}SELECT item FROM InventoryItem item{color}", 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 "{color:#2a00ff}item{color}".
+**- JPQL provides an object oriented query language that is independent of the database being queried.&nbsp; So, regardless of which database being used, the JPQL does not change.&nbsp; 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.
+** Consider the following code:
+{code:java|title=InventoryEntityBroker}
+...
+void addItem(String name, String description, float price, int categoryID)
+{
+    InventoryItem item = new InventoryItem();
+    item.setName(name);
+    item.setDescription(description);
+    ...
+
+    em.persist(item);
+}
+...
+{code}
+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:
+{code}
+...
+em.getTransaction().begin();
+
+addItem(...);
+
+em.getTransaction().commit();
+...
+{code}
+*** 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:
+{code:java|title=InventoryCategory.java}
+...
+@OneToMany(targetEntity=tutorial.InventoryItem.class,
+   cascade=CascadeType.ALL,
+   mappedBy="category")
+public List<InventoryItem> getItems()
+{
+    return items;
+}
+...
+{code}
+** The annotation {color:#646464}@OneToMany{color} 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.
+*** {color:black}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".{color}\\  {color:black}Now open the source file, InventoryItem.java and find the following code:{color}
+{code:java|title=InventoryItem.java}
+...
+@ManyToOne
+@JoinColumn(name="CAT_ID", nullable=false)
+public InventoryCategory getCategory()
+{
+    return category;
+}
+...
+{code}
+*** {color:black}The annotation @ManyToOne identifies that:{color}
+*** This object has a many-to-one relationship with the InventoryCategory object. Meaning that there many InventoryItems can reference the same InventoryCategory
+** The annotation {color:#646464}@JoinColumn{color} identifies that:
+*** The column in the database table that holds the InventoryCategory reference by the attribute: {color:black}name={color}{color:#2a00ff}"CAT_ID"{color}.
+\\
+{info:title=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&nbsp; [documentation is here|http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_meta_field.html].
+{info}
+
+h1. 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.~
+
+\\
+
+h1. References
+
+* *Java J2SE 1.6*
+** [Download|https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/ViewProductDetail-Start?ProductRef=jdk-6u16-oth-JPR@CDS-CDS_Developer]
+*&nbsp;*
+* *Apache Sources*
+** *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]
+** *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]&nbsp;&nbsp;
+
+* *Annotations*
+** [Documentation       for Java Annotations|http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html]
+* *JPQL*
+** [A       reference for JPQL|http://java.sun.com/javaee/5/docs/tutorial/backup/update3/doc/QueryLanguage.html]
+* *Blogs*
+** [Discussion       on The Server Side|http://www.theserverside.com/news/thread.tss?thread_id=58343]
+** [Websphere & OpenJPA blog on       blogspot|http://bit.ly/WASJPAblog]
+** [JPA Blog on developerWorks|http://bit.ly/JPATutApachedwBlog]
+* *Implementation Sites*
+** [IBM WebSphere Application Server V7 Java Persistence API (JPA) 2.0 Open Beta|http://bit.ly/BetaSiteApache]
\ No newline at end of file

Propchange: openjpa/site/trunk/content/begin-using-openjpa---the-basics.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: openjpa/site/trunk/content/begin-using-openjpa---the-basics.mdtext
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/begin-using-openjpa---the-basics.mdtext?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/begin-using-openjpa---the-basics.mdtext (added)
+++ openjpa/site/trunk/content/begin-using-openjpa---the-basics.mdtext Wed Nov 14 01:49:37 2012
@@ -0,0 +1,804 @@
+Title: Begin using OpenJPA - The Basics
+<a name="BeginusingOpenJPA-TheBasics-Introduction"></a>
+# 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 {color:black}web application{color} 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. &nbsp;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.&nbsp;
+
+<a name="BeginusingOpenJPA-TheBasics-Prerequisites"></a>
+## 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-JPR@CDS-CDS_Developer]
+.
+
+*Eclipse V3.2 or later:* This version has annotation support included.
+Annotations play a large role in OpenJPA.&nbsp; [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](^openjpawebapptutorial.zip|attached-source-files.html)
+ are provided with this tutorial. You will add them to your Eclipse
+project.
+
+<a name="BeginusingOpenJPA-TheBasics-SetupandRunningtheSample"></a>
+# 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. &nbsp;
+
+<a name="BeginusingOpenJPA-TheBasics-SettingupEclipse"></a>
+## 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"*.
+1. * 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:
+  
+  
+  
+  
+  
+  
+1. Under the *Target Runtime* section, select *Apache Geronimo v2.2*.
+1. * If you do not already have Geronimo setup in Eclipse then you will have
+to do so now. Click on the *New...* button.
+1. * 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)
+.
+  
+  
+  
+  
+  
+  
+1. * Select *Apache->Apache Geronimo v2.2*
+1. * Click *Next*.
+  
+  
+  
+  
+  
+  
+1. * Set the JRE to *jre6* if it is not already set.
+1. * Browse for the install directory of Geronimo v2.2 on your system.
+1. * Click *Finish*. You should see the following:
+  
+  
+  
+  
+  
+  
+1. Now, click the *Next* button. You should see this:
+  
+  
+  
+  
+  
+  
+1. * Check the *Generate application.xml deployment descriptor* option.
+1. * Click the *New Module...* button:
+  
+  
+  
+  
+  
+  
+1. * De-select *Create default modules*.
+1. * Select	the *Web* option.
+1. * Click *Next*.
+  
+  
+  
+  
+  
+  
+1. * Click *Finish*. You will see the following:
+  
+  
+  
+  
+  
+  
+1. * Click *Finish*.
+  
+  
+  
+  
+1. Now, your Project Explorer should look like this (partially expanded):
+  
+  
+  
+  
+  
+  
+1. * If you double-click on the *Deployment Descriptor: OpenJPATutorial*, you
+should see the application.xml open:
+  
+  
+  
+  
+  
+  
+1. 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:
+  
+  
+  
+  
+  
+  
+1. * 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.
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+
+<a name="BeginusingOpenJPA-TheBasics-RunningandConfiguringGeronimoandDerby"></a>
+## 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.
+1. Type the command:
+
+    start-server
+
+  
+  
+  
+  
+  
+  
+Press the *Enter* key.
+  
+  
+  
+  
+  
+  
+1. Open a web browser and go to the address:
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  
+The default password is _manager_.
+  
+  
+  
+  
+1. 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.
+  
+  
+  
+  
+  
+  
+  
+  
+1. {color:black}Click on the link for the{color} {color:black}{*}DB
+Manager{*}{color}{color:black}.{color}
+1. You will see two sections: *DB Viewer* and *Run SQL*.
+1. 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.
+  
+  
+  
+  
+  
+  
+  
+  
+1. {color:black}Click on the{color} {color:black}{*}Create{*}{color}
+{color:black}button. You should now see the{color}
+{color:black}{*}StoreSystem{*}{color} {color:black}database appear in
+the{color}{color:black}{*}DB Viewer{*}{color} {color:black}section{color}.
+  
+  
+  
+  
+  
+  
+  
+  
+1. {color:black}We are now ready to deploy and run the sample code.{color}
+
+  
+  
+
+<a name="BeginusingOpenJPA-TheBasics-RunningandDeployingtheSampleCodeinGeronimo"></a>
+## 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*.
+  
+  
+  
+  
+  
+  
+  
+  
+1. In the      Ear Export dialog, find a convenient place to put the
+exported EAR file.
+1. Check      the *Overwrite existing file* check box.
+  
+  
+  
+  
+  
+  
+  
+  
+1. Click *Finish*.
+1. 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.
+  
+  
+  
+  
+  
+  
+  
+  
+1. Open the Geronimo console in a web browser and log in.
+1. In the Console Navigation menu on the left, under the *Applications*
+section, click on the *Deploy New* item.
+1. Browse to the location of the exported EAR file and the deployment plan
+XML file.
+  
+  
+  
+  
+  
+  
+  
+  
+1. Click on the *Install* button. You should see this.
+  
+  
+  
+  
+  
+  
+  
+  
+1. In the Console Navigation menu on the left, under the *Applications*
+section, click on the *Web App WARs* item.
+1. * Notice that the OpenJPATutorial application is now listed and that there
+is a clickable link under the URL heading:
+  
+  
+  
+  
+  
+  
+  
+  
+1. 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
+1. # Make sure you test each of the buttons and see the results.
+  
+  
+
+<a name="BeginusingOpenJPA-TheBasics-ExaminingtheSampleCode"></a>
+# 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:
+** index.jsp: This is the interface code only. It does call into other
+classes but it does not use any OpenJPA code directly.
+** InventoryEntityBroker.java:&nbsp;This class contains methods that
+encapsulate the OpenJPA handling code. It is provided as a way to separate
+OpenJPA functionality from the web interface.
+** InventoryItem.java: This is an OpenJPA Entity class file. This file is
+an example of a simple OpenJPA Entity with a relationship.
+** 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,
+{color:#646464}@Column{color}, 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.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>InventoryCategory.java|borderStyle=solid</B></DIV><DIV class="codeContent panelContent">
+    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);
+       }
+    }
+
+  
+  
+{info:title=Note}
+In this example, the property annotations (
+{color:#646464}@Column{color},{color:#646464}@Version{color}, and
+{color:#646464}@Id{color}) 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 {color:#646464}*@Id{*}{color} annotation is needed as the unique
+identifier (primary key) for each record.
+* The {color:#646464}*@Version{*}{color} 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.
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;°&nbsp;
+Correct: {color:#7f0055}{*}public{*}{color}
+{color:#7f0055}{*}void{*}{color} {color:black}setCategoryName(String
+name){color}
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;°&nbsp;
+Incorrect: {color:#7f0055}{*}public{*}{color}
+{color:#7f0055}{*}void{*}{color} {color:black}setcategoryname(String
+name){color}
+{info}
+  
+  
+* 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.
+  
+  
+  
+  
+{code:xml|title=META-INF/persistence.xml|borderStyle=solid}
+<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:
+    ** *persistence-unit*: the *name* is the table name to bind. In this case
+it is	     'person'.
+    ** *class*: the java class that is bound to the table 'person'.
+    ** *property:* openjpa.jdbc.SynchronizeMappings: This tells OpenJPA to
+automatically create the table with the class definition if a table does
+not already exist.
+    ** *property:* openjpa.ConnectionURL: The URL of the database connection.
+    ** *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.
+    ** 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):
+    {code:java}
+    EntityManagerFactory factory = 
+Persistence.createEntityManagerFactory("InventorySystem",
+          System.getProperties());
+    
+    EntityManager em = factory.createEntityManager();
+
+** Note that the name, {color:#2a00ff}"InventorySystem"{color}, is the same
+one identified in the persistence.xml.
+** This code can be placed just before a query or transaction or they can
+be class properties.
+** Regardless of the scope, the EntityManager and the EntityManagerFactory
+should be closed when they are no longer needed:
+  
+  
+{code:java}
+...
+em.close();
+factory.close();
+...
+
+    ** 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|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|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:
+    \\
+    {code:java|title=InventoryEntityBroker.java}
+    ...
+    List<Person> getAllItems()
+    {
+         Query q = em.createQuery("SELECT item FROM InventoryItem item");
+    
+         return (List<InventoryItem>)q.getResultList();
+    }
+    ...
+
+{code:java|title=index.jsp}
+...
+List<InventoryItem> itemList = getAllItems();
+...
+
+    ** All of the specific APIs are described in the OpenJPA [javadoc|http:/openjpa.apache.org/builds/latest/docs/javadoc/index.html]
+    ** 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, "{color:#2a00ff}SELECT item FROM InventoryItem
+item{color}", 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
+"{color:#2a00ff}item{color}".
+    **- JPQL provides an object oriented query language that is independent of
+the database being queried.&nbsp; So, regardless of which database being
+used, the JPQL does not change.&nbsp; 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.
+    ** Consider the following code:
+    {code:java|title=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:
+{code:java|title=InventoryCategory.java}
+...
+@OneToMany(targetEntity=tutorial.InventoryItem.class,
+   cascade=CascadeType.ALL,
+   mappedBy="category")
+public List<InventoryItem> getItems()
+{
+    return items;
+}
+...
+
+    ** The annotation {color:#646464}@OneToMany{color} 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.
+    *** {color:black}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".{color}\\  {color:black}Now open the source file,
+InventoryItem.java and find the following code:{color}
+    {code:java|title=InventoryItem.java}
+    ...
+    @ManyToOne
+    @JoinColumn(name="CAT_ID", nullable=false)
+    public InventoryCategory getCategory()
+    {
+        return category;
+    }
+    ...
+
+*** {color:black}The annotation @ManyToOne identifies that:{color}
+*** This object has a many-to-one relationship with the InventoryCategory
+object. Meaning that there many InventoryItems can reference the same
+InventoryCategory
+** The annotation {color:#646464}@JoinColumn{color} identifies that:
+*** The column in the database table that holds the InventoryCategory
+reference by the attribute:
+{color:black}name={color}{color:#2a00ff}"CAT_ID"{color}.
+  
+  
+{info:title=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&nbsp; [documentation is here](http://openjpa.apache.org/builds/latest/docs/manual/jpa_overview_meta_field.html)
+.
+{info}
+
+<a name="BeginusingOpenJPA-TheBasics-Summary"></a>
+# 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.~
+
+  
+  
+
+<a name="BeginusingOpenJPA-TheBasics-References"></a>
+# References
+
+* *Java J2SE 1.6*
+** [Download](https://cds.sun.com/is-bin/INTERSHOP.enfinity/WFS/CDS-CDS_Developer-Site/en_US/-/USD/ViewProductDetail-Start?ProductRef=jdk-6u16-oth-JPR@CDS-CDS_Developer)
+*&nbsp;*
+* *Apache Sources*
+** *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)
+** *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)
+&nbsp;&nbsp;
+
+* *Annotations*
+** [Documentation       for Java Annotations](http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html)
+* *JPQL*
+** [A       reference for JPQL](http://java.sun.com/javaee/5/docs/tutorial/backup/update3/doc/QueryLanguage.html)
+* *Blogs*
+** [Discussion       on The Server Side](http://www.theserverside.com/news/thread.tss?thread_id=58343)
+** [Websphere & OpenJPA blog on       blogspot](http://bit.ly/WASJPAblog)
+** [JPA Blog on developerWorks](http://bit.ly/JPATutApachedwBlog)
+* *Implementation Sites*
+** [IBM WebSphere Application Server V7 Java Persistence API (JPA) 2.0 Open Beta](http://bit.ly/BetaSiteApache)

Added: openjpa/site/trunk/content/beginners-performance-guide
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/beginners-performance-guide?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/beginners-performance-guide (added)
+++ openjpa/site/trunk/content/beginners-performance-guide Wed Nov 14 01:49:37 2012
@@ -0,0 +1,61 @@
+{excerpt:hidden=true}Intro to tuning OpenJPA{excerpt}
+
+
+h1. OpenJPA Beginners Performance Guide
+
+This guide is targeted at new users of OpenJPA that would like to know some of the important performance tuning properties. Please do not mistake this for an exhaustive tuning guide. This is just enough information to make a developer dangerous, not lethal.
+
+h2. Enhancement 
+
+OpenJPA uses byte-code weaving technologies to enhance user created Entity class objects at build time or dynamically at run time. This allows us to efficiently handle these objects. 
+
+Follow these instructions on how to properly enhance your Entities.
+*[Entity Enhancement|openjpa:Entity Enhancement].
+
+OpenJPA also has a feature that will auto-generate new subclasses or proxy objects that front the user's Entity objects at run time, but *this feature is not recommended for use*. There are numerous functional issues reported and it doesn't perform nearly as well. If you ever see the following message you are using the non-recommended subclassing approach to enhancement.
+
+bq. 3328  pu_name INFO   \[main\] openjpa.Enhance - Creating subclass for "\[ class org.apache.openjpa.entity.E1 , class org.apache.openjpa.entity.E2 \]". This means that your application will be less efficient and will consume more memory than it would if you ran the OpenJPA enhancer. Additionally, lazy loading will not be available for one-to-one and many-to-one persistent attributes in types using field access; they will be loaded eagerly instead.
+
+It is recommended to set the following property to ensure that you don't use this enhancement approach.
+
+{code:xml}
+<properties> 
+    <property name="openjpa.RuntimeUnenhancedClasses" value="unsupported"/>
+<properties>
+{code}
+
+h2. Connection Pooling
+
+As of the 2.1.0 release OpenJPA bundles [Apache Commons DBCP|http://commons.apache.org/dbcp/] as part of the binary download. When running in JSE environments a default connection pool will be plugged in with the provided database configuration properties (Once [OPENJPA-1764|https://issues.apache.org/jira/browse/OPENJPA-1764] is completed) . Most JEE container environments should provide some level of connection pooling. 
+
+In releases prior to 2.1.0 add DBCP to your classpath and use the following example to figure out how to configure pooling.
+
+{code: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="example-derby" transaction-type="RESOURCE_LOCAL">
+        <properties>
+            <property name="openjpa.ConnectionProperties" 
+                value="DriverClassName=org.apache.derby.jdbc.ClientDriver,
+                  Url=jdbc:derby://localhost:1527/database, 
+                  MaxActive=100, 
+                  MaxWait=10000, 
+                  TestOnBorrow=true, 
+                  Username=user, 
+                  Password=secret"/>
+            <property name="openjpa.ConnectionDriverName" 
+                value="org.apache.commons.dbcp.BasicDataSource"/>
+        </properties>
+    </persistence-unit>
+</persistence>
+
+{code}
+h2. Caching
+
+{code:xml}
+<properties> 
+    <property name="openjpa.DataCache" value="true"/>
+    <property name="openjpa.QueryCache" value="true"/>
+<properties>
+{code}
+
+Insert details about what those two properties give me.

Added: openjpa/site/trunk/content/beginners-performance-guide.cwiki
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/beginners-performance-guide.cwiki?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/beginners-performance-guide.cwiki (added)
+++ openjpa/site/trunk/content/beginners-performance-guide.cwiki Wed Nov 14 01:49:37 2012
@@ -0,0 +1,61 @@
+{excerpt:hidden=true}Intro to tuning OpenJPA{excerpt}
+
+
+h1. OpenJPA Beginners Performance Guide
+
+This guide is targeted at new users of OpenJPA that would like to know some of the important performance tuning properties. Please do not mistake this for an exhaustive tuning guide. This is just enough information to make a developer dangerous, not lethal.
+
+h2. Enhancement 
+
+OpenJPA uses byte-code weaving technologies to enhance user created Entity class objects at build time or dynamically at run time. This allows us to efficiently handle these objects. 
+
+Follow these instructions on how to properly enhance your Entities.
+*[Entity Enhancement|openjpa:Entity Enhancement].
+
+OpenJPA also has a feature that will auto-generate new subclasses or proxy objects that front the user's Entity objects at run time, but *this feature is not recommended for use*. There are numerous functional issues reported and it doesn't perform nearly as well. If you ever see the following message you are using the non-recommended subclassing approach to enhancement.
+
+bq. 3328  pu_name INFO   \[main\] openjpa.Enhance - Creating subclass for "\[ class org.apache.openjpa.entity.E1 , class org.apache.openjpa.entity.E2 \]". This means that your application will be less efficient and will consume more memory than it would if you ran the OpenJPA enhancer. Additionally, lazy loading will not be available for one-to-one and many-to-one persistent attributes in types using field access; they will be loaded eagerly instead.
+
+It is recommended to set the following property to ensure that you don't use this enhancement approach.
+
+{code:xml}
+<properties> 
+    <property name="openjpa.RuntimeUnenhancedClasses" value="unsupported"/>
+<properties>
+{code}
+
+h2. Connection Pooling
+
+As of the 2.1.0 release OpenJPA bundles [Apache Commons DBCP|http://commons.apache.org/dbcp/] as part of the binary download. When running in JSE environments a default connection pool will be plugged in with the provided database configuration properties (Once [OPENJPA-1764|https://issues.apache.org/jira/browse/OPENJPA-1764] is completed) . Most JEE container environments should provide some level of connection pooling. 
+
+In releases prior to 2.1.0 add DBCP to your classpath and use the following example to figure out how to configure pooling.
+
+{code: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="example-derby" transaction-type="RESOURCE_LOCAL">
+        <properties>
+            <property name="openjpa.ConnectionProperties" 
+                value="DriverClassName=org.apache.derby.jdbc.ClientDriver,
+                  Url=jdbc:derby://localhost:1527/database, 
+                  MaxActive=100, 
+                  MaxWait=10000, 
+                  TestOnBorrow=true, 
+                  Username=user, 
+                  Password=secret"/>
+            <property name="openjpa.ConnectionDriverName" 
+                value="org.apache.commons.dbcp.BasicDataSource"/>
+        </properties>
+    </persistence-unit>
+</persistence>
+
+{code}
+h2. Caching
+
+{code:xml}
+<properties> 
+    <property name="openjpa.DataCache" value="true"/>
+    <property name="openjpa.QueryCache" value="true"/>
+<properties>
+{code}
+
+Insert details about what those two properties give me.

Propchange: openjpa/site/trunk/content/beginners-performance-guide.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: openjpa/site/trunk/content/beginners-performance-guide.mdtext
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/beginners-performance-guide.mdtext?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/beginners-performance-guide.mdtext (added)
+++ openjpa/site/trunk/content/beginners-performance-guide.mdtext Wed Nov 14 01:49:37 2012
@@ -0,0 +1,93 @@
+Title: Beginners Performance Guide
+{excerpt:hidden=true}Intro to tuning OpenJPA{excerpt}
+
+
+<a name="BeginnersPerformanceGuide-OpenJPABeginnersPerformanceGuide"></a>
+# OpenJPA Beginners Performance Guide
+
+This guide is targeted at new users of OpenJPA that would like to know some
+of the important performance tuning properties. Please do not mistake this
+for an exhaustive tuning guide. This is just enough information to make a
+developer dangerous, not lethal.
+
+<a name="BeginnersPerformanceGuide-Enhancement"></a>
+## Enhancement 
+
+OpenJPA uses byte-code weaving technologies to enhance user created Entity
+class objects at build time or dynamically at run time. This allows us to
+efficiently handle these objects. 
+
+Follow these instructions on how to properly enhance your Entities.
+*[Entity Enhancement](openjpa:entity-enhancement.html)
+.
+
+OpenJPA also has a feature that will auto-generate new subclasses or proxy
+objects that front the user's Entity objects at run time, but *this feature
+is not recommended for use*. There are numerous functional issues reported
+and it doesn't perform nearly as well. If you ever see the following
+message you are using the non-recommended subclassing approach to
+enhancement.
+
+bq. 3328  pu_name INFO   \[main\](main\.html)
+ openjpa.Enhance - Creating subclass for "\[ class
+org.apache.openjpa.entity.E1 , class org.apache.openjpa.entity.E2 \]". This
+means that your application will be less efficient and will consume more
+memory than it would if you ran the OpenJPA enhancer. Additionally, lazy
+loading will not be available for one-to-one and many-to-one persistent
+attributes in types using field access; they will be loaded eagerly
+instead.
+
+It is recommended to set the following property to ensure that you don't
+use this enhancement approach.
+
+
+    <properties> 
+        <property name="openjpa.RuntimeUnenhancedClasses" value="unsupported"/>
+    <properties>
+
+
+<a name="BeginnersPerformanceGuide-ConnectionPooling"></a>
+## Connection Pooling
+
+As of the 2.1.0 release OpenJPA bundles [Apache Commons DBCP](http://commons.apache.org/dbcp/)
+ as part of the binary download. When running in JSE environments a default
+connection pool will be plugged in with the provided database configuration
+properties (Once [OPENJPA-1764|https://issues.apache.org/jira/browse/OPENJPA-1764]
+ is completed) . Most JEE container environments should provide some level
+of connection pooling. 
+
+In releases prior to 2.1.0 add DBCP to your classpath and use the following
+example to figure out how to configure pooling.
+
+
+    <persistence xmlns="http://java.sun.com/xml/ns/persistence"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
+        <persistence-unit name="example-derby"
+transaction-type="RESOURCE_LOCAL">
+    	<properties>
+    	    <property name="openjpa.ConnectionProperties" 
+    		value="DriverClassName=org.apache.derby.jdbc.ClientDriver,
+    		  Url=jdbc:derby://localhost:1527/database, 
+    		  MaxActive=100, 
+    		  MaxWait=10000, 
+    		  TestOnBorrow=true, 
+    		  Username=user, 
+    		  Password=secret"/>
+    	    <property name="openjpa.ConnectionDriverName" 
+    		value="org.apache.commons.dbcp.BasicDataSource"/>
+    	</properties>
+        </persistence-unit>
+    </persistence>
+    
+
+<a name="BeginnersPerformanceGuide-Caching"></a>
+## Caching
+
+
+    <properties> 
+        <property name="openjpa.DataCache" value="true"/>
+        <property name="openjpa.QueryCache" value="true"/>
+    <properties>
+
+
+Insert details about what those two properties give me.

Added: openjpa/site/trunk/content/build-and-runtime-dependencies
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/build-and-runtime-dependencies?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/build-and-runtime-dependencies (added)
+++ openjpa/site/trunk/content/build-and-runtime-dependencies Wed Nov 14 01:49:37 2012
@@ -0,0 +1,145 @@
+{excerpt:hidden=true}OpenJPA Build and Runtime Dependencies{excerpt}
+
+h2. Java versions
+
+* OpenJPA trunk (i.e. OpenJPA 2.2.0 currently) and 2.1.x branch require JDK 1.6.
+* OpenJPA 2.0.x branch requires JDK 1.6 or 1.5. Note that some functionality that requires JDK 1.6 will not be available if you choose to build with JDK 1.5.
+* Building javadoc from 2.0.x branch or newer requires JDK 1.6.
+* OpenJPA 1.3.x, 1.2.x and 1.1.x branches require JDK 1.5.
+* OpenJPA 1.0.x branch requires JDK 1.5 or 1.4.
+
+
+h2. Maven versions
+* Trunk, 2.1.x and 2.0.x branches require Maven 2.2.1.
+* 1.3.x, 1.2.x, 1.1.x and 1.0.x branches require Maven 2.0.9.
+
+
+h2. Runtime Dependencies
+
+The binary release download of OpenJPA _apache-openjpa-<version>-binary.zip_ includes all of the code needed to run in a stand-alone Java SE JVM or within a Java EE application server.
+
+h3. OpenJPA 1.0.x - 1.2.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.jar
+* commons-lang-2.1.jar
+* commons-pool-1.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jpa_3.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625] by OpenJPA:
+* derby-10.2.2.0.jar
+
+
+h3. OpenJPA 1.3.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625] by OpenJPA:
+* derby-10.2.2.0.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+h3. OpenJPA 2.0.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/2.0.1/apache-openjpa-2.0.1/docs/manual/dbsupport.html#d0e36152] by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+h3. OpenJPA 2.1.x Releases and OpenJPA 2.2.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-pool-1.5.4.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/2.1.1/apache-openjpa/docs/dbsupport.html] by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The following artifacts under lib/ are optional and can be used for bean validation:
+* commons-beanutils-1.8.3.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-beanutils-1.8.3.jar
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.4.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+* serp-1.13.1.jar
+
+
+\\

Added: openjpa/site/trunk/content/build-and-runtime-dependencies.cwiki
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/build-and-runtime-dependencies.cwiki?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/build-and-runtime-dependencies.cwiki (added)
+++ openjpa/site/trunk/content/build-and-runtime-dependencies.cwiki Wed Nov 14 01:49:37 2012
@@ -0,0 +1,145 @@
+{excerpt:hidden=true}OpenJPA Build and Runtime Dependencies{excerpt}
+
+h2. Java versions
+
+* OpenJPA trunk (i.e. OpenJPA 2.2.0 currently) and 2.1.x branch require JDK 1.6.
+* OpenJPA 2.0.x branch requires JDK 1.6 or 1.5. Note that some functionality that requires JDK 1.6 will not be available if you choose to build with JDK 1.5.
+* Building javadoc from 2.0.x branch or newer requires JDK 1.6.
+* OpenJPA 1.3.x, 1.2.x and 1.1.x branches require JDK 1.5.
+* OpenJPA 1.0.x branch requires JDK 1.5 or 1.4.
+
+
+h2. Maven versions
+* Trunk, 2.1.x and 2.0.x branches require Maven 2.2.1.
+* 1.3.x, 1.2.x, 1.1.x and 1.0.x branches require Maven 2.0.9.
+
+
+h2. Runtime Dependencies
+
+The binary release download of OpenJPA _apache-openjpa-<version>-binary.zip_ includes all of the code needed to run in a stand-alone Java SE JVM or within a Java EE application server.
+
+h3. OpenJPA 1.0.x - 1.2.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.jar
+* commons-lang-2.1.jar
+* commons-pool-1.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jpa_3.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625] by OpenJPA:
+* derby-10.2.2.0.jar
+
+
+h3. OpenJPA 1.3.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625] by OpenJPA:
+* derby-10.2.2.0.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+h3. OpenJPA 2.0.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/2.0.1/apache-openjpa-2.0.1/docs/manual/dbsupport.html#d0e36152] by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+h3. OpenJPA 2.1.x Releases and OpenJPA 2.2.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-pool-1.5.4.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE environments, as a Java EE application server should provide an implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the JDBC driver artifacts required by your database provider and [supported|http://openjpa.apache.org/builds/2.1.1/apache-openjpa/docs/dbsupport.html] by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The following artifacts under lib/ are optional and can be used for bean validation:
+* commons-beanutils-1.8.3.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+
+The binary download also contains an artifact which includes the OpenJPA core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-beanutils-1.8.3.jar
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.4.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+* serp-1.13.1.jar
+
+
+\\

Propchange: openjpa/site/trunk/content/build-and-runtime-dependencies.cwiki
------------------------------------------------------------------------------
    svn:eol-style = native

Added: openjpa/site/trunk/content/build-and-runtime-dependencies.mdtext
URL: http://svn.apache.org/viewvc/openjpa/site/trunk/content/build-and-runtime-dependencies.mdtext?rev=1409057&view=auto
==============================================================================
--- openjpa/site/trunk/content/build-and-runtime-dependencies.mdtext (added)
+++ openjpa/site/trunk/content/build-and-runtime-dependencies.mdtext Wed Nov 14 01:49:37 2012
@@ -0,0 +1,179 @@
+Title: Build and Runtime Dependencies
+{excerpt:hidden=true}OpenJPA Build and Runtime Dependencies{excerpt}
+
+<a name="BuildandRuntimeDependencies-Javaversions"></a>
+## Java versions
+
+* OpenJPA trunk (i.e. OpenJPA 2.2.0 currently) and 2.1.x branch require JDK
+1.6.
+* OpenJPA 2.0.x branch requires JDK 1.6 or 1.5. Note that some
+functionality that requires JDK 1.6 will not be available if you choose to
+build with JDK 1.5.
+* Building javadoc from 2.0.x branch or newer requires JDK 1.6.
+* OpenJPA 1.3.x, 1.2.x and 1.1.x branches require JDK 1.5.
+* OpenJPA 1.0.x branch requires JDK 1.5 or 1.4.
+
+
+<a name="BuildandRuntimeDependencies-Mavenversions"></a>
+## Maven versions
+* Trunk, 2.1.x and 2.0.x branches require Maven 2.2.1.
+* 1.3.x, 1.2.x, 1.1.x and 1.0.x branches require Maven 2.0.9.
+
+
+<a name="BuildandRuntimeDependencies-RuntimeDependencies"></a>
+## Runtime Dependencies
+
+The binary release download of OpenJPA
+_apache-openjpa-<version>-binary.zip_ includes all of the code needed to
+run in a stand-alone Java SE JVM or within a Java EE application server.
+
+<a name="BuildandRuntimeDependencies-OpenJPA1.0.x-1.2.xReleases"></a>
+### OpenJPA 1.0.x - 1.2.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.jar
+* commons-lang-2.1.jar
+* commons-pool-1.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE
+environments, as a Java EE application server should provide an
+implementation:
+* geronimo-jpa_3.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.jar
+
+The following artifact under lib/ is optional, as you should include the
+JDBC driver artifacts required by your database provider and [supported](http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625)
+ by OpenJPA:
+* derby-10.2.2.0.jar
+
+
+<a name="BuildandRuntimeDependencies-OpenJPA1.3.0SNAPSHOTBranch"></a>
+### OpenJPA 1.3.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE
+environments, as a Java EE application server should provide an
+implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the
+JDBC driver artifacts required by your database provider and [supported](http://openjpa.apache.org/builds/1.2.2/apache-openjpa-1.2.2/docs/manual/supported_databases.html#d0e32625)
+ by OpenJPA:
+* derby-10.2.2.0.jar
+
+The binary download also contains an artifact which includes the OpenJPA
+core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_1.0_spec-1.1.2.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+<a name="BuildandRuntimeDependencies-OpenJPA2.0.xReleases"></a>
+### OpenJPA 2.0.x Releases
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-pool-1.5.3.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE
+environments, as a Java EE application server should provide an
+implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the
+JDBC driver artifacts required by your database provider and [supported](http://openjpa.apache.org/builds/2.0.1/apache-openjpa-2.0.1/docs/manual/dbsupport.html#d0e36152)
+ by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The binary download also contains an artifact which includes the OpenJPA
+core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-collections-3.2.1.jar
+* commons-lang-2.1.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.3.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.0.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* serp-1.13.1.jar
+
+
+<a name="BuildandRuntimeDependencies-OpenJPA2.1.xReleasesandOpenJPA2.2.0SNAPSHOTBranch"></a>
+### OpenJPA 2.1.x Releases and OpenJPA 2.2.0 SNAPSHOT Branch
+
+The binary download includes the following required OpenJPA core artifact:
+* openjpa-<version>.jar
+
+and the following required runtime dependencies under the lib/ directory:
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-pool-1.5.4.jar
+* serp-1.13.1.jar
+
+The following artifacts under lib/ are only required for Java SE
+environments, as a Java EE application server should provide an
+implementation:
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+
+The following artifact under lib/ is optional, as you should include the
+JDBC driver artifacts required by your database provider and [supported](http://openjpa.apache.org/builds/2.1.1/apache-openjpa/docs/dbsupport.html)
+ by OpenJPA:
+* derby-10.5.3.0_1.jar
+
+The following artifacts under lib/ are optional and can be used for bean
+validation:
+* commons-beanutils-1.8.3.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+
+The binary download also contains an artifact which includes the OpenJPA
+core code plus all of the runtime dependencies for Java SE environments:
+* openjpa-all-<version>.jar
+
+which in turn includes classes from the following packages:
+* commons-beanutils-1.8.3.jar
+* commons-collections-3.2.1.jar
+* commons-lang-2.4.jar
+* commons-logging-1.0.4.jar
+* commons-pool-1.5.4.jar
+* geronimo-jms_1.1_spec-1.1.1.jar
+* geronimo-jpa_2.0_spec-1.1.jar
+* geronimo-jta_1.1_spec-1.1.1.jar
+* org.apache.bval.bundle-0.2-incubating.jar
+* serp-1.13.1.jar
+
+
+  
+