6.2 Creating Entity Objects and Associations

The simplest way to create entity objects and associations is to reverse-engineer them from existing tables. Since often you will already have a database schema to work with, the simplest way is also the most common approach that you'll use in practice. When needed, you can also create an entity object from scratch, and then generate a table for it later as well.

6.2.1 How to Create Entity Objects and Associations from Existing Tables

To create an entity object, use the Business Components from Tables wizard. The wizard is available from the New Gallery in the Business Tier > ADF Business Components category. If it's the first component you're creating in the project, the Initialize Business Components Project dialog appears to allow you to select a database connection before the wizard will appear. These examples assume that you're working with an connection named SRDemo for the SRDEMO schema.

In step 1 on the Entity Objects page, you select a list of tables from the Available list for which you want to create entity objects. The Package field at the top allows you to indicate the package in which all of the entity objects will be created. If the Auto-Query checkbox is checked, then the list of available tables appears immediately, otherwise you need to click the Query button to retrieve the list after optionally providing a name filter. Once you have selected a table from the Available list, the proposed entity object name for that table appears in the Selected list with the related table name in parenthesis. Clicking an entity object name in the Selected list, you can use the Entity Name field below to change the default entity object name. Since each entity object instance represents a single row in a particular table, it is best practice to name the entity objects with a singular noun like User, Product, and ServiceHistory instead of their plural counterparts. Figure 6-2 shows what the wizard page looks like after selecting all five tables in the SRDEMO schema, setting a package name of devguide.model.entities, and renaming each proposed entity object to have a singular name.

Note: Since an entity object represents a database row, it seems natural to call it an entity row. Alternatively, since at runtime the entity row is an instance of a Java object that encapsulates business logic for that database row, the more object-oriented term entity instance is also appropriate. Therefore, these two terms are interchangeable.

Figure 6-2 Creating Entity Objects for Existing Tables

Click Finish to create the entity objects. A progress dialog appears while the components are created, and then you can see the resulting components in the Application Navigator as shown in Figure 6-3. You can experiment with the Flat Level control and the Sort by Type button to see the effect they have on the display.

Figure 6-3 New Entity Objects in Application Navigator Using Flat Level 1 and Sorted By Type

6.2.2 What Happens When You Create Entity Objects and Associations from Existing Tables

When you create an entity object from an existing table, first JDeveloper interrogates the data dictionary to infer the following information:

• The Java-friendly entity attribute names from the names of the table's columns (e.g. USER_ID -> UserId)

• The SQL and Java data types of each attribute based on those of the underlying column

• The length and precision of each attribute

• The primary and unique key attributes

• The mandatory flag on attributes, based on NOT NULL constraints

• The relationships between the new entity object and other entities based on foreign key constraints

JDeveloper then creates the XML component definition file that represents its declarative settings and saves it in the directory that corresponds to the name of its package. One of the entities created above was named User in the devguide.model.entities package, so the XML file created will be ./devguide/model/entities/User.xml under the project's source path. This XML file contains the name of the table, the names and data types of each entity attribute, and the column name for each attribute. If you're curious to see its contents, you can see the XML file for the entity object by selecting it in the Application Navigator and looking in the corresponding Sources folder in the Structure window. Double-clicking the User.xml node will open the XML in an editor so you can inspect it.

Note: If your IDE-level Business Components Java generation preferences so indicate, the wizard may also create an optional custom entity object class UserImpl.java.

In addition to the entity objects whose names you decided, the wizard also generates named association components that capture information about the relationships between entity objects. A quick glance at the database diagram in Figure 6-4 confirms that the default association names like SvrAssignedToUsrFkAssoc and SvrCreatedByUsrFkAssoc are derived by converting the foreign key constraint names to a Java-friendly name and adding the Assoc suffix. For each association created, JDeveloper creates an appropriate XML component definition file and saves it in the directory that corresponds to the name of its package. By default the associations reverse-engineered from foreign keys get created in the same package as the entities, so, for example, one of the association XML file will be named ./devguide/model/entities/SvrAssignedToUsrFkAssoc.xml.

Figure 6-4 USERS and SERVICE_REQUESTS Tables Are Related By Foreign Keys

6.2.2.1 What Happens When a Table Has No Primary Key

