JPA with Rational Application Developer 8 and WebSphere Application Server 8

Use the Identity Value Generation strategy and other advanced design options

Learn how to create Java Persistence Architecture (JPA) entities that are built from pre-existing relational tables, that use database-generated primary key values, and are part of a composition (or aggregation) of one or more other JPA entity beans. You will use Rational Application Developer tools to rapidly generate and customize JPA entities from a Derby database with tables that use the Identity Value Generation capability. Using the views and editors increases your productivity by freeing you from hand coding the required annotations.

Ali Manji (amanji@ca.ibm.com), Software Analyst, Rational Accelerated Value Program, IBM

photo of Ali Manji

Ali Manji is a software engineer at the IBM Toronto Lab and works with the WebSphere Studio Application Developer Service team. You can reach Ali at amanji@ca.ibm.com .



28 June 2011

Also available in

This article revisits one published by IBM® developerWorks® in 2010, "Create bottom-up JPA entities with Rational Application Developer, DB2, and WebSphere Application Server" (cited in Resources) by updating the discussion and instructions for these applications:

  • IBM® Rational® Application Developer version 8.0.2 development environment
  • IBM® WebSphere® Application Server version 8.0 beta (targeting the newly released Java Enterprise Edition (JEE) 6.0 specification)
  • Apache Derby version 10 database

However, the focus for this article will remain on the creation of these types of Java Persistence Architecture (JPA) entities:

  • Generated from pre-existing relational tables (sometimes referred to as a "bottom-up" approach)
  • Use database-generated primary key values for the ID attribute
  • Are part of a composition (or aggregation) of one or more other JPA entity beans (for example, one-to-one or many-to-one relationships)

Although they are not the focus for this article, the application will use an Enterprise JavaBean (EJB) 3.1 Stateless Session Bean and a servlet that uses the Servlet 2.5 specification.

Before you start

To construct the application, you will need to use these applications:

  • IBM Rational Application Developer Version 8.0.2.


Note:
After installing Version 8.0, use the IBM Installation Manager to discover and apply fix packs and other maintenance to update your installation to 8.0.2 or later.

  • IBM WebSphere Application Server 8.0 beta, March Refresh image (by using the WebSphere Test Environment that is available with Rational Application Developer).
    Note: You will need to download and install the March 2011 beta refresh image (see Resources for a link), because you will not be able to use the earlier version of the 8.0 Beta shipped with Rational Application Developer Version 8.0.2.
  • Derby database Version 10 provided by Rational Application Developer

Also, extract the resources.zip file (see the Downloads section) to a location of your choice in your file system. It should contain two files:

  • members.sql
  • AcmeMembershipApplication.ear

These resources include a script to create your initial Derby database and an Enterprise Archive (EAR) file that contains artifacts to begin developing your Java Enterprise Edition (JEE) application.


Work with the Acme membership system

Figure 1 represents the physical relational database for Acme's membership subsystem.

Figure 1. The Acme membership data model
Diagram of 5 tables for Acme's membership database

To receive Acme Co.'s services and benefits, clients must become members. Clients can choose from Single, Student, or Family memberships (the membership_type field in the membership table identifies the type of membership). Family memberships provide Acme's services to couples and any children that they have who are under the age of 18. To remain members in "good standing," clients must renew their memberships annually.

All memberships will have, at most, one primary member. The primary member is responsible for keeping the membership in good standing and for paying the annual subscription fees.

In addition to having a primary member, a family membership will normally have one or more dependents. There are two types of dependents in a family membership: the spouse and any children younger than 18.

All correspondence between Acme Co. and its members occurs solely through the primary member. Acme collects the address and other contact information for the primary member for all memberships for this purpose.

Set up the WebSphere Application Server

The application you will build in this article will not run using the WebSphere Application Server Version 8.0 Beta that is included in Rational Application Developer Version 8.0. You need to download the WebSphere Application Server Version 8.0 beta March 2011 or later refresh. In addition, the WebSphere 8.0 beta that is included in Rational Application Developer v8.0 cannot be upgraded. This means that you must install the March 2011 v8.0 Beta refresh to a separate location. Fortunately, both versions will co-exist on the same machine.

