Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter includes information on using TopLink with an integrated development environment (IDE). This chapter includes the following sections:
In addition to the development environment described here, TopLink can be used with any J2EE development environment and process.
This section contains information on how to configure TopLink for use with Oracle JDeveloper. JDeveloper is a J2EE development environment with end-to-end support to develop, debug, and deploy e-business applications and Web services.
Starting with Oracle JDeveloper 10g, the standard JDeveloper installation includes an embedded TopLink editor. Refer to the JDeveloper documentation for complete information.
To use TopLink with JDeveloper 9.0.4 (and earlier), use the following procedure to add the TopLink JAR files to your JDeveloper projects:
Select a JDeveloper project in the System Navigator window.
Choose Project > Project Settings. The Project Settings window appears.
Choose Configurations > Development > Libraries. A list of predefined and user-defined libraries appears.
Click New to create a new library that will contain the TopLink .jar
files. The New Library dialog box appears.
Enter a name for the new library–for example, TopLink. Ensure that the default choice for Location remains as User Libraries.
Figure 6-2 Creating a New Library Dialog Box
To edit the Class Path and add the TopLink .jar
files, click Edit.
Add the following to the beginning of your Class Path:
<ORACLE_HOME>\toplink\jlib\toplink.jar <ORACLE_HOME>\toplink\jlib\antlr.jar <ORACLE_HOME>\lib\xmlparserv2.jar <ORACLE_HOME>\lib\xml.jar
Click OK. On the Project Settings window click OK.
Using an Existing User-Defined TopLink Library
After a user library is created, it can be referenced again by any other project. Revisit the Libraries window of the Project Settings, and add the TopLink Library to any project with which you want to use TopLink.
When using TopLink 10g Release 3 (10.1.3.1.0) with Oracle JDeveloper, you should be aware that you cannot configure all sessions.xml
options with the JDeveloper mapping editor.
To configure supported options (prior to 10g Release 3 (10.1.3.1.0)), use the JDeveloper mapping editor. For details, refer to the JDeveloper online help at:
http://www.oracle.com/technology/documentation/9i_jdev.html
To configure the new TopLink 10g Release 3 (10.1.3.1.0) options, including, cache coordination options (see Chapter 88, "Configuring a Coordinated Cache"), historical sessions (see Chapter 78, "Configuring Historical Sessions"), and connection policy for server sessions (see "Configuring Connection Policy") use one of the following methods:
Use a SessionEventListener.preLogin(SessionEvent)
method
When accessing the session from the session manager, request it with the loggedIn
option set to false
. The returned session can then be customized and you can invoke login.
You can use TopLink Workbench with a source control management (SCM) system to facilitate enterprise-level team development (see "Using a Source Control Management System"). If you have a small development team, you can manage the changes from within XML files (see "Sharing Project Objects").
When using a TopLink Workbench project in a team environment, you must synchronize your changes with other developers. See "Merging Files" for more information.
If you use an enterprise, file-based source control management system to manage your Java source files, you can use the same system with your TopLink Workbench project files. These project files are maintained by TopLink Workbench and written out in XML file format.
The check in and check out mechanism for the source control system defines how to manage the source (the XML source and TopLink Workbench project file) in a multiuser environment.
Checking Out and Checking In TopLink Workbench Project Files
Although your actual development process will vary depending on your SCM tool, a typical process involves the following steps:
Determine (based on your SCM system) which files to retrieve from the source management system.
Edit the project using TopLink Workbench.
Save the edited project. If TopLink Workbench displays the Read-Only Files dialog box, make a note of these files, they must be unlocked and possibly merged. See "Working With Locked Files" for more information.
Merge the required project files. See "Merging Files" for details.
Check in the modified files, then retrieve from the repository any files that have been added or modified for this TopLink Workbench project.
The most difficult aspect of application development is merging changes from two (or more) development team members that have simultaneously edited the same file. If one developer checks in his or her changes, a merge condition exists. Use a file comparison tool to determine the merged aspects of the project. The files to edit will vary, depending on the type of merge:
Example 6-1 and Example 6-2 demonstrate a merge out merging technique.
Project files contain references to the objects in the project. Generally, your project <projectName>
.mwp
contains the following elements:
Database information: <database>
Database tables: <tables>
Descriptors: <descriptors>
Repository: <repository>
Classes: <classpath-entries>
Changes in these parts of the .mwp
file are usually caused by adding, deleting, or renaming project elements.
To merge project files, you will generally need to merge a project file if another developer has added or removed a descriptor, table, or class, and checked in the project while you were adding or removing descriptors, tables, or classes from the same project. To merge the project's .mwp
file, use this procedure:
Perform a file comparison between the <projectName>
.mwp
file in the repository and your local copy. The file comparison shows the addition or removal of a project element inside the owner (that is, <database>
, <descriptors>
, or <repository>
).
Insert the XML script to, or delete from your local <projectName>
.mwp
file (inside the corresponding owner element). This brings your local code up-to-date to the current code in the code repository.
Retrieve any updated files, as indicated by your source control system.
Your local source now matches the repository.
Example 6-1 Merging Projects
Another developer has added and checked in a new Employee class descriptor to the com.demo
package while you were working with the same TopLink Workbench project. To merge your work with the newly changed project, follow these steps:
Perform a file comparison on the <projectName>
.mwp
file to determine the differences between your local file and the file in the repository. Your SCM system may show the file in merge status.
The file comparison shows the addition of the <package-descriptor>
tag and a <name>
element inside that tag:
<package-descriptor> <name>com.demo.Employee.ClassDescriptor</name> </package-descriptor>
Insert this XML into your <projectName>
.mwp
file (inside the <descriptors>
element) to bring it up-to-date with the current files in the source repository.
Retrieve any new or updated files from your source control system. This includes the newly added Employee class descriptor.
Check in files that you have modified.
Developers who concurrently modify the same existing table, descriptor, or class file will create a merge condition for the following files:
Table: <tableName
>.xml
(one for each table)
Descriptor: <descriptorName.type>
.xml
(one for each descriptor)
Class: <className>
.xml
(one for each class)
TopLink Workbench changes these files when saving a project if you have changed any of the contents within them (such as adding a mapping to a descriptor, adding an attribute to a class, or a changing a field reference in a table).
If another developer has changed an attribute in a table, descriptor, or class, while you were changing a different mapping on that same descriptor, you will need to merge your project. To merge your project, use this procedure:
Perform a file comparison on the specific .xml
files in merge status (that is, table, descriptor, or class). The file comparison shows the addition or removal of an XML element.
Insert the XML script to, or remove from your local .xml
file to bring it up-to-date with the current files in the source repository.
Example 6-2 Merging Files
Another developer has added and checked in the firstName mapping to the Employee class descriptor while you were changing a different mapping on that same descriptor. To merge your work with the newly changed project, use this procedure:
Perform a file comparison on the com.demo.Employee.ClassDescriptor.xml
file located in <projectRoot>
/Descriptor/
directory that is in merge status.
The file comparison shows the addition of the <mapping>
tag and the elements inside that tag:
<mapping> <uses-method-accessing>false</uses-method-accessing> <inherited>false</inherited> <read-only>false</read-only> <instance-variable-name>firstName</instance-variable-name> <default-field-names> <default-field-name>direct field=</default-field-name> </default-field-names> <field-handle> <field-handle> <table>EMPLOYEE</table> <field-name>F_NAME</field-name> </field-handle> </field-handle> <mapping-class>MWDirectToFieldMapping </mapping-class> </mapping>
Insert this XML block into your local com.demo.Employee.ClassDescriptor.xml
file (inside the existing <mapping>
element) to bring it up to date to the current files in the source repository.
Retrieve any new files noted as missing by your source control system. This includes any tables or descriptors that may be referenced by the new mapping.
Check in files that you have modified.
You can also share project objects by copying the table or descriptor files into the appropriate directories in the target project.
After copying the files, insert a reference to the table, descriptor, or class in the appropriate place in the <projectName>
.mwp
file. All references contained within the project file must refer to an existing object in the project.
When working in a team environment, manage the ejb-jar.xml
file similarly to the .xml
project files. TopLink Workbench edits and updates the ejb-jar.xml
file, if necessary, when working with an EJB project.
If you use a version control system, perform the same check in and check out procedures. For merge conditions, use a file comparison tool to determine which elements have been added or removed. Modify the file as necessary and check in the file to exercise version control on your work.
When working in a team environment, your source control system may lock files when you retrieve them from the repository. If TopLink Workbench attempts to save a locked file, the Version Control Assistance dialog box appears, showing the locked files.
Figure 6-3 Version Control Assistance Dialog Box
Select one of the following methods to save your project:
Use your source control system to unlock the files, and then click Save.
Click Save As to save the project to a new location.
See "Saving Projects" for more information.