mirror of https://github.com/apache/openjpa.git
184 lines
7.3 KiB
HTML
184 lines
7.3 KiB
HTML
<!--
|
|
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>
|