After downloading and installing the WebSphere Application Server 8.0 beta March 2011 refresh, you need to create a server instance in Rational Application Developer.

  1. Start Rational Application Developer 8.0.2 using a workspace location of your choice. Start > IBM Software Delivery Platform > IBM Rational Application Developer for WebSphere Software 8.0.2.
  2. When prompted to enter a workspace location, select the default location provided or enter another convenient location.
  3. If the Welcome window appears, go ahead and close it.
  4. If you are not already in the Java EE perspective, open it.
    Note: The first time that you switch to this perspective, you could get a dialog window requesting you to enable certain activities or features. Click OK to accept any such requests.
  5. Within the Java EE perspective, in the Servers view, right-click and select New > Server.
  6. In the New Server wizard, expand the IBM folder, as shown in Figure 2, select WebSphere Application Server v8.0 Beta, and click Next.
Figure 2. Define a new server to deploy and test your applications
Define a new server window in the wizard
  1. Name your test environment server WebSphere Application Server v8.0 Beta March 2011 Refresh, as shown in Figure 3, to avoid confusion with the earlier version of WebSphere Application Server v8 beta included with Rational Application Developer v8. For the Installation directory field, browse to the location where you installed the WebSphere Application Server v8.0 beta March 2011 refresh.
  2. Click Finish.
Figure 3. Providing the location for the server runtime
New Server dialog window in RAD

Create the Acme membership database

Acme's membership application depends on the existing layout of the Acme database. You will recreate Acme's membership database tables using the embedded Derby database provided by Rational Application Developer.

  1. Open the Data perspective.
  2. In the Data Source Explorer view, right-click the Database Connections folder and select New.
  3. The New Connection wizard will appear. There are three things to change on the first page of the wizard:
    1. Select Derby from the list of choices in the Select a Database Manager: panel.
    2. From the JDBC driver: drop-down list, select Derby 10.2 – Embedded JDBC Driver Default.
    3. In the Database location: text box, update the default value (in Microsoft Windows, this is typically C:\Documents and Settings\Administrator\MyDB) to C:\Documents and Settings\Administrator\MembersDB.
Figure 4. Creating and connecting to a new Derby database
Connection Parameters view, New Connection wizard
  1. Click Finish.

Create the relational tables

Now that you have successfully created the Members database, you will create the relational tables. You will do this by running the members.sql script provided (see Downloads).

  1. Still within the Data perspective, right-click anywhere in the Data Project Explorer view and select New > Data Design Project.
  2. Enter MembersDBProject for the Project name.
  3. Click Finish.
  4. Right-click the newly created MembersDBProject project in the Data Project Explorer and select Import.
  5. In the Import dialog wizard, expand the General folder, select File System and click Next.
  6. To the right of the "From directory" text box, click the Browse button and navigate to the location where you downloaded and extracted the Members.sql file. Select Members.sql, and click Finish.
  7. Under the MembersDBProject project folder expand the SQL Scripts folder.
  8. Right-click Members.sql, and select Run SQL.
  9. In the Select Connection Profile dialog window, in the Connections list, select MembersDB and click Finish.

If you explore your connection to the Members database through the MemberDB connection, you will notice the creation of new tables in the APP schema.


Use the Identity Value Generation strategy

Having the database generate values for the primary key for a table (and by extension, any foreign key values for related tables) eliminates the burden from the application to do so. That is, not having to generate unique key values for persistent objects within the application allows the focus to remain on core business logic and business rules. This has the positive consequence of enhancing the application's maintainability and readability.

In this scenario, Acme's lead data and application architects want to use the Identity Value Generation approach to remove that burden from the business logic of their various applications. To leverage that capability, JPA can delegate assignment of an entity's ID attribute to the relational database.

The primary key fields in the relational tables for the MembersDB are set to generate unique values to adhere to the identity value generation strategy that Acme developers want to take.

Before you generate the JPA entities, you need to import the beginnings of a JEE 6.0 Enterprise Application project that will have an EJB project and a web project.


Import the membership application into Rational Application Developer

  1. Switch back to the Java EE perspective.
  2. Import the initial EAR project that you will build upon:
    1. From the menu bar select File > Import > Java EE > EAR File, and then click Next.
    2. Click the Browse button, navigate to the location where you saved the file AcmeMembershipApplication.ear, and select it to import.
      Important: For Target runtime, make sure that you select the "WebSphere Application Server v8.0 Beta March 2011 Refresh" server that you previously created.
    3. Click Finish.