If a table has no primary key constraint, then JDeveloper cannot infer the primary key for the entity object. Since every entity object must have at least one attribute marked as a primary key, the wizard will create an attribute named RowID and use the database ROWID value as the primary key for the entity. If appropriate, you can edit the entity object later to mark a different attribute as a primary key and remove the RowID attribute. If you use the Create Entity Object wizard, you will be prompted to use RowID as the primary key, if you have not set any other attribute as primary key.

6.2.3 Creating Entity Objects Using the Create Entity Wizard

To create a single entity object, you can use the Create Entity Object wizard. The wizard is available from the New Gallery in the Business Tier > ADF Business Components category. By selecting the name of an existing table in step 1, on the Name page, JDeveloper will infer all of the same information for the new entity that it would have done using the Business Components from Tables wizard. If you enter a name of a table that does not exist, you will need to define each attribute one by one on the Attributes page of the wizard. You can later create the table manually, or generate it, as described in Section 6.2.6, "Creating Database Tables from Entity Objects".

6.2.4 Creating an Entity Object for a Synonym or View

When creating an entity object using the Business Components from Tables wizard or the Create Entity Object wizard, an entity object can represent an underlying table, synonym, or view. You've seen in Section 6.2.2.1, "What Happens When a Table Has No Primary Key", that the framework can infer the primary key and related associations by inspecting database primary and foreign key constraints in the data dictionary. However, if the schema object you select is a database view then neither the primary key, nor associations can be inferred since database views do not have database constraints. In this case, if you use the Business Components from Tables wizard, the primary key defaults to RowID. If you use the Create Entity Object wizard, you'll need to specify the primary key manually by marking at least one of its attributes as a primary key.

If the schema object you choose is a synonym, then there are two possible outcomes. If the synonym is a synonym for a table, then the wizard and editor will behave as if you had specified a table. If instead the synonym refers to a database view, then they will behave as if you had specified the a view.

6.2.5 Editing an Existing Entity Object or Association

After you've created a new entity object, you can edit any of its settings by using the Entity Object Editor. Select the Edit menu option on the context menu in the Application Navigator, or double-click on the entity object, to launch the editor. By opening the different panels of the editor, you can adjust the settings that define the entity and govern its runtime behavior. Later sections of this chapter cover many of these settings.

6.2.6 Creating Database Tables from Entity Objects

To create database tables based on entity objects, select the package in the Application Navigator that contains the entity objects and choose Create Database Objects... from the context menu. A dialog appears to let you select the entities whose tables you'd like to create. This tool can be used to generate a table for an entity object you created from scratch, or to drop and re-create an existing table.

Caution: This feature does not generate a DDL script to run later; it performs its operations directly against the database and will drop existing tables. A dialog appears to confirm that you want to do this before proceeding. For entities based on existing tables, use with prudence.

6.2.6.1 Using Database Key Constraints for an Association

In the Association editor, the Use Database Key Constraints checkbox on the Association Properties page controls whether the related foreign key constraint will be generated when creating the tables for entity objects. Selecting this option does not have any runtime implications.

6.2.7 Synchronizing an Entity with Changes to Its Database Table

Inevitably you (or your DBA) might alter a table for which you've already created an entity object. Your existing entity will not be disturbed by the presence of additional attributes in its underlying table; however, if you want to access the new column in the table in your J2EE application, you'll need to synchronize the entity object with the database table. To perform this synchronization automatically, select the entity object in question and choose Synchronize with Database... from the context menu. For example, suppose you had done the following at the SQL*Plus command prompt to add a new SECURITY_QUESTION column to the USERS table:

ALTER TABLE USERS ADD (security_question VARCHAR2(60));

After you use the synchronize feature on the existing User entity, the Synchronize with Database dialog would appear as shown in Figure 6-5

Figure 6-5 Synchronizing an Entity Object with Its Underlying Table

The dialog proposes the changes that it can perform for you automatically, and by clicking the desired synchronize button you can carry out the synchronization.

6.2.8 What You May Need to Know About Creating Entities

The Business Components from Tables wizard makes it easy to quickly generate a lot of business components at the same time. In practice, this does not mean that you should use it to immediately create entity objects for every table in your database schema just because you can. If your application will be using all of those tables, that may be appropriate, but since you can use the wizard whenever needed, Oracle recommends creating the entity objects for the tables you know will be involved in the application. Section 8.9, "Deciding on the Granularity of Application Modules" outlines some thoughts on use case-driven design for your business services that can assist you in understanding which entity objects are required to support your application's business logic needs. You can always add more entity objects later as necessary.