Dali Object-Relational Mapping Tool

Create a database connection

After creating and populating the database you will need to create a database connection to use with the tutorial application. An active database connection is required to complete the tutorial application.

1. In Eclipse, use the New Connection wizard to create a database connection. Refer to "Creating a Connection Profile" in the Eclispe online help for more information.

   
   

   Note: Use the SQL Model-JDBC Connection profile to create the connection.

   
   

   Creating a Database Connection

   
   

2. Open the Data Source Explorer view to display the tutorial database.

Database Explorer

Build the entities

Before mapping the entities to the database, you must add the necessary fields to each entity.

1. Add the following fields to the Inventory entity:

   protected double cost;
   private long id;
   protected Item item;
   protected double price;
   protected int quantity;
   protected int version;
   
   

   Add get() and set() methods for the following:

   • cost

   • item

   • price

   • quantity

2. Add the following fields to the Item entity:

   protected String category;
   protected String description;
   protected String name;
   protected long sKU;
   protected int version;
   
   

   Add get() and set() methods for the following:

   • category

   • description

   • name

   • SKU

   • version

3. Add the following fields to the Order entity:

   protected Date arrivalDate;
   protected String currentLocation;
   protected Item item;
   protected long orderId;
   protected Date orderInitiated;
   protected int quantity;
   protected int version;
   
   

   Import java.util.Date.

   Add get() and set() methods for the following:

   • arrivalDate

   • currentLocation

   • item

   • orderId

   • orderInitiated

   • quantity

Create persistent entities and associate with a database table

Now you will change each class to a persistent entity. You must also associate each entity with its primary database table.

1. In the Package Explorer view, open Inventory.java.

2. In the JPA Structure view, select the Inventory entity.

3. In the JPA Details view, in the Map As field select Entity. Eclipse adds the @Entity annotation to the class.

4. In the Package Explorer view, right-click the persistence.xml file select JPA Tools > Synchronize Classes. This will update the persistence.xml file with the newly added entity.

   Synchronizing the persistence.xml File

   
   

   In the JPA Structure Properties view, notice that Dali has automatically identified the default table, Inventory, associated with the entity.

   JPA Details view for the Inventory Entity

   
   

Repeat this procedure to create entities from the Item and Order classes and then associate the entities with the database tables. By default, entities are associated with a similarly named database table and Dali identifies these defaults. Like the Inventory entity, even though you have not explicitly associated the Item entity with a database table, there is no error in the Problems view because the entity name, Item, is identical to the table name (Item).

Because the Order entity is named differently than the database table (ORDER_TABLE), you must explicitly create the association (as shown in Figure: JPA Details view for the Inventory Entity). Dali adds the @Table(name="ORDER_TABLE") annotation to the Order entity.

Remember to resynchronize the persistence.xml file after creating and associating the entities.

Create ID mappings

Use an ID Mapping to specify the primary key of an entity. Each persistent entity must have an ID. Notice that the Problems view reports that each entity "does not have Id or EmbeddedId."

1. In the Package Explorer view, open Inventory.java.

2. Expand the Inventory entity in the JPA Structure view and select the id field. The JPA Details view displays the properties for the field.

3. In the Map As field, select ID.

   ID Mapping for id Field

   
   

4. Use this table to complete the remaining fields on the General tab in the Persistence Properties view.

   Property	Description
   Map As	Defines this mapping as an ID Mapping. Dali adds the @Id annotation to the entity.
   Column	The database column for the primary key of the table associated with the entity. Select ITEM_SKU. Because the database column (ITEM_SKU) is named differently than the entity field (id), Dali adds the @Column(name="ITEM_SKU") annotation. Anytime you override the default, Dali adds the @Column annotation.
   Insertable	The value of the id field is obtained from the Item entity. Select False. Dali adds insertable = false to the annotation.
   Updatable	The value of the id field is updated from the Item entity. Select False. Dali adds updatable = false to the annotation.

   
   

In the JPA Details view, the id field is identified as the primary key by the following icon:

JPA Structure for Inventory Entity

Repeat this procedure to map the following primary keys (as shown in Table: Tutorial Database Schema):

• The SKU field of the Item entity to the SKU column of the ITEM table.

• The orderId field of the Order entity to the ORDERID column of the ORDER_TABLE table.

For both of these mappings:

1. Expand the Primary Key Generation area.

   Primary Key Generation for id Field

   
   

2. Select the Primary Key Generation option.

