Rapid JPA development with Rational Application Developer 8.5.x: Create JPA entities with Rational Application Developer 8.5.1

Learn how to create Java Persistence Architecture (JPA) entities using preexisting relational tables that use database-generated primary key values. You will use Rational Application Developer to build JPA entities easily from an IBM DB2 database.


Ali Manji (amanji@ca.ibm.com), Software Developer, IBM China

author photoAli Manji is a software developer with the Rational Insight team. He has several years of experience with Rational software and in working with many IBM offerings. You can follow him on Twitter @torontoIBMer or read his developerWorks blog, Random Rational Tidbits.

19 March 2013

After completing the steps in this article, you will be able to generate JPA beans from pre-existing relational tables, where the database generates the primary key values.

Before you start

This article revisits a previous article, "Create bottom-up JPA entities with Rational Application Developer, DB2, and WebSphere Application Server," cited in Resources. It updates the discussion and instructions for these three applications, which you use to construct the application:

  • IBM® Rational® Application Developer, Version 8.5.1
  • IBM® WebSphere® Application Server, Version (by using the WebSphere Test Environment that is available with Rational Application Developer)

    Note: After installing both Rational Application Developer 8.5 and WebSphere Application Server 8.5, use the IBM Installation Manager to find and apply fix packs and other maintenance updates to your installation to match the levels described here.
  • IBM® DB2® Enterprise Server Edition database, Version 10.1, Fix Pack 2, for Microsoft Windows

Extract the files in the resources.zip file (see the Downloads section) to a location of your choice in your file system. It contains two files:

  • MembersDB2_10_1.sql, a script to create your initial DB2 database
  • AcmeMembershipApplication.ear, the beginnings of your enterprise JPA application

Set up 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 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 have, at most, one primary member. The primary member is responsible for keeping the membership in good standing and for paying the annual fees.

In addition to having a primary member, a family membership normally has 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.

Create the Acme membership database

Acme's membership database is a core piece of its membership application, so begin by creating the database.

  1. From your Windows Start menu, select Start >All Programs > IBM DB2 > DB2Copy1 (Default) > Command Window.
  2. From the Command Window, type db2 -tvf C:\MembersDB2_10_1.sql and press Enter. Note: This assumes that you extracted the MembersDB2_10_1.sql file to your C: directory.
  3. Upon successful execution of the SQL and DDL commands, finish by closing the Command Window.

Before you generate the JPA entities, you need to complete two more steps:

  • Import the beginnings of a Java Enterprise Edition (JEE) Application Project that has a Java Enterprise Project and a corresponding Web Project.
  • Create a connection to the Acme Membership database.

Import the membership application into Rational Application Developer

  1. Start Rational Application Developer 8.5 using a workspace location of your choice and these selections: Start > IBM Software Delivery Platform > IBM Rational Application Developer for WebSphere Software.
  2. When prompted to enter a workspace location, select the default location or enter another convenient location.

If you are using a new workspace, you should see the Configuring the WebSphere Application Server dialog window shown in Figure 2.

  1. For Package group name, select IBM WebSphere Application Server V8.5 from the drop-down menu, and click Finish.
Figure 2. Configuring the WebSphere Application Server for use with a new workspace
runtime environment and profile settings window
  1. If the Welcome window appears, go ahead and close it.
  2. If you are not already in the Java EE perspective, open it.
  3. Import the initial EAR project that you will build upon.
  4. From the toolbar, select File > Import > Java EE > EAR File, and then click Next.
  5. Click the Browse button, navigate to the location where you saved the file AcmeMembershipApplication.ear, and select it.
  6. For Target runtime, select WebSphere Application Server v8.5.
  7. Click Finish.

Upon successful import, you will have the project layout shown in Figure 3, with two new projects:

  • An enterprise application project, AcmeMembershipApplication
  • A corresponding web module project, AcmeMembersWeb

You will see errors in the Markers view, but you can safely ignore those for now.

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

The web project has a servlet that you will run to populate your database with sample data.

Set up the data connection

To make Rational Application Developer aware of the ACMEMBRS database, you need to establish a data connection to it.

  1. Switch from the Java EE Perspective to the Data Perspective. Select Window > Open Perspective > Other > Data.
  2. In the Data Source Explorer view under the Database Connections folder, you should see the ACMEMBRS database listed. Right-click, and select Properties.
  3. In the Properties window, select the Driver Properties leaf and, in the details screen, enter the DB2 account user name and password. For convenience, make sure to check the Save password check box.
  4. Try testing the connection by clicking the Test Connection button. Click OK after you see a message that says Ping succeeded!
  5. Select the ACMEMBERS database under the Database Connections folder in the Data Source Explorer view, right-click, and select Connect.

Create your JPA project and entities

We will generate the JPA entities from the ACMEMBRS database tables. These JPA entities provide the foundation of the business logic for Acme's membership system.

