Example: Web Application (JSF) Using JPA

Version: 8/30/06 GlassFish: Version 2, Build 11

Introduction

This example will walk you through the basic steps of packaging and deploying a Web application using the EJB 3.0 Java Persistence API (JPA).

In this application, a Java Server Faces (JSF) presentation layer will make use of JPA for persistence outside of an EJB 3.0 container.

Figure 1-1 shows the object model that this example uses.

For more information on JPA, see:

Required Software

Setup and Configuration

Before starting this example, you must setup and configure the required software:

  1. Install JDK 5.0

  2. Install Ant

  3. Install the example and example source files:

    • Create a directory in which to unzip the example source files.

      This is the <EXAMPLE_HOME> directory.

    • Unzip the order-jsf-jpa-example.zip file to the <EXAMPLE_HOME> directory.

      This directory contains the example source.

    For more information about the structure and content of the <EXAMPLE_HOME> directory, see Understanding the Example Source Files.

  4. Install and setup your relational database:

  5. Install and setup your Web container:

  6. Install TopLink JPA:

    • Move the TopLink JPA installer JAR file to a temporary directory.

    • Execute the TopLink JPA installer JAR file you downloaded by entering the following on the command line (you must use JDK 1.5):

      java -jar glassfish-persistence-installer-X.X-bXX.jar

    • Scroll down to the end of the license agreement and click Accept.

      The installer un-packs the README, license files, and the TopLink Essentials JAR files as follows: 

      glassfish-persistence\README
glassfish-persistence\3RD-PARTY-LICENSE.txt
glassfish-persistence\toplink-essentials.jar
glassfish-persistence\toplink-essentials-agent.jar
glassfish-persistence\CDDLv1.0.txt

    • Add toplink-essentials.jar and toplink-essentials-agent.jar to <EXAMPLE_HOME>\lib.

  7. Configure your persistence unit to match your database (see Configuring the Persistence Unit).

  8. Create database tables and populate them with data:

    • From the command line, change directories to the <EXAMPLE_HOME> directory and execute: 

      ant -f build.xml generate-tables
ant -f build.xml populate-data

    • Confirm that TABLE CREATE statements are visible in the log messages written to standard out.

      If they are, then you are connecting to the database successfully.

      If they are not, then you are not connecting to the database. In this case, confirm your persistence.xml file settings and ensure that your database is up and running.

  9. Package and deploy the example to your Web container (see Packaging and Deployment).

  10. Run the application (see Running the Application).

    Confirm that you can see the example application main page as Figure 1-2 shows.

Understanding the Example Source Files

After unzipping the order-jsf-jpa-example.zip (see Setup and Configuration), you have an <EXAMPLE_HOME> directory.

This directory contains the structure that Example 1-1 shows. Table 1-1 describes the important content of this directory.

Table 1-1 Important Subdirectories in <EXAMPLE_HOME>

SubdirectoryDescription

extras/

Contains source files that are not directly executed by the example application.

     classes/

The directory in which the extra/src source files are compiled by the example build.xml Ant script.

     src/

The src/oracle/toplink/jpa/example/inventory/tools/ directory contains helper classes that you can optionally invoke with example build.xml Ant script targets:

  • generate-tables - invokes DDLGenerator to generate the example application's database tables.

  • populate-data - invokes Populator to populate the example application's database tables.

lib/

The lib directory contains all the JAR files that the example application depends on. In particular, this includes:

  • JSF and JSTL JARs (included)

  • JDBC driver JARs (user-supplied)

  • TopLink JPA JAR files (user-supplied)

persistence-unit/

Contains the source files for persistent JPA entities.

     classes/

This is a temporary directory where the persistence unit source files are built before packaging into the persistence unit archive.

     deploy/

This directory will contain the built and packaged persistence unit persistence-unit.jar file.

     src/

This directory contains the sources required for the persistence unit including the domain classes.

It also contains the persistence.xml file located in the sub-directory META-INF, as per the JPA specification.

web-application/

Contains the source files that implement the services and user interface of the example application that use the JPA entities.

     classes/

This is a temporary directory where the sources are built before packaging into the deployable archive.

     deploy/

This directory will contain the built deployable Web application, jpa-example.war. This is built using the ant target package.webapp.

     public_html/

Contains the presentation layer of the application including JSPs, stylesheets ( css/), images ( images/), and deployment descriptor ( WEB-INF/web.xml).

     src/

This directory includes the sources for the controller layer of the application.

  • The oracle/toplink/jpa/example/inventory/services directory contains the sources for the services interfaces that provide access to the persistence layer:

  • The oracle/toplink/jpa/example/inventory/services/impl directory contains the classes that implement the service interfaces.

    The ManagedOrderBean implements the OrderService interface.

    The ManagedInventoryBean implements the InventoryService interface.

    The JPAResourceBean is a helper class that the example application uses to acquire an EntityManager for the example application's persistence unit.

  • The oracle/toplink/jpa/example/inventory/ui directory contains the InventoryManagerBean class that drives the example application user interface.


Configuring the Persistence Unit

The entity manager is the primary JPA interface you use to perform basic persistence operations on your entities (create, read, update, and delete).

A persistence unit defines an entity manager's configuration by logically grouping details like entity manager provider, configuration properties, and persistent managed classes.

Each persistence unit must have a name. Only one persistence unit of a given name may exist in a given EJB-JAR, WAR, EAR, or application client JAR. You specify a persistence unit by name when you acquire an entity manager factory.

You define persistence units in the persistence.xml file.

To configure the persistence unit:

  1. Using the editor of your choice, open the <EXAMPLE_HOME>\persistence-unit\src\META-INF\persistence.xml file.

  2. Replace the <!-- class list goes here --> comment with a <class> element for each of the persistent JPA entity classes: 

    <class>oracle.toplink.jpa.example.inventory.model.Inventory</class>
