19 Creating a Relational Project

This chapter describes the various components that you must configure in order to create a relational project.

This chapter includes the following sections:

Introduction to the Relational Project Creation
Creating a Project from an Existing Object and Data Model
Creating a Project from an Existing Object Model
Creating a Project from an Existing Data Model
Creating a Project from an OC4J EJB CMP EAR at Deployment Time
Exporting Project Information
Working with the ejb-xml.File

For information on how to create more than one type of TopLink projects, see Chapter 116, "Creating a Project".

19.1 Introduction to the Relational Project Creation

You can create a project using Oracle JDeveloper TopLink Editor, TopLink Workbench, or Java code.

Oracle recommends using either Oracle JDeveloper or TopLink Workbench to create projects and generate deployment XML or Java source versions of the project for use at run time. For more information on how to create a project using TopLink Workbench, see Section 116.1.2, "How to Create a Project Using TopLink Workbench". For information on how to create a project using Java, see Section 116.1.3, "How to Create a Project Using Java".

You can use TopLink to create a relational project, if any of the following conditions are met:

You have both an object and data model: see Section 19.2, "Creating a Project from an Existing Object and Data Model".
You have an object model, but no data model yet: see Section 19.3, "Creating a Project from an Existing Object Model".
You have a data model, but no object model yet: Section 19.4, "Creating a Project from an Existing Data Model".
You are deploying an EJB CMP application to OC4J, you can create a project (including all mappings and data model) automatically at deployment time: see Section 19.5, "Creating a Project from an OC4J EJB CMP EAR at Deployment Time".

For more information, see Chapter 18, "Introduction to Relational Projects".

19.2 Creating a Project from an Existing Object and Data Model

If you have both an existing object model (Java classes for your domain objects) and data model (such as an existing database schema), you can use either Oracle JDeveloper or TopLink Workbench to create your TopLink project.

19.2.1 How to Create a Project from an Existing Object and Data Model Using TopLink Workbench

Create the project (see Section 116.1.2, "How to Create a Project Using TopLink Workbench").
Configure the project classpath (see Section 117.3, "Configuring Project Classpath").
Import classes (see Section 5.7.3, "How to Import and Update Classes").
Import database tables (see Section 5.5.1.3, "Importing Tables from a Database").
Automatically create mappings (see Section 120.3.1, "How to Create Mappings Automatically During Development Using TopLink Workbench").
Configure project options (see Chapter 117, "Configuring a Project").

19.3 Creating a Project from an Existing Object Model

If you have an existing object model (Java classes for your domain objects), but you do not have a corresponding data model, you can use either Oracle JDeveloper or TopLink Workbench to create your TopLink project and automatically generate the corresponding data model.

19.3.1 How to Create a Project from an Existing Object Model Using TopLink Workbench

Create the project (see Section 116.1.2, "How to Create a Project Using TopLink Workbench").
Configure the project classpath (see Section 117.3, "Configuring Project Classpath").
Import classes (see Section 5.7.3, "How to Import and Update Classes").
Generate database tables. For more information, see the following:
Configure project options (see Chapter 117, "Configuring a Project").

19.4 Creating a Project from an Existing Data Model

If you have an existing data model (such as a database schema), but you do not have a corresponding data model (Java classes for domain objects), you can use either Oracle JDeveloper or TopLink Workbench to create your TopLink project and automatically generate the corresponding object model.

19.4.1 How to Create a Project from an Existing Data Model Using TopLink Workbench

Create the project (see Section 116.1.2, "How to Create a Project Using TopLink Workbench").
Import database tables (see Section 5.5.1.3, "Importing Tables from a Database").
Generate classes. For more information, see either of the following:
- Section 5.5.3.2, "Generating Classes and Descriptors from Database Tables"
- Section 5.5.3.3, "Generating EJB Entity Beans and Descriptors from Database Tables"
Configure project options (see Chapter 117, "Configuring a Project").

19.5 Creating a Project from an OC4J EJB CMP EAR at Deployment Time

For a CMP application deployed to OC4J configured to use TopLink as the persistence manager, you can use the TopLink default mapping feature to automatically generate a TopLink project, including descriptors and mappings for all persistent objects, at deployment time.

This procedure applies only to CMP relational projects deployed to OC4J configured to use TopLink as the persistence manager.

For more information, see Section 17.2.3.4, "Default Mapping in EJB 2.n CMP Projects Using OC4J at Run Time".

19.6 Exporting Project Information

TopLink Workbench generates and exports the following project information:

Project Java source (see Section 19.6.1, "How to Export Project Java Source Using TopLink Workbench")
Table creator files (see Section 19.6.2, "How to Export Table Creator Files Using TopLink Workbench")

19.6.1 How to Export Project Java Source Using TopLink Workbench

For relational projects only, you can convert the project to Java source code. Generally, the generated code executes faster and deploys easier than XML files. See Section 118.3, "Generating Java Code for Descriptors" to export the model source for a specific descriptor in a project. To convert your relational project to Java source, use this procedure:

