Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Creating a Relational Descriptor (ELUG)"

m (How to Create a Relational Descriptor Using Workbench)
m (227400)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
 
<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
 
[[Special:Whatlinkshere/Creating a Relational Descriptor (ELUG)|Related Topics]]</div>
 
[[Special:Whatlinkshere/Creating a Relational Descriptor (ELUG)|Related Topics]]</div>
 
This section describes how to create relational descriptors. For information on how to create more than one type of descriptors, see [[Creating%20a%20Descriptor%20(ELUG)|Creating a Descriptor]].
 
 
 
 
==Introduction to Relational Descriptor Creation==
 
 
 
After you create a descriptor, you must configure its various options (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]) and use it to define mappings.
 
After you create a descriptor, you must configure its various options (see [[Configuring%20a%20Descriptor%20(ELUG)|Configuring a Descriptor]]) and use it to define mappings.
  
For complete information on the various types of mapping that EclipseLink supports, see [[Introduction%20to%20Mappings%20(ELUG)|Introduction to Mappings]] and [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]].
+
For information on the various types of mapping that EclipseLink supports, see [[Introduction%20to%20Mappings%20(ELUG)|Introduction to Mappings]] and [[Creating%20a%20Mapping%20(ELUG)|Creating a Mapping]].
  
For complete information on the various types of descriptor that EclipseLink supports, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptor Types]].
+
For information on the various types of descriptor that EclipseLink supports, see [[Introduction%20to%20Descriptors%20(ELUG)|Descriptor Types]].
  
 
For more information, see [[Introduction%20to%20Relational%20Descriptors%20(ELUG)|Introduction to Relational Descriptors]].
 
For more information, see [[Introduction%20to%20Relational%20Descriptors%20(ELUG)|Introduction to Relational Descriptors]].
Line 19: Line 12:
  
 
==Creating a Relational Descriptor==
 
==Creating a Relational Descriptor==
 
