This chapter describes how to create TopLink projects.
This chapter includes the following sections:
For information on the various types of projects available, see Section 15.1, "TopLink Project Types".
You can create a project using Oracle JDeveloper, 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, see Section 116.1.1, "How to Create a Project Using Oracle JDeveloper" and Section 116.1.2, "How to Create a Project Using TopLink Workbench".
Alternatively, you can create projects in Java code. For an EIS project that uses a record type other than XML, you must use Java code. For more information, see Section 116.1.3, "How to Create a Project Using Java" and Oracle Fusion Middleware Java API Reference for Oracle TopLink.
For information on how to create a project using Java, see Section 116.1.3, "How to Create a Project Using Java".
When you create a TopLink project using Oracle JDeveloper, your mapping information is stored in the TopLink map. The TopLink map contains the information about how classes map to database tables. Use the TopLink editor to edit each component of the mappings, including:
Database information, such as driver, URL, and login information.
Mapping defaults, such as identity map and cache options.
The TopLink editor in Oracle JDeveloper supports the following project types:
Relational project
XML project
EIS project
When you create a project using TopLink Workbench, all project information is stored in the project file ( .mwp
file). This file references additional XML data files that contain the information about how the Java classes map to database tables or XML elements.
Using TopLink Workbench, you can export this information as a TopLink project XML file (that is, the deployment XML file) that is read in by the TopLink runtime. You can also export this information as a Java class. For more information, see Section 116.3, "Exporting Project Information".
TopLink Workbench displays projects and their contents in the Navigator window. When you select a project, its attributes are displayed in the Editor window. See Section 5.3.3, "How to Use the Navigator" for more information. TopLink Workbench supports the following project types:
Relational project
XML project
EIS project
This section includes information on creating a new TopLink Workbench project. To create a new project from an existing persistence application, such as, for example, OC4J, see Chapter 8, "Integrating TopLink with an Application Server". To create a new project from JAXB, see Section 47.1.1, "TopLink Support for Java Architecture for XML Binding (JAXB)".
To create a new TopLink Workbench project, use this procedure:
Click New on the toolbar and select Project. The Create New TopLink Workbench Project dialog box appears.
You can also create a new project by choosing File > New > Project from the menu.
Figure 116-1 Create New TopLink Workbench Project Dialog Box
Use the following information to enter data in each field of this dialog box:
Field | Description |
---|---|
Name | Enter the name of the TopLink Workbench project. This project name will also become the name of the .mwp file. |
Data Source | Use these options to specify the type of project to create, and its data source. |
Database | Select Database to create an relational project to a relational database.
Use the Platform list to select the specific database platform. See Chapter 18, "Introduction to Relational Projects" for more information. |
EIS | Select EIS to create an EIS project to a nonrelational data source using XML records.
Use the Platform list to specify the JCA adapter to use. See Chapter 71, "Introduction to EIS Projects" for more information. |
XML | Select XML to create a nontransactional, nonpersistent XML project to an XML schema.
Alternatively, you can generate both an XML project and object model classes (see Section 48.2, "Creating an XML Project from an XML Schema"). See Chapter 47, "Introduction to XML Projects" for more information. |
For more project information, continue with the following:
Configure the project (see Chapter 117, "Configuring a Project").
Add mappings and descriptors (see Chapter 16, "Introduction to Descriptors" and Chapter 17, "Introduction to Mappings").
Export the project for use with the TopLink runtime (see Section 116.3, "Exporting Project Information").
To create a project using Java code, use this procedure:
Implement a project class that extends the oracle.toplink.sessions.Project
class (see Example 116-1).
Compile the project class.
Example 116-1 Specifying a TopLink Project in Code
/** * The class EmployeeProject is an example of an Oracle TopLink project defined in * Java code. The individual parts of the project - the Login and the descriptors, * are built inside of methods that are called by the constructor. Note that * EmployeeProject extends the class oracle.toplink.sessions.Project */ public class EmployeeProject extends oracle.toplink.sessions.Project { /** * Supply a zero-argument constructor that initializes all aspects of the project. * Make sure that the login and all the descriptors are initialized and added to * the project. Project-level properties, such as the name of the project, should * be specified here */ public EmployeeProject() { setName("EmployeeProject"); applyLogin(); addDescriptor(buildAddressDescriptor()); addDescriptor(buildEmployeeDescriptor()); addDescriptor(buildPhoneNumberDescriptor()); } // Data source information public void applyLogin() { DatabaseLogin login = new DatabaseLogin(); // use platform appropriate for underlying database login.usePlatform( new oracle.toplink.platform.database.oracle.Oracle9Platform()); login.setDriverClassName("oracle.jdbc.OracleDriver"); login.setConnectionString("jdbc:oracle:thin:@HOST:PORT:SID"); login.setUserName("USER NAME"); login.setEncryptedPassword("PASSWORD, ENCRYPTED"); // Configuration Properties setDatasourceLogin(login); } /** * Descriptors are built by defining table info, setting properties * (caching, etc.) and by adding mappings to the descriptor */ // SECTION: DESCRIPTOR public ClassDescriptor buildAddressDescriptor() { RelationalDescriptor descriptor = new RelationalDescriptor(); // specify the class to be made persistent descriptor.setJavaClass(examples.servletjsp.model.Address.class); // specify the tables to be used and primary key descriptor.addTableName("ADDRESS"); descriptor.addPrimaryKeyFieldName("ADDRESS.ADDRESS_ID"); // Descriptor Properties descriptor.useSoftCacheWeakIdentityMap(); descriptor.setIdentityMapSize(100) descriptor.useRemoteSoftCacheWeakIdentityMap() descriptor.setRemoteIdentityMapSize(100) descriptor.setSequenceNumberFieldName("ADDRESS.ADDRESS_ID") descriptor.setSequenceNumberName("ADD_SEQ"); descriptor.setAlias("Address"); // Mappings DirectToFieldMapping cityMapping = new DirectToFieldMapping(); cityMapping.setAttributeName("city"); cityMapping.setFieldName("ADDRESS.CITY"); descriptor.addMapping(cityMapping); // Additional mappings are added to the descriptor using the addMapping method return descriptor;}
Note:
Using TopLink Workbench provides a starting point for a custom project class. For more information, see Section 19.6.1, "How to Export Project Java Source Using TopLink Workbench".Using TopLink Workbench, you can perform the following project functions:
See Chapter 117, "Configuring a Project" for additional information on working with TopLink Workbench projects.
Use this procedure to open an existing project:
Caution:
For most prior release projects, simply opening the project in TopLink Workbench will upgrade your project. However, to upgrade release 9.0.3 (and earlier) projects, you must follow specific upgrade procedures and use the Package Rename tool.Refer to Oracle TopLink Release Notes for more information.
Click Open Project on the toolbar. The Choose a File dialog box appears. You can also open a project by choosing File > Open from the menu.
Note:
The File menu option contains a list of recently opened projects. You can select one of these projects to open. See Section 5.4.1, "How to Use General Preferences" for information on customizing this list.Select the TopLink Workbench project file ( .mwp
) to open, and click Open. TopLink Workbench displays the project information.
If you open a TopLink Workbench version 3.n project that contains EJB information, the Potential EJB Descriptors dialog box appears.
Figure 116-2 Potential EJB Descriptors Dialog Box
Select which of the descriptors should be imported as EJB descriptors, the project persistence type, and click OK.
You can also specify whether or not TopLink Workbench generates methods and attributes that comply with the EJB specification, if they are not found within the current class descriptor(s).
If you open a TopLink Workbench version 9.0.3 (or later) project, the Create New TopLink Workbench Project from Previous Version dialog box appears.
Figure 116-3 Create New TopLink Workbench Project From Previous Version Dialog Box
To convert the old project to the current format and view the project immediately, click Save Later.
To convert the old project to the current format and save it to a new location and then view the project, click Save Now.
TopLink Workbench does not automatically save your project. Be sure to save your project often to avoid losing data.
To save your project(s), use this procedure:
Click Save or Save All to save your project(s).
You can also save a project by choosing File > Save or File > Save All from the menu.
If you close TopLink Workbench while there are currently unsaved changes, the Save Project dialog box appears.
Select the project(s) to save and click OK.
Click Select All to select all the available projects.
To save your project with a different name or location, use this procedure:
Choose File > Save As. The Save As dialog box appears.
Select a name and location, then click Save.
Use the project status report to display a list of all warnings and errors in the TopLink Workbench project. This report is similar to the Problems window (see Section 5.3, "Using TopLink Workbench"), but lets you easily copy and paste the errors into documents or messages. To generate the project status report, use this procedure:
Right-click the Problems label above the Problems window and select Problem Report. The Project Status Report dialog box appears, displaying the status of each TopLink Workbench project.
You can also generate the project status report by selecting Tools > Problem Report from the menu.
See Section A.3, "TopLink Workbench Error Reference" for information on each reported error.
To copy the report to another application, click Copy.
To use your project with the TopLink Foundation Library at run time, you must either generate deployment XML or export the project to Java source code.
For all project types, TopLink Workbench can generate and export the following project information:
Deployment information (see Section 116.3.1, "How to Export Deployment XML Information Using TopLink Workbench") (project.xml
file)
Model Java source (see Section 116.3.2, "How to Export Model Java Source Using TopLink Workbench")
Note:
When exporting Java source and deployment XML, TopLink Workbench writes the database password (if applicable) using Java Cryptography Extension (JCE) encryption. For information on how to specify password encryption options, see Section 97.3, "Configuring Password Encryption".To export your deployment XML file (project.xml
), use this procedure (see Chapter 9, "Creating TopLink Files for Deployment" for detailed information):
Select the project and click Export Deployment XML.
You can also right-click the project in the Navigator and choose Export > Project Deployment XML from the context menu or choose Selected > Export > Project Deployment XML 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 file name and directory.
Note:
If your project contains errors, theproject.xml
may not be valid. See Section A.3, "TopLink Workbench Error Reference" for information on each reported error.To generate the deployment XML file that is compatible with projects prior to this release, see Section 20.11, "Configuring Deprecated Direct Mappings".
To generate the project model's Java source code, use this procedure:
Right-click the project, package, or specific descriptor in the Navigator and choose Export > Export Model Java Source from the context menu. TopLink Workbench creates a .java
file for each selected descriptor.
You can also choose Workbench > Export > Export Model Java Source or Selected > Export > Model Java Source from the menu or click Generate Source Code on the Class tab. See Section 5.7.2.1, "Configuring Class Information" for more information.
Click Generate Source Code to generate the project's model Java source.
If you have not defined deployment and source code generation defaults (see Section 117, "Configuring a Project") TopLink Workbench prompts for a root directory.
Note:
If your TopLink Workbench project uses UTF-8 character set, you must use a compatible JDK when compiling the exported Java source.