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".
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".
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.
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").
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.
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").
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.
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:
Configure project options (see Chapter 117, "Configuring a Project").
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".
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")
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".
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.
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 |
---|---|
Bean attribute mapped to the primary key in the database table (see Section 119.2, "Configuring Primary Keys"). |
|
|
EJB descriptor information on the EJB Info tab (see Section 119.18, "Configuring a Descriptor with EJB CMP and BMP Information"). |
|
Descriptor Alias field (see Section 119.5, "Configuring Descriptor Alias"). |
|
Direct (non-relationship) attributes on the Descriptor Info tab (see Section 119.1, "Configuring Common Descriptor Options"). |
|
Persistence Type field on the General tab (see Section 117.5, "Configuring Persistence Type"). The |
|
Queries listed in Queries tab (see Section 119.7, "Configuring Named Queries at the Descriptor Level"). Note: The |
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 theejb-jar.xml
file. For more information, see the Oracle JDeveloper online help.For more information, see Section 9.1.3, "ejb-jar.xml File".
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 theejbEjar.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.
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 theejb-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 theejb-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.