6.3 Creating and Configuring Associations

If your database tables have no foreign key constraints defined, JDeveloper won't be able to automatically infer the associations between the entity objects that you create. Since several interesting runtime features that you'll learn about depend on the presence of entity associations, Oracle recommends that you create them manually.

6.3.1 How to Create an Association

To create an association, use the Create New Association wizard.

Assuming the association between the ServiceRequest and the ServiceHistory entities did not already exist, you could create it manually following these steps:

To create an association:

1. Open the Create New Association wizard from the New Gallery in the Business Tier > ADF Business Components category.

2. In step 1 on the Name page, provide a name for the association component and a package to contain it.

3. In step 2, on the Entity Objects page, select a "source" attribute from one of the entity objects that will be involved in the association to act as the master. Figure 6-6 shows the selected SvrId attribute from the ServiceRequest entity object as the source entity attribute.

   Figure 6-6 Manually Defining the Attribute Pairs That Relate Two Entity Objects

   
   

4. Next, select a corresponding destination attribute from the other entity object involved in the association. Since ServiceHistory rows contain a service request ID that relates them to a specific ServiceRequest row, select this SvrId foreign key attribute in the ServiceHistory entity object as the destination attribute.

5. Next, click Add to add the matching attribute pair to the table of source and destination attribute pairs below. If there were multiple attribute pairs required to define the association, you could repeat these steps to add additional source/target attribute pairs. For this example, the one (SvrId,SvrId) pair is all that's required.

6. Finally, ensure that the Cardinality dropdown correctly reflects the cardinality of the association. Since the relationship between a ServiceRequest and its related ServiceHistory rows is one-to-many, you can leave the default setting.

7. In step 3, on the Association SQL page, you can preview the association SQL predicate that will be used at runtime to access the related ServiceHistory entity objects for a given instance of the ServiceRequest entity object.

8. In step 4, on the Association Properties page, you control whether the association represents a one-way relationship or a bidirectional one and set other properties that define the runtime behavior of the association. Notice in Figure 6-7 that the Expose Accessor checkbox is checked in both the Source and Destination group boxes. By default, an association is a bi-directional relationship allowing either entity object to access the related entity row(s) on the other side when needed. In this example, it means that if you are working with an instance of a ServiceRequest entity object, you can easily access the collection of its related ServiceHistory rows. You can also easily access the ServiceRequest to which it belongs, with any instance of a ServiceHistory entity object. Bidirectional navigation is more convenient for writing business validation logic, so in practice, you will typically leave these default checkbox settings.

   Figure 6-7 Association Properties Control Runtime Behavior

   
   

6.3.1.1 Changing Entity Association Accessor Names

You should consider the default settings for the accessor names on the Association Properties page and decide whether changing the names to something more intuitive is appropriate. These define the names of the accessor attributes you will use at runtime to programmatically access the entities on the other side of the relationship. By default, the accessor names will be the names of the entity object on the other side. Since the accessor names on an entity must be unique among entity object attributes and other accessors, if one entity is related to another entity in multiple ways then the default accessor names are modified with a numeric suffix to make the name unique. For example, the ServiceRequest entity is associated once to the User entity to represent the user who created the request, and a second time to reflect the technician to whom the service request is assigned for resolution. The default accessor names on the ServiceRequest entity would be User and User1. By opening the respective Association Properties page for the associations in question, you can rename these accessors to more intuitive names like CreatedByUser and TechnicianAssigned.

6.3.1.2 Renaming and Moving Associations to a Different Package

Since the names of the default associations are not easy to understand, one of the first tasks you might want to perform after creating entity objects from tables is to rename them to something more meaningful. Furthermore, since associations are a component that you typically configure at the outset of your project and don't really visit frequently thereafter, you might want to move them to a different package so that your entity objects are easier to see. Both renaming components and moving them to a different package is straightforward using JDeveloper's refactoring functionality. To move a set of business components to a different package, select one or more of the components in the Application Navigator and choose Refactor > Move... from the context menu. To rename a component, select it in the navigator and choose Refactor > Rename from the context menu.

When you refactor ADF Business Components, JDeveloper automatically moves any XML and/or Java files related to the components, as well as updating any other components that might reference them. Figure 6-8 shows what the Application Navigator would look like after renaming all of the associations and moving them to the devguide.model.entities.associations package. While you can refactor the associations into any package names you choose, picking a subpackage like this keeps them logically related to the entities but allows collapsing the package of associations to avoid seeing them when you don't need to.

Figure 6-8 Application Navigator After Association Refactoring

6.3.2 What Happens When You Create an Association

When you create an association, JDeveloper creates an appropriate XML component definition file and saves it in the directory that corresponds to the name of its package. If you created an association named ServiceHistoriesForServiceRequest in the devguide.model.entities.associations package, then the association XML file will be created in the ./devguide/model/entities/associations directory with the name ServiceHistoriesForServiceRequest.xml. At runtime, the entity object uses the association information to automate working with related sets of entities.

6.3.3 What You May Need to Know About Composition Associations

{para}?>When you create composition associations, it is useful to know about the kinds of relationships you can represent, and the various options.

Associations between entity objects can represent two styles of relationships depending on whether the source entity:

• References the destination entity

• Contains the destination entity as a logical, nested part

As shown in Figure 6-9, in your SRDemo application business layer you have a ServiceRequest that references a Product, the requesting User, and the assigned User (a technician). These relationships represent the first kind of association, reflecting that a User or a Product entity object can exist independently of a ServiceRequest. In addition, the removal of a ServiceRequest does not imply the cascade removal of the Product to which it was referring or the related Users.

In contrast, the relationship between ServiceRequest and its collection of related ServiceHistory details is stronger than a simple reference. The ServiceHistory entries comprise a logical part of the overall ServiceRequest. In other words, a ServiceRequest is composed of ServiceHistory entries. It does not make sense for a ServiceHistory entity row to exist independently from a ServiceRequest, and when a ServiceRequest is removed — assuming it is allowed — all of its composed parts should be removed as well.

This type of logical containership represents the second kind of association, called a composition. The UML diagram in Figure 6-9 illustrates the stronger composition relationship using the solid diamond shape on the side of the association which composes the other.

Figure 6-9 ServiceRequest is Composed of ServiceHistory Entries and References Both Product and User

The Business Components from Tables wizard creates composition associations by default for any foreign keys that have the ON DELETE CASCADE option. Using the Create Association wizard or the Association Editor, to indicate that an association is a composition association, check the Composition Association checkbox on the Association Properties page. An entity object offers additional runtime behavior in the presence of a composition. You'll learn the specifics and the settings that control it in Section 6.6.3.12, "Understanding and Configuring Composition Behavior".