Create a JPA project

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

  1. Switch to the JPA perspective. Select Window > Open Perspective > Other > JPA
  2. Select File > New > JPA Project to bring up the New JPA Project wizard.
  3. For the project name, enter AcmeMembershipApplicationDomain.
  4. Make sure that the Add project to an EAR is checked and that AcmeMembershipApplication is selected in the EAR project name drop-down menu, and then click Next.
  5. Click Next again on the Java page of the New JPA Project wizard.
  6. In the JPA Facet page of the wizard, select ACMEMBRS from the Connection drop-down menu.
  7. Click Finish.

Generate the JPA entities

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

  1. Right-click the new JPA project, AcmeMembershipApplicationDomain, and select JPA Tools > Generate Entities from Tables.
  2. On the Select Tables page in the Generate Custom Entities wizard:
    1. Select ACMEMBRS from the Connection drop-down menu.
    2. Select Administrator from the Schema drop-down menu.
    3. Be sure to check all tables listed in the Tables list.
    4. Ensure that the Update class list in persistence.xml check box is checked.

The Select Tables page of the Generate Custom Entities wizard should look like Figure 4.

Figure 4. 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 results shown in Figure 5, Figure 6, Figure 7, and Figure 8.
  3. As you complete the actions in each view, click Next to proceed to the next screen.

In the Table Associations screen shown in Figure 5, 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 5. Editing the relationships for Dependent, Membership
Cascade all selected for membership, dependents

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

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

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

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

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

Figure 8. 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 (Figure 9):
    1. Select identity from the Key generator drop-down menu.
      Here, you are indicating that you want to use the Identity Generation scheme as the approach for generating unique values for primary key attributes for your JPA beans.
    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.
Figure 9. Customize Default Entity Generation view
Set some default characteristics of the JPA entities
  1. Click Next.
  2. On the Customize Individual Entities page of the Generate Custom Entities wizard (Figure 10), you can customize numerous characteristics for both the classes and their underlying attributes:
    1. Under "Tables and columns," expand Dependent and select the BIRTHDATE column.
    2. From the corresponding "Mapping type" drop-down menu, select java.util.Calendar.
Figure 10: Customize Individual Entities view
Change some attribute types from the defaults
  1. Repeat the previous step for these attributes:
    1. BIRTHDATE column in the PRIMARYMEMBER table
    3. MEMBERSINCE columns in the MEMBERSHIP table
  2. Click Finish.

You can browse the generated JPA entities in the AcmeMembershipApplicationDomain project.

Adjust the JPA entities

The JPA entities now require adjustments to ensure that they reflect the business and application domain accurately.

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

To reflect the constraints of the business rules for Acme's membership administration, you need to make a few adjustments to your JPA entities, namely:

  • Tighten the cardinality for some of the relationships from many-to-one to one-to-one.
  • Reduce the navigational 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

Step 5 is necessary 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 run a servlet to create a new family membership in the Acme membership system.

  1. Ensure 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. In the "Set up connections for deployment" dialog window, from the Connection drop-down menu, select the ACMEMBRS data connection.
  4. Ensure that other check boxes and values match those in the screen capture in Figure 12, and then click OK.
Figure 12. The "Set up connections for deployment" dialog window
ACMEMMBRS selected for Connection field
  1. Switch from the JPA perspective back to the Java EE perspective.
  2. In the Enterprise Explorer view, expand AcmeMembershipApplicationWeb > AcmeMembershipApplicationWeb > Servlets.
  3. Right-click org.acme.membership.admin.AddMembershipServlet, and select Run As > Run on Server.
  4. If the Run on Server dialog wizard appears, select WebSphere Application Server v8.5 at localhost and check the Always use this server when running this project check box before clicking Finish.

After the WebSphere server has started, it will run your servlet and open a web page, indicating success in creating a new membership. The web page will ask you to look at your database tables to see the values in the various tables to confirm the creation.


This article explained how to use Rational Application Developer to rapidly generate and customize JPA entities from a DB2 database with these characteristics:

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

The productivity-boosting wizards, views, and editors in Rational Application Developer environment let you create and tailor your JPA entities, thus freeing you from writing any code by hand.

Part 2 will cover:

  • Using your JPA beans to generate JPA Manager Beans to assist with the creation and retrieval of data
  • Using your managed JPA bean to view information through a JavaServer facelet web page


The author thanks Robin Wood for her support in bringing this article to developerWorks and Judith Broadhurst for her care and professionalism to make it so much better.


The beginnings of your enterprise JPA applicationAcmeMembershipApplication.zip12KB
A script to create your initial DB2 databaseMembersDB2_10_1.zip2KB



Get products and technologies



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

ArticleTitle=Rapid JPA development with Rational Application Developer 8.5.x: Create JPA entities with Rational Application Developer 8.5.1