22 Creating a Relational Descriptor
This chapter describes how to create relational descriptors.
This chapter includes the following sections:
For information on how to create more than one type of descriptors, see Chapter 118, "Creating a Descriptor".
22.1 Introduction to Relational Descriptor Creation
After you create a descriptor, you must configure its various options (see Chapter 119, "Configuring a Descriptor") and use it to define mappings.
For complete information on the various types of mapping that TopLink supports, see Chapter 17, "Introduction to Mappings" and Chapter 120, "Creating a Mapping".
For complete information on the various types of descriptor that TopLink supports, see Section 16.1, "Descriptor Types".
For more information, see Chapter 21, "Introduction to Relational Descriptors".
22.2 Creating a Relational Descriptor
You can create a relational descriptor using Oracle JDeveloper, TopLink Workbench (see Section 22.2.1, "How to Create a Relational Descriptor Using TopLink Workbench"), or Java code (see Section 22.2.2, "How to Create a Relational Descriptor Using Java").
22.2.1 How to Create a Relational Descriptor Using TopLink Workbench
Using TopLink Workbench, you can create the following types of descriptor in a relational project:
-
Relational class descriptors (see Section 22.2.1.1, "Creating Relational Class Descriptors");
-
Relational aggregate descriptors (see Section 22.2.1.2, "Creating Relational Aggregate Descriptors");
-
Relational interface descriptors (see Section 22.2.1.3, "Creating Relational Interface Descriptors").
22.2.1.1 Creating Relational Class Descriptors
By default, when you add a Java class to a relational project (see Section 117.3, "Configuring Project Classpath"), TopLink Workbench creates a relational class descriptor for it. A class descriptor is applicable to any persistent object except an object that is owned by another in an aggregate relationship. In this case, you must describe the owned object with an aggregate descriptor (see Section 22.2.1.2, "Creating Relational Aggregate Descriptors"). Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.
22.2.1.2 Creating Relational Aggregate Descriptors
An aggregate object is an object that is strictly dependent on its owning object. Aggregate descriptors do not define a table, primary key, or many of the standard descriptor options as they obtain these from their owning descriptor. If you want to configure an aggregate mapping to associate data members in a target object with fields in a source object's underlying database tables (see Chapter 35, "Configuring a Relational Aggregate Collection Mapping" and Chapter 37, "Configuring a Relational Aggregate Object Mapping"), you must designate the target object's descriptor as an aggregate (see Section 23.6, "Configuring a Relational Descriptor as a Class or Aggregate Type").
22.2.1.3 Creating Relational Interface Descriptors
If you add an interface to a relational project (see Section 117.3, "Configuring Project Classpath"), TopLink Workbench creates an interface descriptor for it.
An interface is a collection of abstract behavior that other classes can use. It is a purely Java concept and has no representation on the relational database. Therefore, a descriptor defined for the interfaces does not map any relational entities on the database.
The interface descriptor includes the following elements:
-
The Java interface it describes.
-
The parent interface(s) it implements.
-
A list of abstract query keys.
An interface descriptor does not define any mappings, because there is no concrete data or table associated with it. A list of abstract query keys is defined so that you can issue queries on the interfaces (see Section 119.11, "Configuring Interface Query Keys"). A read query on the interface results in reading one or more of its implementors.
22.2.2 How to Create a Relational Descriptor Using Java
Example 22-1 shows how to create a relational descriptor using Java code.
Example 22-1 Creating a Relational Descriptor in Java
RelationalDescriptor descriptor = new RelationalDescriptor(); descriptor.setJavaClass(YourClass.class);
To designate a relational descriptor as an aggregate, use ClassDescriptor method descriptorIsAggregate. For a RelationalDescriptor configured as an aggregate, you do not define a primary key, but when using Java, you must configure the associated table (see Section 23.2, "Configuring Associated Tables") and field mappings (see Chapter 17, "Introduction to Mappings").
To allow a relational descriptor to participate in an aggregate collection mapping (see Section 27.9, "Aggregate Collection Mapping"), use ClassDescriptor method descriptorIsAggregateCollection. For a RelationalDescriptor configured for use with an aggregate collection mapping, you do define primary keys (see Section 119.2, "Configuring Primary Keys") and an associated table (see Section 23.2, "Configuring Associated Tables"), but you do not have to map the primary keys if they are shared from their parent.
To configure a relational descriptor for an interface, use ClassDescriptor method setJavaInterface, passing in the java.lang.Class of the interface. You should only use an interface descriptor for an interface that has multiple implementors. If an interface has only a single implementor, then rather than creating an interface descriptor, just set the implementor descriptor's interface alias (see Section 23.5, "Configuring Interface Alias").