Upon successful import, you will have a project layout as shown in Figure 5. There will be three new projects:

  • An enterprise application project
  • A corresponding web module project
  • An EJB module project

You will see errors in the Markers view that you can safely ignore for now.

Figure 5. Acme's enterprise application projects
Enterprise Explorer tab view shows 3 projects

The EJB project has a stateless session EJB that you will use to invoke your JPA entities to create new members and memberships.

The web project has a simple single servlet that you can easily run in your WebSphere Test Environment to invoke your business logic.


Generate the JPA entities

In this section, you will generate the JPA entities from the Members database tables. These JPA entities provide the foundation of the business logic for Acme's membership system.

First, create a JPA project to host your JPA entity beans:

  1. Switch to the JPA perspective. Select File > New > JPA Project to bring up the New JPA Project wizard.
  2. For the Project name, enter AcmeMembershipApplicationDomain.
  3. Make sure that the Add project to an EAR is checked, and then click Next.
  4. Click Next again on the Java page of the New JPA Project wizard.
  5. In the JPA Facet page of the wizard, select MembersDB from the Connection drop-down list.
  6. Click Finish. If you are asked to switch to the JPA perspective, click Yes.

Now that you have a JPA project created, you can generate your JPA entities:

  1. Right-click the new JPA project that you created, AcmeMembershipApplicationDomain, and select JPA Tools > Generate Entities from Tables.
  2. On the Select Tables page of the Generate Custom Entities:
    1. Select MembersDB from the Connection drop-down list.
    2. Select APP from the Schema drop-down list
    3. Be sure to check all tables listed in the Tables combination list.
    4. Check the Update class list in persistence.xml check box.

The Select Tables page of the wizard should look like Figure 6.

Figure 6. Selecting the tables from which to generate JPA entities
Select Tables in Generate Custom Entities wizard
  1. Click Next.
  2. On the Table Associations page of the Generate Custom Entities wizard, you have an opportunity to generate and shape relationships between the entities that you will generate. Select each of the table associations, and make the necessary edits and selections that give you the same result as shown in Figure 7, Figure 8, Figure 9, and Figure 10.
  3. Then click Next.

In the screen shown in Figure 7, you are setting the name of the attribute that provides the many-to-one relationship between the dependents in a family and a family membership.

Figure 7. Editing the relationships for Dependent – Membership
Cascade all selected for membership, dependents

Figure 8 shows setting the name of the attribute that provides the aggregate relationship between the primary member and that person's membership with Acme Inc.

Figure 8. Editing the relationship for PrimaryMember – Membership
Cascade all for primaryMember, plus check box

Figure 9 shows setting the name of the attribute that provides the aggregate relationship between the primary member and that member's residence address.

Figure 9. Editing the relationship for PrimaryMember – Address
Cascade all for address, plus check box

Figure 10 shows setting the name of the attribute that provides the aggregate relationship between the primary member and that member's contact information.

Figure 10. Editing the relationship for PrimaryMember - ContactInfo
Cascade all for contactInfo, plus check box
  1. On the Customize Default Entity Generation page of the Generate Custom Entities wizard:
    1. Select identity from the Key generator drop-down list.
      Note: Here, you are indicating the desire to use the Identity Generation scheme as the approach for generating unique values for primary key attributes for your JPA domain classes.
    2. Choose Property for the Entity Access radio button.
    3. Select java.util.Set for the Collections Property Type radio button.
    4. For the Package field, enter org.acme.membership.domain.
    5. Click Next.
  2. On the Customize Individual Entities page of the Generate Custom Entities wizard, you can customize numerous characteristics for both the classes and their underlying attributes.
    1. Expand Dependent in the Tables and columns list box.
    2. Under Dependent, select the BIRTHDATE column.
    3. In the corresponding Mapping type drop-down list, select java.util.Calendar.
  3. Repeat Step 5 for the BIRTHDATE column in PRIMARYMEMBER and for the LASTRENEWALDATE and MEMBERSINCE columns in the MEMBERSHIP table.
  4. Click Finish.

Feel free to browse the generated JPA entities in the AcmeMembershipApplicationDomain project.


