Instructions to download and run OpenBooks Demo¶
OpenBooks comes with
Follow the simple instructions below to build and run OpenBooks:
OpenBooks can be checked out from OpenJPA repository.
will check out the source code and build scripts of OpenBooks in current directory.
OpenBooks requires following software environment to run:
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 and build.jee.liberty.xml for build and installation steps for WebSphere Application Server and the Liberty Profile for WAS, respectively.
Before you run a build, configure the build environment by editing openjpa-examples/openbooks/build.properties. Essentially, you need to
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.
The next step is to configure runtime configuration descriptors and environment variables.
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 -Dbuild.mode=jee
The default target of the ant script will
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 target/openbooks.war web archive needs to be deployed manually.
WebSphere Application Server¶
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 (at a minimum). Yes, OpenBooks requires features defined by the JPA 2.0 specification, thus the use of the WAS V7 JPA 2.0 feature pack is a minimum requirement. Further information on this feature pack is available here or WebSphere in general.
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.
Liberty Profile in WebSphere Application Server v8.5¶
For the Liberty Profile in WebSphere Application Server v8.5, automated build scripts are available in build.jee.liberty.xml. Liberty Profile deployment is very easy and needs to be triggered by ant as follows
$ ant -Dbuild.mode=jee -Dappserver=liberty -Dliberty.home=<WAS_HOME>/wlp -Dliberty.server=<server name>
By specifying liberty.home and liberty.server, the ant script will attempt to "deploy" the resulting openbooks.war application to the designated Liberty server. Additional configuration of your Liberty server may be required before OpenBooks will work. For example, you will need to specify the jpa-2.0 and jdbc-4.0 features in your server.xml. You will also need to define the JTA datasources used by the OpenBooks application via your server.xml file. Examples of a derby configuration can be found in the openbooks/scripts/liberty directory.
If you have built OpenBooks for JSE, then go to the openjpa-examples/openbooks/target/openbooks directory.
Invoke the Ant script to run OpenBooks
$ ant -f run.xml
If you have built OpenBooks for JEE, a Web Application Archive openbooks.war will be created in openjpa-examples/openbooks/target 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 >:
to access OpenBooks as a 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 on "first touch". 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