3. Use this table to complete the remaining fields in the JPA Details view.

   Property	Description
   Generated Value	These fields define how the primary key is generated. Dali adds the @GeneratedValue annotation to the entity.
   Strategy	For the tutorial project, leave this as the Default (Auto).
   Generator Name	Leave this field blank.

   
   

Create basic mappings

Use a Basic Mapping to map an attribute directly to a database column. In the object model, the quantity field of the Inventory class maps directly to the QUANTITY column of the INVENTORY database table.

1. In the Package Explorer view, open Inventory.java.

2. In the JPA Structure view, select the quantity field of the Inventory entity. The JPA Details view displays the properties for the field.

   Notice that Dali has already identified the mapping as the Basic mapping type. By default, all attributes of the following types use Basic mapping: Java primitive types, wrappers of the primitive types, java.lang.String, java.math.BigInteger, java.math.BigDecimal, java.util.Date, java.util.Calendar, java.sql.Date, java.sql.Time, java.sql.Timestamp, byte[], Byte[], char[], and Character[].

3. Basic Mapping for quantity

   
   

Notice that Dali has automatically identified the QUANTITY field and INVENTORY table for this mapping. Dali identifies the defaults for the mapping.

In the JPA Details view, the quantity field is identified as a basic mapping as shown in the following figure:

JPA Details view for Inventory Entity

Repeat this procedure to review each of the following Basic mappings:

• Item entity

  • description field to DESCRIPTION column

  • name field to NAME column

  • category field to CATEGORY column

• Order Entity

  • orderInitiated field to ORDERINITIATED column

    In the JPA Details view, use the Temporal field to select Date. Dali adds the @Temporal(DATE) annotation to the mapping.

  • arrivalDate field to ARRIVALDATE column

    In the JPA Details view, use the Temporal field to select Date. Dali adds the @Temporal(DATE) annotation to the mapping.

  • currentLocation field to CUURENTLOCATION column

  • quantity field to QUANTITY column

• Inventory Entity

  • cost field to COST column

  • price field to PRICE column

Create one-to-one mappings

Use a One-to-One Mapping to define a relationship from an attribute to another class, with one-to-one multiplicity to a database column. In the object model, the item field of the Inventory class has a one-to-one relationship to the Item class; each inventory object contains a single item.

1. In the Package Explorer view, open Inventory.java.

2. In the JPA Structure view, select the item field of the Inventory entity. The JPA Details view displays the properties for the field.

3. In the Map As field, select One-to-One.

   One-to-one Mapping for item

   
   

4. Dali has identified the default Target Entity for the mapping: org.eclipse.dali.example.jsf.inventory.model.Item.

   Leave the other fields with their default values.

In the JPA Structure view, the item field is identified as a one-to-one mapping, as shown in the following figure:

JPA Structure view for Inventory Entity

Repeat this procedure to create the following additional one-to-one mapping:

• Create a one-to-one mapping from the item attribute of the Order entity to the Item.

Create version mappings

Use a Version Mapping to specify the database field used by a persistent entity for optimistic locking.

1. In the Package Explorer view, open Inventory.java.

2. In the JPA Structure view, select the version field of the Inventory entity. The JPA Details view displays the properties for the field.

3. In the Map As field, select Version.

   Version Mapping for version

   
   

Notice that Dali has identified the default column in the INVENTORY database table. In the JPA Details view, the Version field is identified as a version mapping, as shown in the following figure:

JPA Details view for Inventory Entity

Repeat this procedure to create following version mappings:

• version attribute of the Order entity

• version attribute of the Item entity

Add resources

Add the following resources to the Dali_Tutorial_Application project's WebContent/WEB-INF/lib directory:

• JPA JARs (for this tutorial, use toplink-essentials.jar from the TopLink Essentials JPA)

• JSF JARs (for this tutorial, use the jsf-api.jar and jsf-impl.jar files from the JSF 1.1 library)

• Database JDBC JAR (for this tutorial, use derbyclient.jar)

Associate the model project

Use this procedure to associate the Dali_Tutorial_Model project with the Dali_Tutorial_Application project.

1. Right-click the Dali_Tutorial_Application project in the Explorer and select Properties.

2. Click J2EE Module Dependencies, select the Dali_Tutorial_Model project, and click OK.

   Project Build Path

   
   

Add the project files

The Dali_Tutorial_Web.zip (included with http://www.eclipse.org/webtools/dali/docs/tutorial/jsf/Dali_Tutorial_Application.zip) file contains the non-entity source files and Web content files for the dynamic Web project. Unzip the Dali_Tutorial_Web.zip file into your Dali_Tutorial_Application project's directory.

Dali_Tutorial_Application.zip Project