openjpa-examples/openbooks/index.html - openjpa - Git at Google

 <!--
 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>
    &nbsp;&nbsp;<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>&lt;jta-data-source&gt;</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>
     &nbsp;&nbsp;<code>$ ant</code>
     <br>or<br>
     &nbsp;&nbsp;<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>
     &nbsp;&nbsp;<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>
     &nbsp;&nbsp;<code>http://&lt;app server host&gt;:&lt;port&gt;/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>
     &nbsp;&nbsp;<code>$ ant -f run.xml load</code>

 </body>
 </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>