Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter contains the following information:
For information on the various types of projects available, see "TopLink Project Types".
You can create a project using TopLink Workbench or Java code.
Oracle recommends using 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 "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 "Using Java" and Oracle TopLink API Reference.
You can use TopLink to create a project, if any of the following conditions are met:
You have both an object and data model: see "Creating a Project for an Existing Object and Data Model".
You have an object model, but no data model yet: see "Creating a Project From an Existing Object Model".
You have a data model, but no object model yet: "Creating a Project From an Existing Data Model".
You have an XML schema (XSD) document, but no object model yet: see "Creating an XML Project From an XML Schema".
If you have both XSD and object model classes, you can create an XML project using the procedure described in "Using TopLink Workbench".
You have a non-OC4J CMP project, you can create a project by migrating your application to OC4J and TopLink persistence: see "Creating a Project by Migrating an EAR to OC4J".
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 "Creating a Project From an OC4J EJB CMP EAR at Deployment Time".
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 "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 "Using 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 OC4J), see Chapter 7, "Integrating TopLink With an Application Server ". To create a new project from JAXB, see "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 18-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 "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 J2C adapter to use. See "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 "Creating an XML Project From an XML Schema"). See "XML Projects" for more information. |
For more project information, continue with the following:
Configure the project (see Chapter 19, "Configuring a Project").
Add mappings and descriptors (see Chapter 23, "Understanding Descriptors" and Chapter 30, "Understanding Mappings").
Export the project for use with the TopLink runtime (see "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 18-1).
Compile the project class.
Example 18-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: Use TopLink Workbench to create a Java project class from an existing project. This provides a starting point for a custom project class. For more information, see "Exporting Project Java Source". |
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.
This procedure applies to relational project types.
Create the project (see "Using TopLink Workbench").
Configure the project classpath (see "Configuring Project Classpath").
Import classes (see "Importing and Updating Classes").
Import database tables (see "Importing Tables From a Database").
Configure project options (see Chapter 19, "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, use this procedure to create your TopLink project and automatically generate the corresponding data model.
This procedure applies to relational projects.
Create the project (see "Using TopLink Workbench").
Configure the project classpath (see "Configuring Project Classpath").
Import classes (see "Importing and Updating Classes").
Generate database tables. For more information, see the following:
Configure project options (see Chapter 19, "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), use this procedure to create your TopLink project and automatically generate the corresponding object model.
This procedure applies to relational projects.
Create the project (see "Using TopLink Workbench").
Import database tables (see "Importing Tables From a Database").
Generate classes. For more information, see either of the following:
Configure project options (see Chapter 19, "Configuring a Project").
If you have an existing data model (XML schema document), but you do not have a corresponding object model (Java classes for domain objects), use this procedure to create your TopLink project and automatically generate the corresponding object model.
Note: If you have both XSD and object model classes, you can create an XML project using the procedure described in "Using TopLink Workbench". |
Using the TopLink JAXB compiler simplifies JAXB application development with TopLink by automatically generating both the required JAXB files and the TopLink files from your XML schema (XSD) document. Once generated, you can open the TopLink Workbench project to fine-tune XML mappings without having to recompile your JAXB object model.
You can use the TopLink JAXB compiler from TopLink Workbench (see "Using TopLink Workbench") or from the command line (see "Using the Command Line"). Oracle recommends that you use TopLink Workbench.
Note: Before you compile your generated classes, be sure to configure your IDE classpath to include< ORACLE_HOME >\lib\xml.jar . For example, see Chapter 6, "Using an Integrated Development Environment". |
For more information, see the following:
To create a new, mapped TopLink Workbench project from an XML schema using JAXB, use this procedure:
From TopLink Workbench, select File > New > Project > From XML Schema (JAXB).
Figure 18-2 Create TopLink Workbench Project using JAXB Dialog Box
Use the following information to enter data in each field of this dialog box:
Field | Description |
---|---|
From | Use these fields to specify your existing JAXB information. |
Schema File | Click Browse and select the fully qualified path to your XSD file. |
JAXB Customization File | This in an optional setting. It can be used if you have a standard JAXB configuration file that you wish to use to override the default JAXB compiler behavior. The JAXB customization file contains binding declarations for customizing the default binding between an XSD component and its Java representation. |
To | Use these fields to specify the location and options of the TopLink Workbench project. |
Output Directory | Click Browse and select the path to the directory into which generated files are written. All paths used in the project are relative to this directory. |
Output Source Directory | Click Browse and select the path to the directory (relative to the Output Directory) into which generated interfaces, implementation classes, and deployment files are written. Default: directory named source in the specified output directory. |
Output Workbench Project Directory | Click Browse and select the path to the directory (relative to the Output Directory) into which the TopLink Workbench project files are written. Default: directory named mw in the specified output directory. |
Package Name for Generated Interfaces | The optional name of the package to which generated interfaces belong. This defines your context path. If it is not specified, a package name of jaxbderived.<schema name> is used where <schema name> is the name of the schema specified by the Schema File field. |
Package Name for Generated Implementation Classes | The optional name of the package to which generated implementation classes belong. This defines your context path. If it is not specified, a package name of jaxbderived.<schema name> is used where <schema name> is the name of the schema specified by the Schema File field. |
The TopLink JAXB compiler generates JAXB-specific files (see "Understanding JAXB-Specific Generated Files") and TopLink-specific files (see "Understanding TopLink-Specific Generated Files").
Optionally, open the generated TopLink Workbench project (see "TopLink Workbench Project"), customize the generated mappings and descriptors, and reexport the TopLink project XML.
Note: Before you compile your generated classes, be sure to configure your IDE classpath to include< ORACLE_HOME >\lib\xml.jar . For example, see Chapter 6, "Using an Integrated Development Environment". |
To create a new, mapped Oracle TopLink Workbench project from an XML schema using JAXB from the command line, use the tljaxb.cmd
or tljaxb.sh
file (located in the <ORACLE_HOME>
/toplink/bin
directory) as follows:
Using a text editor, edit the tljaxb.cmd
or tljaxb.sh
file to set proxy settings (if required).
If you are using a schema that imports another schema by URL and you are operating behind a proxy, then you must uncomment the lines shown in Example 18-2 or Example 18-3 and edit them to set your proxy host (name or IP address) and port:
Execute the tljaxb.cmd
or tljaxb.sh
file (located in the <ORACLE_HOME>
/toplink/bin
directory).
The TopLink JAXB compiler generates JAXB-specific files (see "Understanding JAXB-Specific Generated Files") and TopLink-specific files (see "Understanding TopLink-Specific Generated Files").
Example 18-4 illustrates how to generate an object model from a schema using the Toplink JAXB compiler. Table 18-1 lists the compiler arguments.
Example 18-4 Generating an Object Model from a Schema with tljaxb.cmd
tljaxb.cmd -sourceDir ./app/src -generateWorkbench -workbenchDir ./app/mw -schema purchaseOrder.xsd -targetPkg examples.ox.model.if -implClassPkg examples.ox.model.impl
Table 18-1 TopLink JAXB Binding Compiler Arguments
Argument | Description | Optional? |
---|---|---|
|
Prints this usage information. |
Yes |
|
Prints the release version of the TopLink JAXB compiler. |
Yes |
|
The path to the directory into which generated interfaces, implementation classes, and deployment files are written. Default: directory named |
Yes |
|
Generate a TopLink Workbench project and necessary project files. If omitted, only runtime information is generated. |
Yes |
|
The path to the directory into which the TopLink Workbench project files are written. This argument requires the Default: directory named |
Yes |
|
The fully qualified path to your XSD file. |
No |
|
The name of the package to which both generated interfaces and classes belong. This defines your context path. To specify a different package for implementation classes, set the Default: a package name of |
Yes |
|
The name of the package to which generated implementation classes belong. If this option is set, interfaces belong to the package specified by the |
Yes |
|
Generate only interfaces. This argument is optional. Default: generate both interfaces and implementation classes. |
Yes |
|
The interfaces and classes generated. This argument is optional. Default: not verbose. |
Yes |
|
The fully qualified path and file name of a standard JAXB customization file that you can use to override default JAXB compiler behavior. |
Yes |
Optionally, open the generated TopLink Workbench project (see "TopLink Workbench Project") in TopLink Workbench, customize the generated mappings and descriptors, and reexport the TopLink project XML.
Note: Before you compile your generated classes, be sure to configure your IDE classpath to include< ORACLE_HOME >\lib\xml.jar . For example, see Chapter 6, "Using an Integrated Development Environment". |
If you configure TopLink to be the default persistence for your application server, TopLink provides automated support for migrating your existing J2EE CMP application server-specific ejb-jar.xml
file to the required toplink-ejb-jar.xml
file, including providing an appropriate TopLink Workbench project.
This procedure applies to CMP relational projects only.
For more information, see "Persistence Manager Migration".
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 default persistence manager.
For more information, see "Default Mapping in CMP Projects Using OC4J at Run Time".
Using TopLink Workbench, you can perform the following project functions:
See Chapter 19, "Configuring a Project" for additional information on working with TopLink Workbench projects.
Use this procedure to open an existing project:
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 "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 18-3 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 18-4 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 "Working With 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 Chapter 14, "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:
Exporting Deployment XML Information (project.xml
file)
Note: When exporting Java source and deployment XML, TopLink Workbench writes the database password (if applicable) using Java Cryptography Extension (JCE) encryption (when using JDK 1.4). For information on how to specify password encryption options, see "Configuring Password Encryption".Refer to Oracle TopLink Getting Started Guide for information on using password encryption with JDK 1.3 and earlier. |
For relational projects only, TopLink Workbench can also generate and export the following project information:
To export your deployment XML file (project.xml
), use this procedure (see Chapter 8, "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 19, "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 Chapter 14, "TopLink Workbench Error Reference" for information on each reported error. |
To generate the deployment XML file that is compatible with projects prior to 10g Release 3 (10.1.3.1.0), see "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 "Configuring Class Information" for more information.
If you have not defined deployment and source code generation defaults (see "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. |
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 "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 "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 |
To generate Java source that is compatible with projects prior to 10g Release 3 (10.1.3.1.0), see "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 19, "Configuring a Project") TopLink Workbench prompts for a class name and root directory.
For TopLink Workbench 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 18-2 describes how fields in the ejb-jar.xml
file correspond to specific functions in TopLink Workbench.
Table 18-2 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 "Configuring Primary Keys"). |
|
|
EJB descriptor information on the EJB Info tab (see "Configuring a Descriptor With EJB Information"). |
|
Descriptor Alias field (see "Configuring Descriptor Alias"). |
|
Direct (non-relationship) attributes on the Descriptor Info tab (see "Configuring Common Descriptor Options"). |
|
Persistence Type field on the General tab (see "Configuring Persistence Type"). The |
|
Queries listed in Queries tab (see "Configuring Named Queries at the Descriptor Level"). Note: The |
One-to-one, one-to-many, and many-to-many mappings (see Part X, "Relational Mappings"). |
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 theejb-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 ). |
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.
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 ejb-jar.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 "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. |