+
You can create a relational descriptor using [[#How to Create a Relational Descriptor Using Workbench|the Workbench]] or [[#How to Create a Relational Descriptor Using Java|Java code]].
You can create a relational descriptor using[[#How to Create a Relational Descriptor Using Workbench|the Workbench]]) or [[#How to Create a Relational Descriptor Using Java|Java code ]]).
+
 
+
  
  
 
===How to Create a Relational Descriptor Using Workbench===
 
===How to Create a Relational Descriptor Using Workbench===
 
 
Using Workbench, you can create the following types of descriptor in a relational project:
 
Using Workbench, you can create the following types of descriptor in a relational project:
 
 
* [[#Creating Relational Class Descriptors|Relational class descriptors]];
 
* [[#Creating Relational Class Descriptors|Relational class descriptors]];
 
* [[#Creating Relational Aggregate Descriptors|Relational aggregate descriptors]];
 
* [[#Creating Relational Aggregate Descriptors|Relational aggregate descriptors]];
 
* [[#Creating Relational Interface Descriptors|Relational interface descriptors]].
 
* [[#Creating Relational Interface Descriptors|Relational interface descriptors]].
 
  
  
 
====Creating Relational Class Descriptors====
 
====Creating Relational Class Descriptors====
 
+
[[Image:clsesin.gif|Class descriptor icon]] By default, when you add a Java class to a relational project (see [[Configuring%20a%20Project%20(ELUG)|Configuring Project Classpath]]), the 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 [[#Creating Relational Aggregate Descriptors|an aggregate descriptor]]. Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.
<div style="float:left">[[Image:clsesin.gif|Class descriptor icon]]</div> By default, when you add a Java class to a relational project (see [[Configuring%20a%20Project%20(ELUG)|Configuring Project Classpath]]), 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 [[#Creating Relational Aggregate Descriptors|Creating Relational Aggregate Descriptors]]). Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.
+
 
+
  
  
 
====Creating Relational Aggregate Descriptors====
 
====Creating Relational Aggregate Descriptors====
 +
[[Image:agdesbtn.gif|Aggregate Descriptor button]] 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 [[Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)|Configuring a Relational Aggregate Collection Mapping]] and [[Configuring%20a%20Relational%20Aggregate%20Object%20Mapping (ELUG)|Configuring a Relational Aggregate Object Mapping]]), you must designate the target object's descriptor as [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring a Relational Descriptor as a Class or Aggregate Type|an aggregate]].
  
<div style="float:left">[[Image:agdesbtn.gif|Aggregate Descriptor button]]</div> 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 [[Configuring%20a%20Relational%20Aggregate%20Collection%20Mapping%20(ELUG)|Configuring a Relational Aggregate Collection Mapping]] and [[Configuring%20a%20Relational%20Aggregate%20Object%20Mapping (ELUG)|Configuring a Relational Aggregate Object Mapping]]), you must designate the target object's descriptor as an aggregate (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring a Relational Descriptor as a Class or Aggregate Type|Configuring a Relational Descriptor as a Class or Aggregate Type]]).
 
  
 
====Creating Relational Interface Descriptors====
 
====Creating Relational Interface Descriptors====
 
+
<div style="float:left">[[Image:ifdescin.gif|Interface descriptor icon]]</div> If you add an interface to a relational project (see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]]), the Workbench creates an interface descriptor for it.
<div style="float:left">[[Image:ifdescin.gif|Interface descriptor icon]]</div> If you add an interface to a relational project (see [[Configuring%20a%20Project%20(ELUG)#Configuring Project Classpath|Configuring Project Classpath]]), 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.
 
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 interface descriptor includes the following elements:
 
 
* The Java interface it describes.
 
* The Java interface it describes.
 
* The parent interface(s) it implements.
 
* The parent interface(s) it implements.
 
* A list of abstract query keys.
 
* 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%20a%20Descriptor%20(ELUG)|Configuring Interface Query Keys]]). A read query on the interface results in reading one or more of its implementors.
+
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 [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Interface Query Keys|queries on the interfaces]]. A read query on the interface results in reading one or more of its implementors.
  
===How to Create a Relational Descriptor Using Java===
 
  
 +
===How to Create a Relational Descriptor Using Java===
 
This example shows how to create a relational descriptor using Java code.
 
This example shows how to create a relational descriptor using Java code.
  
Line 65: Line 49:
 
<span id="Example 27-1"></span>
 
<span id="Example 27-1"></span>
 
''''' Creating a Relational Descriptor in Java'''''
 
''''' Creating a Relational Descriptor in Java'''''
 +
<source lang="java">
 
  RelationalDescriptor descriptor = new RelationalDescriptor();
 
  RelationalDescriptor descriptor = new RelationalDescriptor();
 
  descriptor.setJavaClass(YourClass.class);
 
  descriptor.setJavaClass(YourClass.class);
 +
</source>
  
 +
To designate a relational descriptor as an aggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregate</tt>. For a <tt>RelationalDescriptor</tt> configured as an aggregate, you do not define a primary key, but when using Java, you must configure the [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|associated table]] and [[Introduction%20to%20Mappings%20(ELUG)|field mappings]].
  
 +
To allow a relational descriptor to participate in an [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate Collection Mapping|Aggregate Collection Mapping]], use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregateCollection</tt>. For a <tt>RelationalDescriptor</tt> configured for use with an aggregate collection mapping, you do [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Primary Keys|define primary keys]] and an [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|associated table]], but you do not have to map the primary keys if they are shared from their parent.
  
To designate a relational descriptor as an aggregate, use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregate</tt>. For a <tt>RelationalDescriptor</tt> configured as an aggregate, you do not define a primary key, but when using Java, you must configure the associated table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|Configuring Associated Tables]]) and field mappings (see [[Introduction%20to%20Mappings%20(ELUG)|Introduction to Mappings]]).
+
To configure a relational descriptor for an interface, use <tt>ClassDescriptor</tt> method <tt>setJavaInterface</tt>, passing in the <tt>java.lang.Class</tt> 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 [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Interface Alias|interface alias]].
 
+
To allow a relational descriptor to participate in an aggregate collection mapping (see [[Introduction%20to%20Relational%20Mappings%20(ELUG)#Aggregate Collection Mapping|Aggregate Collection Mapping]]), use <tt>ClassDescriptor</tt> method <tt>descriptorIsAggregateCollection</tt>. For a <tt>RelationalDescriptor</tt> configured for use with an aggregate collection mapping, you do define primary keys (see [[Configuring%20a%20Descriptor%20(ELUG)#Configuring Primary Keys|Configuring Primary Keys]]) and an associated table (see [[Configuring%20a%20Relational%20Descriptor%20(ELUG)#Configuring Associated Tables|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 <tt>ClassDescriptor</tt> method <tt>setJavaInterface</tt>, passing in the <tt>java.lang.Class</tt> 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%20a%20Relational%20Descriptor%20(ELUG)#Configuring Interface Alias|Configuring Interface Alias]]).
+
  
  
Line 86: Line 70:
 
[[Category: Task]]
 
[[Category: Task]]
 
[[Category: Concept]]
 
[[Category: Concept]]
 +
[[Category: ORM]]

Latest revision as of 09:37, 20 May 2009

After you create a descriptor, you must configure its various options (see Configuring a Descriptor) and use it to define mappings.

For information on the various types of mapping that EclipseLink supports, see Introduction to Mappings and Creating a Mapping.

For information on the various types of descriptor that EclipseLink supports, see Descriptor Types.

For more information, see Introduction to Relational Descriptors.


Creating a Relational Descriptor

You can create a relational descriptor using the Workbench or Java code.


How to Create a Relational Descriptor Using Workbench

Using Workbench, you can create the following types of descriptor in a relational project:


Creating Relational Class Descriptors

Class descriptor icon By default, when you add a Java class to a relational project (see Configuring Project Classpath), the 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. Using a class descriptor, you can configure any relational mapping except aggregate collection and aggregate object mappings.


Creating Relational Aggregate Descriptors

Aggregate Descriptor button 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 Configuring a Relational Aggregate Collection Mapping and Configuring a Relational Aggregate Object Mapping), you must designate the target object's descriptor as an aggregate.


Creating Relational Interface Descriptors

Interface descriptor icon
If you add an interface to a relational project (see Configuring Project Classpath), the 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. A read query on the interface results in reading one or more of its implementors.


How to Create a Relational Descriptor Using Java

This example shows how to create a relational descriptor using Java code.


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 and field mappings.

To allow a relational descriptor to participate in an Aggregate Collection Mapping, use ClassDescriptor method descriptorIsAggregateCollection. For a RelationalDescriptor configured for use with an aggregate collection mapping, you do define primary keys and an associated table, 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.




Copyright Statement

Copyright © Eclipse Foundation, Inc. All Rights Reserved.