| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter includes the following information:
For information on creating descriptors, see the following:
After you create a descriptor, you must configure its various options (see Chapter 25, "Configuring a Descriptor") and use it to define mappings.
For complete information on the various types of mapping that TopLink supports, see Chapter 30, "Understanding Mappings" and Chapter 31, "Creating a Mapping".
For complete information on the various types of descriptor that TopLink supports, see "Descriptor Types".
You can create a relational descriptor using TopLink Workbench (see "Using TopLink Workbench") or Java code (see "Using Java"). Oracle recommends that you use TopLink Workbench to create and manage your relational descriptors.
For more information, see "Relational Descriptors".
Using TopLink Workbench, you can create the following types of descriptor in a relational project:
By default, when you add a Java class to a relational project (see "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 "Relational Aggregate Descriptors"). Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.
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 41, "Configuring a Relational Aggregate Collection Mapping" and Chapter 43, "Configuring a Relational Aggregate Object Mapping"), you must designate the target object's descriptor as an aggregate (see "Configuring a Relational Descriptor as a Class or Aggregate Type").
If you add an interface to a relational project (see "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 "Configuring Interface Query Keys"). A read query on the interface results in reading one or more of its implementors.
Example 24-1 shows how to create a relational descriptor using Java code.
Example 24-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 "Configuring Associated Tables") and field mappings (see "Understanding Mappings").
To allow a relational descriptor to participate in an aggregate collection mapping (see "Aggregate Collection Mapping"), use ClassDescriptor method descriptorIsAggregateCollection. For a RelationalDescriptor configured for use with an aggregate collection mapping, you do define primary keys (see "Configuring Primary Keys") and an associated table (see "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 "Configuring Interface Alias").
You cannot create an object-relational descriptor using TopLink Workbench: you must use Java code. For more information on creating descriptors in Java code, see the Oracle TopLink API Reference.
For more information, see "Object-Relational Descriptors".
Use the ObjectRelationalDescriptor class to define an object-relational descriptor. This class extends RelationalDescriptor to add the following methods:
setStructureName: call this method to set the name of the object-relational structure that represents the object class in the data source.
addFieldOrdering: call this method repeatedly to define the order in which object attributes are persisted to the data source. This defines a field index that TopLink uses if your object-relational data source driver uses JDBC indexed arrays.
Example 24-2 shows an Employee object that is mapped to an Oracle Database using its object-relational features.
Example 24-2 Employee Class
public class Employee {
Long id;
String firstName;
String lastName;
...
}
Example 24-3 shows the object-relational database type (Employee_t) created to model the Employee object within the database. Such an object-relational database type is also known as a structure. This example also shows how to create and populate a database table (called department) that stores instances of the Employee_t audio tape.
Example 24-3 Employee Object-Relational Data Model
CREATE TYPE EMPLOYEE_T AS OBJECT( ID NUMBER(10), F_NAME VARCHAR2(100), L_NAME VARCHAR2(100),) NOT FINAL; CREATE TABLE EMPLOYEES OF TYPE EMPLOYEE_T;
Example 24-4 shows how to code an object-relational descriptor in Java to describe the object-relational database type Employee_t.
Example 24-4 Creating an Object-Relational Descriptor in Java
import oracle.toplink.objectrelational.*;
ObjectRelationalDescriptor descriptor = new ObjectRelationalDescriptor();
descriptor.setJavaClass(Employee.class);
descriptor.setTableName("EMPLOYEES");
descriptor.setStructureName("EMPLOYEE_T");
descriptor.setPrimaryKeyFieldName("ID");
descriptor.addFieldOrdering("ID");
descriptor.addFieldOrdering("F_NAME");
descriptor.addFieldOrdering("L_NAME");
descriptor.addDirectMapping("id", "OBJECT_ID");
descriptor.addDirectMapping("firstName", "F_NAME");
descriptor.addDirectMapping("lastName", "L_NAME");
For more information on configuring object-relational descriptors, see "Configuring an Object-Relational Descriptor".
For more information on the object-relational mappings that TopLink supports, see Chapter 46, "Understanding Object-Relational Mappings".
You can create an EIS descriptor using TopLink Workbench (see "Using TopLink Workbench") or Java code (see "Using Java"). Oracle recommends that you use TopLink Workbench to create and manage your EIS descriptors.
For more information, see "EIS Descriptors".
Using TopLink Workbench, you can create the following types of EIS descriptor in an EIS project:
You can modify an EIS descriptor's behavior by configuring it as a root EIS descriptor (see "Configuring an EIS Descriptor as a Root or Composite Type"). When you designate an EIS descriptor as a root, you tell the TopLink runtime that the EIS descriptor's reference class is a parent class: no other class will reference it by way of a composite object mapping or composite collection mapping. Using an EIS root descriptor, you can configure all supported mappings. You can also configure an EIS root descriptor with EIS interactions (see "Using EIS Interactions"). However, if you configure the EIS root descriptor with a composite object mapping or composite collection mapping, the reference descriptor you define must be an EIS composite descriptor; it cannot be another EIS root descriptor.
By default, when you add a class to an EIS project (see "Configuring Project Classpath"), TopLink Workbench creates an EIS descriptor for the class, and designates the EIS descriptor as a composite. When you designate an EIS descriptor as a composite, you tell the TopLink runtime that the EIS descriptor's reference class may be referenced by a composite object mapping or composite collection mapping. Using an EIS composite descriptor, you can configure all supported mappings. However, you cannot configure an EIS composite descriptor with EIS interactions: for this, you need an EIS root descriptor (see "EIS Root Descriptors").
Example 24-5 shows how to create a relational descriptor using Java code.
Example 24-5 Creating an EIS Descriptor in Java
EISDescriptor descriptor = new EISDescriptor(); descriptor.setJavaClass(YourClass.class);
To designate an EIS descriptor as a composite, use ClassDescriptor method descriptorIsAggregate.
You can create an XML descriptor using TopLink Workbench (see "Using TopLink Workbench") or Java code (see "Using Java"). Oracle recommends that you use TopLink Workbench to create and manage your XML descriptors.
For more information, see "XML Descriptors".
When you add a class to an XML project (see "Configuring Project Classpath"), TopLink Workbench creates an XML descriptor for the class.
An XML descriptor is always a composite type.
Example 24-6 shows how to create a relational descriptor using Java code.
Example 24-6 Creating an XML Descriptor in Java
XMLDescriptor descriptor = new XMLDescriptor(); descriptor.setJavaClass(YourClass.class);
|
Note: Use theoracle.toplink.ox.XMLDescriptor class. Do not use the deprecated oracle.toplink.xml.XMLDescriptor class. |
You can validate descriptors in the following ways:
Run the project in a test environment and watch for and interpret any exceptions that occur. For more information, see Chapter 13, "TopLink Exception Reference".
Run the TopLink integrity checker. For more information, see "Integrity Checker".
Review the project status report. For more information, see "Generating the Project Status Report".
Typically, you capture descriptor configuration in the project.xml file and the TopLink runtime reads this information, and then creates and configures all necessary descriptor objects.
Alternatively, for relational projects only, you can export a TopLink project as a Java class (oracle.toplink.sessions.Project) that contains all descriptor configuration in Java. This lets you use TopLink Workbench to quickly create and configure descriptors, and then, manually code features that TopLink Workbench does not support. This gives you the best of both TopLink Workbench and Java access to your descriptors. After configuring your Java project class, compile it and include it in your application's JAR file.
For more information, see "Exporting Project Java Source".
