Skip Headers
Oracle Fusion Middleware Developer's Guide for Oracle TopLink
11g Release 1 (11.1.1)

Part Number B32441-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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:

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 Mapping 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 Oracle JDeveloper or Java, see Section 116.1.1, "How to Create a Project Using Oracle JDeveloper" or 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:

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), use this procedure to create your TopLink project.

19.2.1 How to Create a Project from an Existing Object and Data Model Using Oracle JDeveloper

For more information, see "Adding a TopLink Map to an Existing Project" in the "Developing TopLink Mappings" section of the Oracle JDeveloper online help.

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

  1. Create the project (see Section 116.1.2, "How to Create a Project Using TopLink Workbench").

  2. Configure the project classpath (see Section 117.3, "Configuring Project Classpath").

  3. Import classes (see Section 5.7.3, "How to Import and Update Classes").

  4. Import database tables (see Section 5.5.1.3, "Importing Tables from a Database").

  5. Automatically create mappings (see Section 120.3.2, "How to Create Mappings Automatically During Development Using TopLink Workbench").

  6. 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, use this procedure 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 Oracle JDeveloper

For more information, see "Adding a TopLink Map to an Existing Project" in the "Developing TopLink Mappings" section of the Oracle JDeveloper online help.

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), use this procedure 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 Oracle JDeveloper

For more information, see "Adding a TopLink Map to an Existing Project" in the "Developing TopLink Mappings" section of the Oracle JDeveloper online help.

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

  1. Create the project (see Section 116.1.2, "How to Create a Project Using TopLink Workbench").

  2. Import database tables (see Section 5.5.1.3, "Importing Tables from a Database").

  3. Generate classes. For more information, see either of the following:

  4. 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:

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:

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

    Export to Java Source button
    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:

  1. 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 ejb-jar.xml file to reflect your project. Additionally, if you edit the ejb-jar.xml file outside TopLink Workbench, you can update your project to reflect the current file.

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

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

ejb-jar.xml Fields Oracle JDeveloper
TopLink Workbench

primkey

 

Bean attribute mapped to the primary key in the database table (see Section 119.2, "Configuring Primary Keys").

ejb-name, prim-key-class, local, local-home, remote, home, and ejb-class

 

EJB descriptor information on the EJB Info tab (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information").

abstract-schema-name

 

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").


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 ejb-jar.xml file when you save the project.

Note:

You can also write the information to a .jar file. TopLink Workbench automatically places the ejb-jar.xml file in the proper location (META-INF/ejb-jar.xml).
  1. 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 ejb-jar.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 Write to the ejb-jar.xml File Using Oracle JDeveloper

For more information, see "Working with EJB Modules in Oracle JDeveloper Projects" in the "Developing Enterprise JavaBeans Components" section of the Oracle JDeveloper online help.

19.7.3 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.
  1. 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 ejb-jar.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.

See Also

Working with the ejb-xml.File
Working with Projects

19.7.4 How to Read from the ejb-jar.xml File Using Oracle JDeveloper

For more information, see "Working with EJB Modules in Oracle JDeveloper Projects" in the "Developing Enterprise JavaBeans Components" section of the Oracle JDeveloper online help.