Working with the OracleAS TopLink Mapping Workbench in a Team Environment

When using an OracleAS TopLink Mapping Workbench project in a team environment, you must synchronize your changes with other developers. See "Merging Files" for more information.

You can use the OracleAS TopLink Mapping Workbench with a source control system (see "Using a Source Control Management System") to facilitate enterprise-level team development. If you have a small development team, you can manage the changes from within XML files (see "Sharing Project Objects").

Using a Source Control Management System

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 OracleAS TopLink Mapping Workbench project files. These project files are maintained by the OracleAS TopLink Mapping Workbench and written in XML file format.

The source control system's check in and out mechanism defines how to manage the source (the XML source and OracleAS TopLink Mapping Workbench project file) in a multi-user environment.

To Check Out and In OracleAS TopLink Mapping Workbench Project Files:

Although your actual development process will vary, depending on your SCM tool, a typical process involves:

Determine (based on your SCM system) which files to retrieve from the source management system.
Edit the project using the OracleAS TopLink Mapping Workbench.
Save the edited project. If the OracleAS TopLink Mapping Workbench displays the Read Only Files dialog (see Figure 1–15 on page 1-23), make a note of these files, they must be unlocked and possibly merged.
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 OracleAS TopLink Mapping Workbench project.

Merging Files

The most difficult aspect of team development is merging changes from two (or more) 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:

Merging Project Files
Merging Projects

See Example 1–1 and Example 1–2.

Merging Project Files

Project files contain references to the objects in the project. Generally, your project <projectName>.mwp contains:

Database information – <database>
- Database tables – <tables>
Descriptors – <descriptors>
Repository – <repository>
- Classes – <classpath-entries>

Changes in these parts of the .mwp file are normally caused by adding, deleting, or renaming project elements.

To Merge Project Files:

Generally, you will 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. Use this procedure to merge the project's .mwp file:

Perform a file comparison between the <projectName>.mwp file in the repository and the your local copy. The file comparison shows the addition or removal of an element inside the owner (i.e., <database>, <descriptors>, or <repository>).
Insert or delete the XML into 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 1-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 OracleAS TopLink Mapping Workbench project. To merge your work with the newly changed project:

Perform a file comparison on the <projectName>.mwp 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 to the current files 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

Merging Table, Descriptor, and Class Files

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)

The OracleAS TopLink Mapping 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).

To Merge a Table, Descriptor, or Class File:

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.

Perform a file comparison on the specific .xml file(s) in merge status (i.e., table, descriptor, or class). The file comparison shows the addition or removal of an XML element.
Insert or remove the XML into your local .xml file to bring it up to date to the current files the source repository.

Example 1-2 Merging Files Sharing Project Objects

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:

Perform a file comparison on the com.demo.Employee.ClassDescriptor.xml file located in <projectRoot>/Descriptor/ 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 <mappings> 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.

Sharing Project Objects

You can also share project objects by copying the table or descriptor file(s) into the appropriate directories in the target project.

After copying the file(s), 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.

Managing the ejb-jar.xml File

When working in a team environment, manage the ejb-jar.xml file similarly to the .xml project files. The OracleAS TopLink Mapping 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 version control your work.

Working with Locked Files

When working in a team environment, your source control system may lock files when you retrieve them from the repository. If the OracleAS TopLink Mapping Workbench attempts to save a locked file, the Version Control Assistance dialog box appears, showing the locked files.

Figure 1-15 Version Control Assistance

Description of the illustration readonly.gif

Select one of the following methods to save your project:

Use your source control system to unlock the files, then click Save.
Click Save As to save the project to a new location.

See "Saving Projects" on page 2-4 for more information.