Right-click the project in the Navigator and choose Export > Project Java Source from the context menu.

You can also choose Workbench > Export > Export Java Source or Selected > Export > Project Java Source from the menu.

If you have not defined deployment and source code generation defaults (see Chapter 117, "Configuring a Project") TopLink Workbench prompts for a project class name and directory.

Note:

If your TopLink Workbench project uses the UTF-8 character set, you must use a compatible JDK when compiling the exported Java source.

If your project contains errors, the project.xml file may not be valid. See Section A.3, "TopLink Workbench Error Reference" for information on each reported error.

To generate Java source that is compatible with projects prior to this release, see Section 20.11, "Configuring Deprecated Direct Mappings".

19.6.2 How to Export Table Creator Files Using TopLink Workbench

For relational projects only, you can create Java source code to generate database tables defined in the project using this procedure:

Right-click the project in the Navigator and choose Export > Table Creator Java Source from the context menu.

You can also choose Workbench > Export > Table Creator Java Source or Selected > Export > Table Creator Java Source from the menu.

If you have not defined deployment and source code generation defaults (see Chapter 117, "Configuring a Project") TopLink Workbench prompts for a class name and root directory.

19.7 Working with the ejb-xml.File

For relational projects that use EJB 2.0 CMP, use the ejb-jar.xml file to store persistence information for the application server. With TopLink Workbench, you can import information from an existing ejb-jar.xml file into your project, or you can create and update the ejb-jar.xml file from your project.

Each TopLink Workbench project uses a single ejb-jar.xml file. For each entity bean in the file, you should have an EJB descriptor in the project. All entity beans must use the same persistence type.

As you make changes in your project, you can update the ejbEjar.xml file to reflect your project. Additionally, if you edit the ejbEjar.xml file outside TopLink Workbench, you can update your project to reflect the current file.

Table 19-1 describes how fields in the ejbEjar.xml file correspond to specific functions in TopLink Workbench.

Table 19-1 ejb-jar.xml Fields and TopLink Workbench

ejb-jar.xml Fields	TopLink Workbench
`primkey`	Bean attribute mapped to the primary key in the database table (see Section 119.2, "Configuring Primary Keys").
`ejb-name, primEkeyEclass, local, localEhome, remote, home, and ejbEclass`	EJB descriptor information on the EJB Info tab (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information").
`abstractEschemaEname`	Descriptor Alias field (see Section 119.5, "Configuring Descriptor Alias").
`cmp-field`	Direct (non-relationship) attributes on the Descriptor Info tab (see Section 119.1, "Configuring Common Descriptor Options").
`cmp-version`	Persistence Type field on the General tab (see Section 117.5, "Configuring Persistence Type"). The `persistence-type` is set to `container.`
`query`	Queries listed in Queries tab (see Section 119.7, "Configuring Named Queries at the Descriptor Level"). Note: The `findByPrimaryKey` query is not in the `ejb-jar.xml` file as per the EJB 2.0 specification.
`relationships`	One-to-one, one-to-many, and many-to-many mappings (see Part XII, "Relational Mappings").

Note:

You can also use Oracle JDeveloper TopLink Editor for reading from and writing to the ejb-jar.xml file. For more information, see the Oracle JDeveloper online help.

For more information, see Section 9.1.3, "ejb-jar.xml File".

19.7.1 How to Write to the ejb-jar.xml File Using TopLink Workbench

To update the ejb-jar.xml file based on the current TopLink Workbench information, use this procedure:

Note:

Use the EJB preferences to specify whether or not TopLink Workbench automatically updates the ejbEjar.xml file when you save the project.

Note:

You can also write the information to a .jar file. TopLink Workbench automatically places the ejbEjar.xml file in the proper location (METAEINF/ejbEjar.xml).

Choose Selected > Write Project to ejb-jar.xml from the menu.

You can also right-click the project in the Navigator and choose Write Project to ejb-jar.xml from the context menu.
- If the project does not currently contain an ejb-jar.xml file, the system prompts you to create a new file.
- If the system detects that changes were made to the ejbEjar.xml file but not yet read into TopLink Workbench (for example, you changed the file outside TopLink Workbench), then the system prompts you to read the file before writing the changes.

19.7.2 How to Read from the ejb-jar.xml File Using TopLink Workbench

To read the ejb-jar.xml information and update your TopLink Workbench project, use this procedure.

Tip:

To automatically create EJB descriptors in TopLink Workbench for all entities, read the ejb-jar.xml file before adding any classes in TopLink Workbench.

Choose Selected > Update Project from ejb-jar.xml from the menu.

You can also right-click the project in the Navigator window and choose Update Project from ejbEjar.xml from the context menu.

Note:

If you are using TopLink Workbench behind a firewall, before reading from the ejb-jar.xml file, you may need to configure TopLink Workbench with a proxy (see Section 5.4.2, "How to Use Help Preferences"). If TopLink Workbench fails to read the ejb-jar.xml file due to connection timeout or no route to host, proxy configuration is required.