[CONF] OpenJPA > Building and Running OpenBooks

[confluence]

Building and Running OpenBooks Page edited by Kevin Sutter Changes (42) h2. Instructions to download and run OpenBooks Demo OpenBooks comes with * complete source code * build scripts to demonstrate how to build a typical OpenJPA application and package it for JSE or JEE environment * scripts to run OpenBooks in on your local database installation. Follow the simple instructions below to build and run OpenBooks: h2. Download Instructions OpenBooks can be checked out from OpenJPA repository. {{$ svn co https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks}}. will check out the source code and build scripts of OpenBooks in current directory. OpenBooks requires following software environment to run: * Java Runtime version 6.0 or higher * OpenJPA Libraries version 2.0 or higher * Ant version 1.6 or higher * Any JDBC complaint database supported by OpenJPA. {{$ svn co}} {{[https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks]}}. will check out the source code and build scripts of OpenBooks in current directory. OpenBooks requires following software environment to run: * Java Runtime version 6.0 or higher * OpenJPA Libraries version 2.0 or higher * Ant version 1.6 or higher * Any JDBC complaint database supported by OpenJPA (embedded Derby is the default). h2. Configure build and run environment 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. either as a JSE (Swing based) application or a JEE Web Application. By default, OpenBooks is built as a JSE application. OpenBooks can be built in JSE and JEE mode -- and to keep things simple the common build steps are available in main build script {{build.xml}} while JSE and JEE specific packaging steps are described in separate {{build.jse.xml}} and {{build.jee.xml}}, respectively. Furthermore, for JEE, the deployment step is further refined for each application server. See {{build.jee.was.xml}} for WebSphere installation steps. main build script {{build.xml}} while JSE and JEE specific packaging steps are described in separate {{build.jse.xml}} and {{build.jee.xml}} respectively. Furthermore, for JEE, the deployment step is further refined for each application server. See {{build.jee.was.xml}} for WebSphere installation. Before you run a build, configure the build environment by editing {{build.properties}}. Essentially, you need to * point {{openjpa.lib}} variable to the local directory where OpenJPA class library(ies) reside. Notice that the variable points to a directory and not a {{* .jar}} file. All {{* .jar}} files found under the directory are included in compilation classpath. OpenJPA version 2.0, however, is also available with all its runtime dependencies (such as JPA specification API, Apache Commons Collections and others) packaged together in a _single_ library. * Ideally, a JPA-compliant application _should_ not require provider-specific library during compilation. OpenBooks persistent domain model and application logic also does not use any OpenJPA specific features, but OpenJPA libraries are still used during compilation because bytecode for persistent entities are _enhanced_ as a post-compilation step. This bytecode enhancement is not essential but an important step for using OpenJPA. The next step is to configure runtime configuration descriptors and environment variables. * For JSE environment, edit {{persistence.xml}} located in {{resources/META-INF}} directory. Modify the {{javax.persistence.jdbc.driver}} and {{javax.persistence.jdbc.url}} property to suit your local database and its driver. * In JEE environment, you may already have a JTA data source configured and registered in JNDI. Of course, then the appropriate configuration is to be edited accordingly in {{&lt;jta-data-source&gt;}} clause. See {{persistence.jee.was.xml}} for WebSphere environment. Before you run a build, configure the build environment by editing {{openjpa-examples/openbooks/build.properties}}. Essentially, you need to * Point {{openjpa.lib}} variable to the local directory where OpenJPA class library(ies) reside. Notice that the variable points to a directory and not a {{\* .jar}} file. All {{\* .jar}} files found under the directory are included in compilation classpath. OpenJPA version 2.0, however, is also available with all its runtime dependencies (such as JPA specification API, Apache Commons Collections and others) packaged together in a _single_ library. *Note:&nbsp;* Access to the OpenJPA class libraries is easier if you have a Maven repository (.m2) available on your system.&nbsp; In this case, all that is required is to update the {{openjpa.version}} variable to point at the proper OpenJPA SNAPSHOT version. * Ideally, a JPA-compliant application _should_ not require provider-specific library during compilation. OpenBooks persistent domain model and application logic also does not use any OpenJPA specific features, but OpenJPA libraries are still used during compilation because bytecode for persistent entities are _enhanced_ as a post-compilation step. This bytecode enhancement is not essential but an important step for using OpenJPA. The next step is to configure runtime configuration descriptors and environment variables. * For JSE environment, edit {{persistence.xml}} located in {{openjpa-examples/openbooks/src/main/resources/META-INF}} directory. Modify the {{javax.persistence.jdbc.driver}} and {{javax.persistence.jdbc.url}} property to suit your local database and its driver. * In JSE mode, edit {{openjpa-examples/openbooks/run.properties}} to specify location of OpenJPA class libraries and JDBC Driver used in runtime classpath. Here again, the use of the {{openjpa.version}} variable with a Maven repository makes this configuration easy. used in runtime classpath. * In JEE environment, you may already have a JTA data source configured and registered in JNDI. Of course, then the appropriate configuration is to be edited accordingly in {{<jta-data-source>}} clause. See {{persistence.jee.was.xml}} for WebSphere environment. * In JEE mode, OpenJPA library and JDBC drivers are configured in JEE server and hence variables in this file are irrelevant. this file are irrelevant. Both {{build.properties}} and {{run.properties}} files are commented in-place on what is to be edited. edited. h2. Build OpenBooks from source Once you have configured the environment, simply issue (from the {{openjpa-examples/openbooks}} directory): {{$ ant}} or {{$ ant \-Dbuild.mode=jee}} The default target of the ant script will * generate metamodel classes (required for Criteria API) * compile the source code * enhance the persistence domain model * package the application based on the build.mode as a Swing-based application or a Web Application Archive. and * copy the deployable artifacts to {{target/openbooks}} directory relative to the current directory. The default target of the ant script will * generate metamodel classes (required for Criteria API) * compile the source code * enhance the persistence domain model * package the application based on the build.mode as a Swing-based application or a Web Application Archive. * copy the deployable artifacts to {{target/openbooks}} directory relative to the current directory. h2. Deploy OpenBooks in an Application Server Deployment techniques and configuration vary across JEE compliant application servers. Hence, OpenBooks does not provide an uber-deployment script for all application server. Instead, application server specific steps are encoded in separate build scripts for each application server. Using generic build as described in the previous section, the {{openbooks.war}} web archive need to be deployed manually. For WebSphere Application Server, automated build scripts are available in {{build.jee.was.xml}}. WebSphere deployment needs to be triggered by {{ws_ant}} utility as follows Deployment techniques and configuration vary across JEE compliant application servers. Hence, OpenBooks does not provide an uber-deployment script for all application server. Instead, application server specific steps are encoded in separate build scripts for each application server. Using generic build as described in the previous section, the {{openbooks.war}} web archive need to be deployed manually. {{$ ws_ant -Dbuild.mode=jee -Dappserver=was -Dwas.home=WAS_HOME}} For WebSphere Application Server, automated build scripts are available in {{build.jee.was.xml}}. WebSphere deployment needs to be triggered by {{ws_ant}} utility as follows {{$ ws_ant \-Dbuild.mode=jee \-Dappserver=was \-Dwas.home=WAS_HOME}} where {{WAS_HOME}} denotes the root directory where WAS V7 with JPA 2.0 feature pack has been installed. Yes, OpenBooks requires the WAS V7 JPA 2.0 feature pack with a profile augmented to run with the feature pack. Further information on this feature pack is available [here|http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27018836]. Yes, OpenBooks requires the WAS V7 JPA 2.0 feature pack with a profile augmented to run with the feature pack. Further information on this feature pack is available [here|http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27018836]. The WebSphere specific build will configure appropriate JTA data sources using a python script (found under {{openbooks/scripts/}} directory before deploying OpenBooks as a web application. The script assumes a single server instance. If multiple profiles exist, the script will use the first server profile. directory before deploying OpenBooks as a web application. The script assumes a single server instance. If multiple profiles exist, the script will use the first server profile. h2. Run OpenBooks If you have built OpenBooks for JSE, then go to the {{target/openbooks}} directory. Invoke the Ant script to run OpenBooks {{$ ant -f run.xml}} If you have build OpenBooks for JEE, a Web Application Archive {{openbooks.war}} will be created in {{target/openbooks}} directory. You need to deploy {{openbooks.war}} to a JEE Application Server. Once deployed, you can point a browser to Application Server URL {{http:// &lt; app server host &gt;:&lt;port&gt;/openbooks/}} to access OpenBooks as an web application. Invoke the Ant script to run OpenBooks {{$ ant \-f run.xml}} If you have build OpenBooks for JEE, a Web Application Archive {{openbooks.war}} will be created in {{target/openbooks}} directory. You need to deploy {{openbooks.war}} to a JEE Application Server. Once deployed, you can point a browser to Application Server URL {{http:// < app server host >:<port>/openbooks/}} to access OpenBooks as an web application. h2. Populate OpenBooks Database 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. 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 {{load.properties}} *Note:* By default, the OpenBooks example uses and populates an Embedded Derby instance. So, no further configuration or loading is required for the default configuration. Edit {{load.properties}} 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 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 {{$ ant \-f run.xml load}} Full Content Instructions to download and run OpenBooks Demo OpenBooks comes with complete source code build scripts to demonstrate how to build a typical OpenJPA application and package it for JSE or JEE environment scripts to run OpenBooks in on your local database installation. Follow the simple instructions below to build and run OpenBooks: Download Instructions OpenBooks can be checked out from OpenJPA repository. $ svn co https://svn.apache.org/repos/asf/openjpa/trunk/openjpa-examples/openbooks. will check out the source code and build scripts of OpenBooks in current directory. OpenBooks requires following software environment to run: Java Runtime version 6.0 or higher OpenJPA Libraries version 2.0 or higher Ant version 1.6 or higher Any JDBC complaint database supported by OpenJPA (embedded Derby is the default). Configure build and run environment 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. OpenBooks can be built in JSE and JEE mode – and to keep things simple the common build steps are available in main build script build.xml while JSE and JEE specific packaging steps are described in separate build.jse.xml and build.jee.xml, respectively. Furthermore, for JEE, the deployment step is further refined for each application server. See build.jee.was.xml for WebSphere installation steps. Before you run a build, configure the build environment by editing openjpa-examples/openbooks/build.properties. Essentially, you need to Point openjpa.lib variable to the local directory where OpenJPA class library(ies) reside. Notice that the variable points to a directory and not a * .jar file. All * .jar files found under the directory are included in compilation classpath. OpenJPA version 2.0, however, is also available with all its runtime dependencies (such as JPA specification API, Apache Commons Collections and others) packaged together in a single library. Note:  Access to the OpenJPA class libraries is easier if you have a Maven repository (.m2) available on your system.  In this case, all that is required is to update the openjpa.version variable to point at the proper OpenJPA SNAPSHOT version. Ideally, a JPA-compliant application should not require provider-specific library during compilation. OpenBooks persistent domain model and application logic also does not use any OpenJPA specific features, but OpenJPA libraries are still used during compilation because bytecode for persistent entities are enhanced as a post-compilation step. This bytecode enhancement is not essential but an important step for using OpenJPA. The next step is to configure runtime configuration descriptors and environment variables. For JSE environment, edit persistence.xml located in openjpa-examples/openbooks/src/main/resources/META-INF directory. Modify the javax.persistence.jdbc.driver and javax.persistence.jdbc.url property to suit your local database and its driver. In JSE mode, edit openjpa-examples/openbooks/run.properties to specify location of OpenJPA class libraries and JDBC Driver used in runtime classpath. Here again, the use of the openjpa.version variable with a Maven repository makes this configuration easy. In JEE environment, you may already have a JTA data source configured and registered in JNDI. Of course, then the appropriate configuration is to be edited accordingly in <jta-data-source> clause. See persistence.jee.was.xml for WebSphere environment. In JEE mode, OpenJPA library and JDBC drivers are configured in JEE server and hence variables in this file are irrelevant. Both build.properties and run.properties files are commented in-place on what is to be edited. Build OpenBooks from source Once you have configured the environment, simply issue (from the openjpa-examples/openbooks directory): $ ant or $ ant -Dbuild.mode=jee The default target of the ant script will generate metamodel classes (required for Criteria API) compile the source code enhance the persistence domain model package the application based on the build.mode as a Swing-based application or a Web Application Archive. copy the deployable artifacts to target/openbooks directory relative to the current directory. Deploy OpenBooks in an Application Server Deployment techniques and configuration vary across JEE compliant application servers. Hence, OpenBooks does not provide an uber-deployment script for all application server. Instead, application server specific steps are encoded in separate build scripts for each application server. Using generic build as described in the previous section, the openbooks.war web archive need to be deployed manually. For WebSphere Application Server, automated build scripts are available in build.jee.was.xml. WebSphere deployment needs to be triggered by ws_ant utility as follows $ ws_ant -Dbuild.mode=jee -Dappserver=was -Dwas.home=WAS_HOME where WAS_HOME denotes the root directory where WAS V7 with JPA 2.0 feature pack has been installed. Yes, OpenBooks requires the WAS V7 JPA 2.0 feature pack with a profile augmented to run with the feature pack. Further information on this feature pack is available here. The WebSphere specific build will configure appropriate JTA data sources using a python script (found under openbooks/scripts/ directory before deploying OpenBooks as a web application. The script assumes a single server instance. If multiple profiles exist, the script will use the first server profile. Run OpenBooks If you have built OpenBooks for JSE, then go to the target/openbooks directory. Invoke the Ant script to run OpenBooks $ ant -f run.xml If you have build OpenBooks for JEE, a Web Application Archive openbooks.war will be created in target/openbooks directory. You need to deploy openbooks.war to a JEE Application Server. Once deployed, you can point a browser to Application Server URL http:// < app server host >:<port>/openbooks/ to access OpenBooks as an web application. Populate OpenBooks Database 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. Note: By default, the OpenBooks example uses and populates an Embedded Derby instance. So, no further configuration or loading is required for the default configuration. Edit load.properties 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 $ ant -f run.xml load Change Notification Preferences View Online | View Changes | Add Comment