<class>oracle.toplink.jpa.example.inventory.model.Order</class>
<class>oracle.toplink.jpa.example.inventory.model.Item</class>

  3. Set the following properties to match your relational database:

    <property name="
              
toplink.jdbc.driver" value="<jdbc-driver>"/>
<property name="
              
toplink.jdbc.url" value="<jdbc-url>"/>
<property name="
              
toplink.jdbc.password" value="<jdbc-password>"/>
<property name="
              
toplink.jdbc.user" value="<jdbc-user>"/>

    Where:

    • <jdbc-driver> is the name of your JDBC driver class. Example: oracle.jdbc.OracleDriver.

    • <jdbc-url> is the JDBC connection URL to your database. Example: jdbc:oracle:thin:@myhost:l521:MYSID.

    • <jdbc-password> is the JDBC password you use to connect to your databse. Example: tiger.

    • <jdbc-user> is the JDBC user name you use to connect to your databse. Example: scott

    Your persistence.xml file should look like Example 1-2.

    Example 1-2 Persistence Unit in Persistence.xml

    ...
    <persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
        <provider>
           oracle.toplink.essentials.PersistenceProvider
        </provider>
        <class>oracle.toplink.jpa.example.inventory.model.Inventory</class>
        <class>oracle.toplink.jpa.example.inventory.model.Order</class>
        <class>oracle.toplink.jpa.example.inventory.model.Item</class>
        <properties>
            <property name="toplink.logging.level" value="FINE"/>
            <property name="toplink.jdbc.driver" value="oracle.jdbc.OracleDriver"/>  <!-- update to match database-->
            <property name="toplink.jdbc.url" value="jdbc:oracle:thin:@localhost:1521:XE"/> <!-- update to match database-->
            <property name="toplink.jdbc.password" value="tiger"/> <!-- update to match database-->
            <property name="toplink.jdbc.user" value="scott"/> <!-- update to match database-->
        </properties>
    </persistence-unit>
...

    The name of this persistence unit is default.

    Its transaction-type is RESOURCE_LOCAL, meaning that entity managers for this persistence unit do not participate in JTA transactions.

    It uses provider oracle.toplink.essentials.PersistenceProvider.

    Finally, persistence unit properties are set. You can use persistence unit properties to fine-tune the underlying JPA persistence provider and to specify the connection details for the underlying relational database that this persistence unit should be associated with.

    For more information, about TopLink JPA persistence provider extensions, see TopLink JPA Extension Reference.

    For more information about the persistence.xml file, see JSR-000220 Enterprise JavaBeans v3.0 JPA specification, section 6.3.

  4. Save and close the file.

Packaging and Deployment

This section describes how to package and deploy the tutorial application, including:

Compiling and Packaging the Application

To compile and package the tutorial application, from the command line, change directories to the <EXAMPLE_HOME> directory and execute the following: 

ant -f buld.xml package.webapp

This creates <EXAMPLE_HOME>\web-application\deploy\jpa-example.war.

In this tutorial, we package the persistence unit in WEB-INF\lib\persistence-unit.jar within the jpa-example.war file. By confining the persistence unit to its own JAR file, you can easily re-use the persistence unit in other applications.

Deploying to OC4J

To deploy the tutorial application to OC4J:

  1. Verify that the following system properties are set:

    • JAVA_HOME - set to your JDK 1.5 installation.

      Example: C:\Program Files\Java\jdk1.5.0_06

    • ORACLE_HOME - set to your OC4J installation directory

      Example: C:\OC4JHome

    • PATH - your path must include %JAVA_HOME%\bin

  2. Start OC4J from the command line:

    On Windows:

    cd %ORACLE_HOME%
cd bin
oc4j.cmd -start

    On UNIX:

    cd %ORACLE_HOME%
cd bin
oc4j.sh -start

  3. Log into the Oracle Enterprise Manager Application Server Control console:

    Start a browser and enter the following URL: http://<hostname>:8888/em/console/ias/oc4j/administration

    Where <hostname> is the name of the computer you started OC4J on.

  4. Select Home > Applications and click the Deploy button.

  5. In the Archive area, click the radio button next to Archive is present on local host.

  6. Click the Browse button and locate the jpa-example.war file.

  7. Click Next.

  8. Enter an application name without spaces. For example, "JSF-JPA-Tutorial" and then click Next.

  9. Click Deploy.

    Confirm that the application deploys successfully according to the displayed log message "Application Deployer for JSF JPA Tutorial COMPLETES".

  10. Click Return.

    Confirm that the "JSF JPA Tutorial" application is listed in the Applications tab.

Deploying to Tomcat

To deploy the tutorial application to Tomcat:

  1. Verify that the following system properties are set:

    • JAVA_HOME - set to your JDK 1.5 installation.

      Example: C:\Program Files\Java\jdk1.5.0_06

    • CATALINA_HOME - set to your Tomcat installation directory.

      Example: C:\apache-tomcat-5.5.17

    • PATH - your path must include %JAVA_HOME%\bin

  2. Copy the jpa-example.war file to the Tomcat CATALINA_HOME\webapps directory.

  3. Start Tomcat from the command line:

    On Windows:

    cd %CATALINA_HOME%
cd bin
startup.cmd

    On UNIX:

    cd $CATALINA_HOME
cd bin
startup.sh

  4. Confirm that the application deploys successfully by looking for the log message "deployWAR INFO: Deploying web application archive jpa-example.war" on standard out or in the CATALINA_HOME/logs/catalina.out log file.

Left Curve
Popular Downloads
 Right Curve
Untitled Document