View source for Using an Integrated Development Environment (ELUG)

[[Image:Elug draft icon.png]] '''For the latest EclipseLink documentation, please see http://www.eclipse.org/eclipselink/documentation/ '''

----

<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__
[[Special:Whatlinkshere/Using an Integrated Development Environment (ELUG)|Related Topics]]</div> 
In addition to the development environment described in this section, you can use EclipseLink with ''any'' Java EE development environment and process.



==Configuring Workbench with Source Control Management Software==
You can use Workbench with a source control management (SCM) system to facilitate enterprise-level team development (see [[#How to Use a Source Control Management System|How to Use a Source Control Management System]]). If you have a small development team, you can manage the changes from within XML files (see [[#How to Share Project Objects|How to Share Project Objects]]).

When using a Workbench project in a team environment, you must synchronize your changes with other developers. See [[#How to Merge Files|How to Merge Files]] for more information.


===How to Use 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 Workbench project files. These project files are maintained by 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 Workbench project file) in a multiuser environment.

'''Checking Out and Checking In 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 Workbench.
# Save the edited project. If Workbench displays the Read-Only Files dialog box, make a note of these files, they must be unlocked and possibly merged. See [[#How to Work with Locked Files|How to Work with Locked Files]] for more information.
# Merge the required project files. See [[#How to Merge Files|How to Merge Files]] for details.
# Check in the modified files, then retrieve from the repository any files that have been added or modified for this Workbench project.


===How to Merge Files===
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 you check in your 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, as follows:
* [[#Project Files|Project Files]]
* [[#Merging Table, Descriptor, and Class Files|Merging Table, Descriptor, and Class Files]]

[[#example_merging_projects|Merging Projects]] and [[#example_merging_files|Merging Files]] examples demonstrate a ''merge out'' merging technique.


====Merging Project Files====
Project files contain references to the objects in the project. Generally, your project <tt>''<projectName>''.mwp</tt> contains the following elements:

* Database information: <tt><database></tt>
** Database tables: <tt><tables></tt>
* Descriptors: <tt><descriptors></tt>
* Repository: <tt><repository></tt>
** Classes: <tt><classpath-entries></tt>

Changes in these parts of the <tt>.mwp</tt> 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 <tt>.mwp</tt> file, use this procedure:
# Perform a file comparison between the ''<tt><projectName></tt>''.<tt>mwp</tt> 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, <tt><database></tt>, <tt><descriptors></tt>, or <tt><repository></tt>).
# Insert the XML script to, or delete from your local ''<tt><projectName></tt>''.<tt>mwp</tt> 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.


<span id="example_merging_projects"></span>
'''''Example: Merging Projects'''''<br>
Another developer has added and checked in a new '''Employee''' class descriptor to the <tt>com.demo</tt> package while you were working with the same Workbench project. To merge your work with the newly changed project, follow these steps:
<ol>
<li>Perform a file comparison on the ''<tt><projectName></tt>''.<tt>mwp</tt> 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.<br>The file comparison shows the addition of the <tt><package-descriptor></tt> tag and a <tt><name></tt> element inside that tag: 
<div class="pre">

 <package-descriptor>
    <name>com.demo.Employee.ClassDescriptor</name>
 </package-descriptor>

</div>
</li>
<li>Insert this XML into your ''<tt><projectName></tt>''.<tt>mwp</tt> file (inside the <tt><descriptors></tt> element) to bring it up to date with the current files in the source repository.</li>
<li>Retrieve any new or updated files from your source control system. This includes the newly added '''Employee''' class descriptor.</li>
<li>Check in files that you have modified.</li>
</ol>


====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: ''<tt><tableName</tt>''><tt>.xml</tt> (one for each table)
* Descriptor: ''<tt><descriptorName.type></tt>''<tt>.xml</tt> (one for each descriptor)
* Class: ''<tt><className></tt>''<tt>.xml</tt> (one for each class)

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 <tt>.xml</tt> 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 <tt>.xml</tt> file to bring it up to date with the current files in the source repository.


<span id="example_merging_files"></span>
'''''Example: Merging Files'''''<br>
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:
<ol>
<li>Perform a file comparison on the <tt>com.demo.Employee.ClassDescriptor.xml</tt> file located in ''<tt><projectRoot></tt>''<tt>/Descriptor/</tt> directory that is in merge status.<br>The file comparison shows the addition of the <tt><mapping></tt> tag and the elements inside that tag:  <br>
<div class="pre">
<source lang="java">
 <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>
            &lt;table>EMPLOYEE</table>
            <field-name>F_NAME</field-name>
        </field-handle>
    </field-handle>
 <mapping-class>MWDirectToFieldMapping </mapping-class>
 </mapping>
</source>
</div>
</li>
<li> Insert this XML block into your local <tt>com.demo.Employee.ClassDescriptor.xml</tt> file (inside the existing <tt><mapping></tt> element) to bring it up to date to the current files in the source repository.</li>
<li> 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.</li>
<li> Check in files that you have modified.</li>
</ol>

===How to Share Project Objects===
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 ''<tt><projectName></tt>''<tt>.mwp</tt> file. All references contained within the project file must refer to an existing object in the project.


===How to Work with Locked Files===
When working in a team environment, your source control system may lock files when you retrieve them from the repository. If Workbench attempts to save a locked file, the Version Control Assistance dialog box appears, showing the locked files.'''''


<span id="Figure 6-1"></span>
'''''Version Control Assistance Dialog Box'''''

[[Image:readonly.gif|Version Control Assistance Dialog Box]]<br /><br />

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 [[Creating%20a%20Project%20(ELUG)#How to Save Projects|How to Save Projects]] for more information.




----
''[[EclipseLink User's Guide Copyright Statement|Copyright Statement]]''


[[Category: EclipseLink User's Guide]]
[[Category: Release 1]]
[[Category: Concept]]