| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <head> |
| <meta name="keywords" content="JPA, OpenJPA, OpenBooks, Sample, Criteria, MetaModel"> |
| <style type="text/css"> |
| body { |
| background-color:#FFFFFF; |
| font-family:"Tahoma"; |
| } |
| h1 { |
| color:black; |
| text-align:center; |
| font-family:"Tahoma"; |
| } |
| h2 { |
| color:blue; |
| text-align:left; |
| font-family:"Tahoma"; |
| } |
| |
| p{ |
| font-family:"Tahoma"; |
| } |
| code{ |
| font-family:"Courier New"; |
| font-size:16px; |
| } |
| </style> |
| </head> |
| |
| <body> |
| <h1>OpenBooks: A sample JPA 2.0 Application</h1> |
| <hr> |
| OpenBooks is a sample (and perhaps simple) application to demonstrate some of the new features of |
| version 2.0 of <A HREF="http://jcp.org/en/jsr/detail?id=317">Java Persistence API</A> (JPA) specification, such as |
| <br> |
| <OL> |
| <LI>Creating dynamic Criteria Query from an input form |
| <LI>Using compound, derived identity and orphan delete for modeling composite relationship |
| <LI>Browsing Persistent Domain Model via MetaModel API |
| </LI> |
| </OL> |
| <br> |
| |
| OpenBooks runs with <A HREF="http://openjpa.apache.org">OpenJPA</A> as its JPA provider. |
| <hr> |
| <h2>Instructions to download and run OpenBooks Demo</h2> |
| OpenBooks comes with |
| <OL> |
| <LI>complete source code |
| <LI>build scripts to demonstrate how to build a typical OpenJPA application and package it for JSE or JEE |
| environment |
| <LI>scripts to run OpenBooks in on your local database installation. |
| </OL> |
| <br> |
| Follow the simple instructions below to build and run OpenBooks: |
| |
| <OL> |
| <LI><A href="#Download">Download OpenBooks distribution</A>. |
| <LI><A href="#Configure">Configure build and run environment</A>. |
| <LI><A href="#Build">Build OpenBooks from source</A> |
| <LI><A href="#Run">Run OpenBooks</A> |
| </OL> |
| <hr> |
| <h2><A name="Download">Download Instructions</A></h2> |
| OpenBooks is distributed under <A HREF="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</A> |
| <br> |
| OpenBooks can be checked out from OpenJPA repository. |
| <br> |
| <code>$ svn co https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks</code>. |
| <br> |
| will check out the source code and build scripts of OpenBooks in current directory. |
| <br> |
| OpenBooks requires following software environment to run: |
| <OL> |
| <LI> Java Runtime version 6.0 or higher |
| <LI> OpenJPA Libraries version 2.0 or higher |
| <LI> Ant version 1.6 or higher |
| <LI> Any JDBC complaint database supported by OpenJPA. |
| See <A href="http://openjpa.apache.org/builds/latest/docs/manual/manual.html#ref_guide_dbsetup_dbsupport">OpenJPA documentation</A> for a list of supported databases. |
| </OL> |
| <hr> |
| |
| |
| <h2><A name="Configure">Configure build and run environment</A></h2> |
| OpenBooks builds with Ant. The Ant build script is somewhat involved because OpenBooks can be built and packaged |
| either as a JSE (Swing based) application or a JEE Web Application. By default, OpenBooks is built as a |
| JSE application. |
| <br> |
| Before you run a build, configure the build environment by editing |
| <A HREF="build.properties"><code>build.properties</code></A>. |
| Essentially, you need to |
| <OL> |
| <LI>point <code>openjpa.lib</code> variable to the local directory where OpenJPA class library(ies) reside. |
| Notice that the variable points to a directory and not a <code>*.jar</code> file. All <code>*.jar</code> files |
| found under the directory are included in compilation classpath. |
| </OL> |
| <br> |
| The next step is to configure runtime environment. |
| <OL> |
| <LI>Edit <A HREF="resources/META-INF/persistence.xml"><code>persistence.xml</code></A> located in |
| <code>resources/META-INF</code> directory. |
| Modify the <code>javax.persistence.jdbc.driver</code> |
| and <code>javax.persistence.jdbc.url</code> property to suit your local database and its driver. |
| <br> |
| The example <code>persistence.xml</code> provided is primarily for a JSE environment. |
| In JEE environment, you may already have a JTA data source configured and registered in JNDI. |
| Of course, then the <code>persistence.xml</code> is to be edited accordingly in |
| <code><jta-data-source></code> clause. |
| <LI>In JSE mode, edit <A HREF="run.properties"><code>run.properties</code></A> to specify location of OpenJPA |
| class libraries and JDBC Driver used in runtime classpath. |
| <br> |
| In JEE mode, OpenJPA library and JDBC drivers are configured in JEE server and hence variables in |
| this file are irrelevant. |
| </OL> |
| |
| |
| Both <code>build.properties</code> and <code>run.properties</code> files are commented in-place on what is to be |
| edited. |
| <hr> |
| |
| <h2><A name="Build">Build OpenBooks from source</A></h2> |
| Once you have configured the environment, simply issue |
| <br> |
| <code>$ ant</code> |
| <br>or<br> |
| <code>$ ant -Dbuild.mode=jee</code> |
| <br> |
| The default target of the ant script will |
| <LI>generate metamodel classes (required for Criteria API) |
| <LI>compile the source code |
| <LI>enhance the persistence domain model |
| <LI>package the application based on the build.mode as a Swing-based application or a Web Application Archive. |
| and <LI>copy the deployable artifacts to <code>target/openbooks</code> directory relative to the current directory. |
| <hr> |
| |
| <h2><A name="Run">Run OpenBooks</A></h2> |
| If you have built OpenBooks for JSE, then go to the <code>target/openbooks</code> directory. |
| <br> |
| Invoke the Ant script to run OpenBooks<br> |
| <code>$ ant -f run.xml</code> |
| |
| <hr> |
| If you have build OpenBooks for JEE, a Web Application Archive <code>openbooks.war</code> will be |
| created in <code>target/openbooks</code> directory. You need to deploy <code>openbooks.war</code> |
| to a JEE Application Server. Once deployed, you can point a browser to Application Server URL |
| <br> |
| <code>http://<app server host>:<port>/openbooks/</code> |
| <br> |
| to access OpenBooks as an web application. |
| <hr> |
| |
| <h2><A name="Seed">Populate OpenBooks Database</A></h2> |
| OpenBooks checks for existing data at first connection to the database. |
| If the database is empty, the schema is defined and populated with initial data. |
| However, you can explicitly populate the database in JSE build. |
| Edit <A HREF="load.properties"><code>load.properties</code></A> |
| to specify load parameters such as number of Books etc. OpenBooks uses this data to populate a database |
| with some sample data. This example file has some typical values. If you are satisfied with it, |
| you can leave them as it is. Then invoke the Ant script<br> |
| <code>$ ant -f run.xml load</code> |
| |
| </body> |
| </html> |