Adjust the JPA entities

The JPA entities now require some adjustments and enhancement before elaborating on them with further business logic. Adjustments are required to ensure that the entities reflect the business and application domain more accurately.

You will override the database interpretation of the relationship of some of the entities to be one-to-one rather than many-to-one. This will not affect the referential integrity or primary-foreign key relationships between the tables in the membership database. The reason for doing this is to make the application logic reflect the business rules and constraints that exist between the entities more closely.

Adjust Acme's JPA entities to one-to-one, unidirectional relationships

Assume that to reflect the constraints of the business rules for Acme's membership administration, you would like to make a few adjustments to your JPA entities:

  • Tighten the cardinality (from many-to-one to one-to-one) for some of the relationships.
  • Reduce the navigation flexibility for some of the relationships (from bidirectional to unidirectional).

Both of these changes will make the application more secure and less prone to breaking any of the business rules for Acme's membership application.

Change the cardinality of the relationship

  1. Open the JPA Primarymember entity.
  2. In the Java editor, select the address attribute.
  3. In the JPA Details view, select the many to one hyperlink, as shown in Figure 11.
Figure 11. Changing the cardinality of the relationship
JPA Details tab view
  1. In the Mapping Type Selection dialog window, select One to One and click OK.
  2. In the JPA Details view, uncheck the Optional check box and check the All check box for the Cascade options.
  3. Repeat Steps 1 through 5 for these attributes:
    • contactInfo attribute in the PrimaryMember JPA entity
    • primarymember attribute in the Membership JPA entity

Important:

Step 5 does not change the nature of the relationship of your JPA entities. However, it is a necessary step for making a complex object persistent (for example, an object composed of collections and an aggregation of other complex objects).


Run the Acme membership application

You will now deploy the Acme membership application to the Rational Application Developer WebSphere Test Environment. You will use a servlet to run the Acme membership function to create a new family membership.

  1. Make sure that you are still in the JPA perspective, and then select the AcmeMembershipApplicationDomain project from the Project Explorer view.
  2. Right-click and select JPA Tools > Configure Project for JDBC Deployment.
  3. Figure 12 illustrates the default values for the "Set up connections for deployment" dialog window. Ensure that the defaults are indeed the same as what you see; otherwise, make the necessary changes to match Figure 6.
  4. Click OK.
Figure 12. The "Set up connections for deployment" dialog view
MembersDB selected for Connection field
  1. Switch from the JPA perspective back to the Java EE perspective.
  2. In the Servers view, select the WebSphere Application Server v8.0 Beta at localhost, right-click, and select Add and Remove from the context-sensitive menu.
  3. Select the AcmeMembershipApplication project in the Add and Remove dialog wizard, and click the Add button.
  4. Click Finish.
  5. In the Enterprise Explorer view, expand AcmeMembershipApplicationWeb > AcmeMembershipApplicationWeb > Servlets.
  6. Right-click CreateMembershipServlet, and select Run As > Run on Server.
  7. If the Run On Server dialog wizard appears:
    1. Select WebSphere Application Server v8.0 Beta at localhost.
    2. Check the Always use this server when running this project check box (Figure 13).
    3. Click Finish.
Figure 13. The Run on Server dialog window
Always use this server box checked

After the WebSphere Test Environment server has started, it will invoke your servlet and open a web page, indicating success in creating a new membership. You can inspect the Derby database tables to confirm addition of the new membership record.


Summary

For this article, we used Rational Application Developer tools to rapidly generate and customize JPA entities from a Derby database that had these characteristics:

  • Tables that use the Identity Value Generation capability to create unique primary keys values
  • A nontrivial set of relationships between the tables

Using the Rational Application Developer environment enabled you to increase your productivity by using views and editors that helped you tailor your JPA entities, thus freeing you from hand coding the required annotations.

Finally, you ran your application by using the WebSphere Application Server conveniently embedded within the Rational Application Developer WebSphere Test Environment.


Acknowledgement

The author thanks Mike Reid for his thoughtful and thorough review of this article.


Download

DescriptionNameSize
This archive contains two filesresources8996.zip20KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, WebSphere
ArticleID=682475
ArticleTitle=JPA with Rational Application Developer 8 and WebSphere Application Server 8
publish-date=06282011