6 Versioning Applications with Source Control

This chapter describes how to use source control systems to manage the versions of applications developed in a team environment. It discusses the available version control systems, how to download the various version-control extensions available to Oracle JDeveloper, and then includes instructions for each of the source control systems that can be used with JDeveloper.

This chapter includes the following sections:

6.1 About Versioning Applications with Source Control

Developing in teams often requires coordination among multiple developers who may be called upon to make changes to the same files, to track these changes against project management or bug reporting systems, and eventually to check in or commit their edited files to a commonly used repository of content that will be built into a functioning product.

To assist in team development of software products, JDeveloper integrates the popular version control system, Subversion, into its available feature set. You can access a number of commands for Subversion directly from the JDeveloper interface, through the Version menu or through the Versioning Navigator.

For users familiar with other versioning systems, JDeveloper offers support for CVS, Perforce and Serena Dimensions as downloadable extensions. You can choose from these and other extensions by selecting Help > Check for Updates.

Finally, this section includes a compilation of several best-practices recommendations on writing XML in a way that makes version control much more effective and useful for this important data type.

6.2 Downloading Source Control Extensions in Oracle JDeveloper

JDeveloper offers a number of tools for developing in teams. These include an integrated solution, Subversion, as well as a selection of extensions that interface JDeveloper with popular version control systems. In addition, an application lifecycle management system, Oracle Team Productivity Center, is also available as a downloadable extension.

While most members of a team will interact with their selected versioning system by checking files in and out and managing their changes to the project they are working on, at least one team member is typically required to administer and maintain the versioning system as it relates to JDeveloper. If you are the administrator for your versioning system, you will most likely have additional tasks beyond checking files in and out.

If your team uses one of the versioning systems that require you to download a JDeveloper Extension to integrate your versioning system with JDeveloper, you can browse for the versioning system from the Update Center by selecting Help > Check for Updates. Be sure to select all update centers when you search for your versioning system.

6.3 Using Subversion with Oracle JDeveloper

JDeveloper is integrated with the popular team development solution Subversion (SVN). If you are part of a team that uses Subversion, JDeveloper's Versioning menu contains commands for using Subversion to manage the content you are working on while maintaining a connection to your team's repository and tracking changes, merges, and more. Setting up Subversion involves creating a repository for your source-controlled files, making sure that JDeveloper can connect to that repository, importing files to the repository, and more.

In general, you begin by importing your working files into the Subversion repository to bring them under version control. Once in the repository, your files are then available to be checked out from the Subversion repository to a local folder known as the "Subversion working copy". The working copy is typically in your local file system for ease and speed of access, but it can also be in a network location if you prefer. When you create a new file in JDeveloper (or move it into JDeveloper), you store it in the Subversion working copy. When you are ready to make your work available to the team, you add these new files to Subversion control. When it comes time to make your changed and new files available to other users, you can do so by committing them to the Subversion repository. To take advantage of the work others on your team have done, you can copy changed files from the Subversion repository to your working copy by updating your files.

After completing setup, your work with Subversion will revolve around checking files out, editing them in JDeveloper, and checking them in with your changes. You may also need to resolve conflicts between changes you made and those made by others in your team. Files may also be moved in and out of Subversion control, and finally, you might use special properties of the files associated with specific versions for tracking bugs, customer requests, and other characteristics.

6.3.1 How To Set Up Subversion and JDeveloper

Setting up Subversion involves creating a repository for your source-controlled files, making sure that JDeveloper can connect to that repository, importing files to the repository, and more.

You do not have to install any Subversion software in addition to the JDeveloper Subversion extension, except in the following circumstances:

  • You wish to create a local Subversion repository using the JDeveloper Subversion VCS extension.

  • You wish to use a Java binding (helper library) other than SVNKit, which is the one supplied with the extension.

  • You wish to connect to a Subversion repository through a proxy server

In all of the above cases, you will need to install separate Subversion client software. If you wish to use an alternate Java binding, you will additionally have to install the binding software.

An alternate Java binding that you could use is JavaHL. This has the advantage of being developed and maintained by the makers of Subversion and thus allows repository access via a wide range of protocols (http, https, file, svn, svn+ssh). To use the JavaHL binding, you must install Subversion client software independently of JDeveloper. Once installed, JDeveloper will allow you to choose between JavaHL and SVNKit client options.

To Install Subversion Client Software:

  1. Download the Subversion installer (svn-1.3.2-setup.exe) from http://subversion.apache.org/ (to, for example, c:\downloads).

  2. Run the installer and place the Subversion client in a convenient location, for example c:\subversion. Reboot your computer.

This procedure assumes that the operating system is Windows. For non-Windows environments, consult the documentation for the operating system package management system to ensure the vendor-supplied Subversion client contains JavaHL.

To check the installation so far, open a command prompt and type svn help. You should see a list of subcommands. If not, check that the system path contains the bin directory of the location where the client software was installed (in this example, c:\subversion\bin).

To Install JavaHL Binding Software:

  1. Download the JavaHL binary installer (svn-win32-1.3.2_javahl.zip) from http://subversion.apache.org/ (to, for example, c:\downloads).

  2. Using WinZip or a similar tool, extract the file libsvnjavahl-1.dll from svn-win32-1.3.2_javahl.zip into the bin directory of your Subversion client installation (in this example, c:\subversion\bin).

  3. Run the installer and place the Subversion client in a convenient location, for example c:\subversion. Reboot your computer.

  4. Start or restart JDeveloper.

6.3.1.1 How to Connect to a Subversion Repository Through a Proxy Server

If you wish to connect to a Subversion repository through a proxy server, you must first install separate Subversion client software.

Once you have installed the Subversion client software, you will have a Subversion subdirectory in your Windows Application Data directory. To find the Application Data directory, at the c:/ prompt type cd %APPDATA%. Then open the Subversion subdirectory. (On Linux the equivalent subdirectory will be in ~/.subversion, where ~ is the home directory.)

In the Subversion subdirectory will be a file named servers. Open this file with a text editor and find the [global] section. Remove the comment marker (#) from the line http-proxy-host and overtype the placeholder proxy information with the details of the proxy server that you use. Remove the comment marker (#) from the line http-proxy-port and overtype the placeholder port information with the port number for the proxy server. If you wish to exclude certain URLs from using the proxy server, remove the comment marker (#) from the line http-proxy-exceptions and overtype the placeholder URLs with URLs that you wish to exclude.

Add additional http-proxy-host and http-proxy-port lines with details of any other proxy servers that you use.

It is important that the proxy server supports all the http methods used by Subversion. Some proxy servers do not support the following methods by default: PROPFIND, REPORT, MERGE, MKACTIVITY, CHECKOUT. If you experience problems with using a proxy server to access a Subversion repository, ask the server's system administrator to change the configuration to support these http methods.

6.3.1.2 How to Check the Installation

In JDeveloper, select Subversion as the versioning system (Versioning > Configure, and then select Subversion).

Open the main Subversion preferences page (Tools > Preferences > Versioning), and then check that the required client installation is available. If more than one is listed, select the one that you wish to use.

Important: If you subsequently accept an update of the JDeveloper Subversion extension from the Update Center (Official Oracle Extensions and Updates), the client preference will be reset to SVNKit, even if you had previously chosen an alternate client.

6.3.1.3 How to Create a Subversion Repository

In most cases, you will connect to your team's Subversion repository. As you develop your projects and applications, you will check files out from the Subversion repository, modify them, and check them back in. This is the typical, and recommended, practice for using Subversion.

Depending on your installation, however, you may find it necessary to create a Subversion repository on your local file system through JDeveloper. A connection to the repository will be created at the same time.

JDeveloper will try to use the file:/// protocol to access the newly created repository. SVNKit, the Subversion client installed with JDeveloper, supports the file:/// protocol. If you are using a Subversion client that does not support the file:/// protocol, you will need to use a different access method (http://, https://, svn:// or svn+ssh://). Consult the Subversion documentation for how to do this.

To Create a Subversion Repository:

  1. Choose Versioning > Create Local Repository.

    If your installation does not support local repository creation, you will see an error message. Otherwise, the Create Subversion Repository dialog will open.

  2. Complete the Create Subversion Repository dialog.

    To obtain help while using the dialog, press F1 or click Help.

To Browse a Subversion Repository:

  1. Expand the connection to your Subversion repository in the Versioning Navigator.

  2. Double-click on a folder to view its contents.

  3. Right-click on an element to view available operations.

6.3.1.4 How to Create or Edit a Subversion Connection

Before you can work with a Subversion repository through JDeveloper, you must create a connection to it. You can subsequently edit the connection details if they change for any reason.

Typically, you will obtain the details of your Subversion connection (server name, user ID, password, etc.) from your team or version control administrator. You will need to know those details before you create a connection to your Subversion repository.

To Create a Subversion Connection:

  1. In the Versioning Navigator (View > Team > Versioning Navigator), right-click the Subversion node and choose New Repository Connection.

    The Create Subversion Connection dialog is opened. For help when using this dialog, press F1 or click Help.

  2. Enter the URL of the location of the Subversion repository.

  3. Optionally, enter a name for the connection.

  4. If the Subversion repository has been set up with password protection, enter the username and password.

  5. If you want to test the connection to the Subversion repository, click the Test Connection button. The results will be displayed in the Status area.

  6. To complete the connection, click OK.

To Edit a Subversion Connection:

  1. In the Subversion Navigator (View > Team > Versioning Navigator), right-click the Subversion connection name and choose Properties.

    The Edit Subversion Connection dialog is opened. For help when using this dialog, press F1 or click Help.

  2. Make changes as required and click OK.

6.3.1.5 How to View Subversion Repository Content

You can view the current content of the Subversion repository through the Versioning Navigator. The nodes under your selected Subversion connection unfold to reveal the structure and file content of the Subversion repository.

You can open a read-only version of a Subversion repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the Subversion repository since you checked out or updated your local versions.

Folders in the Subversion repository, visible from the Versioning Navigator, offer the following operations:

New

Opens the new gallery, from which you can create applications, connections, projects, and other entities.

New Remote Directory

Opens the Create Directory dialog, which lets you create a new directory to associate with the URL of the element on which you right-clicked.

Delete

Removes the selected element immediately from the JDeveloper view, without a confirmation dialog. Use with caution.

Check Out

By default, opens the Check Out from Subversion dialog.

If you have configured JDeveloper for a different version control system, Check Out will open the checkout dialog for your selected version control software.

6.3.1.6 How to Check Out Files from the Subversion Repository

When you begin working on a project in Subversion, you check out the files you will be working with. It is recommended that you check out the entire application from the Subversion repository, so that you will have access to all files in that application in your local work area. Subversion uses the term modules to refer to the application it is recommended you check out.

Note:

With Subversion, there is no "check in" procedure, so you do not check in files that you have updated and check them out again when you next want to work on them. Instead, when you have finished working on your local copies of files, you commit them to the Subversion repository to bring the files held there up to date.

To incorporate into your local copies changes that other developers have committed to the Subversion repository since you checked out your files, you update them.

When you check out Subversion files, they are copied from the Subversion repository to a new location (specified by you) on your local machine. This location and the files within it constitute the Subversion "working copy".

To check out modules from the Subversion repository:

  1. In the Versioning Navigator, select the repository node or folder containing the files that you want to check out.

  2. Choose Versioning > Check Out.

    If there is no current connection to a Subversion repository, the Create Subversion Connection dialog is opened for you to create one.

    The Check Out from Subversion dialog is displayed. To obtain more information when working with the dialog, press F1 or click Help.

  3. Make sure that the Subversion connection that the dialog displays is the correct connection (if you have more than one Subversion connection or repository).

  4. Browse to the path in the Subversion connection containing the application files you wish to check out.

  5. Enter the destination in your work area to which you wish the checked-out files to be copied, or click Browse to navigate to your local work area.

  6. You have the option of checking specific tags, if your team uses them.

  7. If you wish to check out files within folders contained by this Subversion module, make sure to select Depth.

    When you have made all your selections, click OK.

6.3.1.7 How to Update Files from the Subversion Repository

Use these procedures to bring the files you have been working on up-to-date with a revision in the Subversion repository.

It is recommended that you perform the update operation on a working copy.

When you use Update Working Copy, all the files in your checked out working copy will be updated, regardless of which node you have active in your application in the JDeveloper Application Navigator. The alternative is to select Update. This will only update the folder or file (and any child folders and files) that you have selected in the Application Navigator.

To update a working copy (recommended):

  1. In the Application Navigator, select a navigator node or file that is part of the working copy.

  2. Select Versioning > Update Working Copy.

    The Update Working Copy dialog is displayed with the working copy folder listed.

  3. Ensure that the folder shown is the correct one for the working copy that you wish to update. If it is not, cancel the dialog and begin again from step 1.

  4. Set the options on the Update Working Copy dialog as required.

    To obtain more information about the options, press F1 or click Help.

  5. To update the working copy from the Subversion repository, click OK.

You can also update individual files. However, this runs the risk of not updating all files that may have been modified by your team members since the last time you checked them out.

To update individual files:

  1. In the Application Navigator, select the file(s) that you wish to update and choose Versioning > Update.

    The Update Resources dialog is displayed with the file(s) listed.

  2. Set the options on the Update Resources dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) from the Subversion repository, click OK.

6.3.1.8 How to Import JDeveloper Files Into Subversion

Files that you created within (or brought into) JDeveloper before using Subversion control must be imported into the Subversion repository, and then checked out from it.

To import an existing JDeveloper project or application into Subversion:

  1. In the Application Navigator, select the application or project that you want to import into Subversion.

  2. Select Versioning > Import Files.

    The Import to Subversion wizard opens.

  3. Complete the wizard. For help while using the wizard, press F1 or click Help.

    If you allowed the wizard to check out the imported files, the files are shown in the Application Navigator with a version number next to them. You may have to refresh the view before the files are shown.

    If you did not allow the wizard to check out the imported files, you must now check them out before you can work on them.

6.3.1.8.1 How to Import an Application to Subversion

You can also import an entire application into Subversion using the JDeveloper Version Application feature.

To import files using Version Application:

  1. Select the application you wish to add to version control.

  2. Select Versioning > Version Application.

  3. From the Version Application dialog, select the Subversion repository. This will open the Import to Subversion wizard.

After you import files into Subversion using the Version Application feature, you will notice that Subversion creates two directories, one as your work area and one as a backup directory.

For example: after creating a new application called Catalog, select Versioning > Version Application > Subversion. Be sure to select the Perform Checkout from the Options page, then finish the wizard.

When the wizard completes, browse to the local directory that you have specified as the Source Directory for this application in Subversion. You will see two directories listed there: Catalog.svn-import-backup and Catalog.svn-import-workarea.

JDeveloper (and Subversion) will use the Catalog.svn-import-workarea directory for file access, checkout/checkin, and other activities. You should avoid editing, moving, or manipulating files in those directories outside of JDeveloper and Subversion.

6.3.2 How to Work with Files in Subversion

After completing setup, your work with Subversion will revolve around checking files out, editing them in JDeveloper, and checking them in with your changes. You may also need to resolve conflicts between changes you made and those made by others in your team. Files may also be moved in and out of Subversion control, and finally, you might use special properties of the files associated with specific versions for tracking bugs, customer requests, and other characteristics.

6.3.2.1 How to Add a File to Subversion Control

When you create a new file in JDeveloper that is part of a local working copy (that is, an application that has been versioned and checked out of your SVN repository), you need to add and then commit the file to Subversion control before you can use the JDeveloper Subversion facilities with it. The preferred method is to set up JDeveloper to do this automatically, through the Preferences menu.

To add new files on commit:

  1. Select Tools > Preferences > Versioning > General.

  2. Select Automatically Add New Files On Committing Working Copy.

  3. Click OK.

You can also place individual files under Subversion control.

To put individual files under Subversion control:

  1. Select the files in the Application Navigator and choose Versioning > Add.

    The files can be your work files, or they can be the application and project files used by JDeveloper.

    The Add to Source Control dialog is displayed with the files listed.

  2. To add the files to Subversion control, click OK.

    The files are now shown in the Application Navigator with a black cross, meaning that they are stored in your JDeveloper workarea but are not yet committed to the Subversion repository. Files must be committed to the Subversion repository before they can be versioned and accessed by other users.

  3. To commit files to the Subversion repository, select the files in the Application Navigator and choose Versioning > Commit.

    The Commit Resources dialog is displayed with the files listed.

  4. Add your versioning comments in the Comments box.

    You will later be able to see these comments when viewing the list of versions of a particular file.

  5. To commit the files to the Subversion repository, click OK.

    The files are now shown in the Application Navigator with an orange dot, indicating that they are known to the Subversion repository and are up to date.

6.3.2.2 How to Use Change Sets

Change sets, or change lists, are essentially labels which can be applied to working copy files to enable group operation on each change list. The idea behind adding files to a change set is similar to sorting files into directories, but change lists can be created dynamically and the labels applied to each file, regardless of their level in the file system hierarchy. You can then address all the files in the change set as a single group. For example, if you make a single bug fix that requires editing three different files, you can add all three files to the change set and track them as a single logical unit in the JDeveloper Pending Changes window.

Subversion lets you associate files with a named change set, either manually or automatically. You make additions to the change set through the menu system; automatic additions are also possible through default association, when JDeveloper detects outgoing changes.

You can browse changes for a named change set in a view of the Pending Changes window. From there, you can manipulate the change sets, and commit associated changes to the repository.

To add a selected file to a new change set:

  • Select a file from the Pending Changes window, then select Versioning > Add To > New Change Set.

To add file to a change set:

  1. In the Pending Changes window, select a file to add to an existing change set and click the right mouse button.

  2. Select Add To, then choose an existing change set.

  3. Select one of the existing change sets displayed in the dialog, or select New Change Set to create a new change set containing this file.

  4. Click OK.

6.3.2.2.1 Editing Change Sets

JDeveloper creates a default, unnamed change set for each installed version control system, and uses this change set until you specify another change set as the default. You can make changes to the content and the status of individual change sets, including this default change set, by right-clicking any change set and selecting from the following:

Edit

Change the content of the selected change set.

Remove

Deletes the selected change set from Pending Changes. Does not delete the files associated with the change set.

Make Default

Makes the selected change set the default for future operations. All newly created and edited files will be made part of this change set until you either change the default or manually add the file to a different change set.

6.3.2.3 How to View the History of a File

Use this procedure to open the History Viewer and view the history of Subversion files.

To view the history of a file:

  • With the file selected in the Application Navigator, choose Versioning > Version History from the context menu.

    For more information while using the History Viewer, press F1 or click Help.

6.3.2.4 How to Commit Files to the Subversion Repository

Use these procedures to bring the Subversion repository up to date with the latest version of the files you have been working on, at the same time adding any new files to or removing any unwanted files from the Subversion repository.

You can perform the commit operation on individual files, or in the context of a working copy.

If an individual object that you want to commit has uncommitted parent objects, you must first commit the parent objects. An alternative is to commit the working copy that the objects are part of, in which case all the uncommitted objects will be committed.

You can also use change sets to manage groups of files, which can help ensure that you commit all files pertaining to a particular sub-project or task within the overall application.

To commit individual files shown in the Application Navigator or the Pending Changes window:

  • Select the file(s) and choose Versioning > Commit.

    The Commit Resources dialog is displayed with any files listed. Set the options on the Commit Resources dialog as required.

    To obtain more information about the options, press F1 or click Help. To commit the listed file or files to the Subversion repository, click OK.

To commit a working copy from the Application Navigator:

  1. Select a navigator node or file that is part of the working copy.

  2. Select Versioning > Commit Working Copy.

To obtain more information about the options, press F1 or click Help. To update the Subversion repository with the content of the working copy, click OK.

When you use Commit Working Copy, all the files in your checked out working copy will be updated, regardless of which node you have active in your application in the JDeveloper Application Navigator. The alternative is to select Commit. This will only commit the folder or file (and any child folders and files) that you have selected in the Application Navigator.

Additionally, you can commit a working copy from the Pending Changes window.

To commit a working copy from the Pending Changes window:

  1. Put the Pending Changes window into Outgoing Changes mode.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Select a file from the working copy that you wish to commit.

  3. Select Versioning > Commit Working Copy.

6.3.2.4.1 Saving Work Item ID with the Oracle Team Productivity Center Extension

If you are using Oracle Team Productivity Center, the work item ID will automatically be saved as a tag in the comment dialog when you commit.

6.3.2.5 How to Use Templates in Subversion

Many team environments require the developer to enter comments when a file is checked in. These comments might include bug report numbers, dependencies on other files, or some other explanatory information to be stored in connection with the file being committed to the repository.

JDeveloper lets you create and select templates for use with such comments. The templates are available from the Commit menu.

To create a new template:

  1. Select Tools > Preferences > Versioning > Subversion > Comment Templates.

  2. Click Add.

To select a template:

  1. Click Choose a template or previous comment.

  2. Select the template from the list.

  3. Click OK.

To make a comment to a file being committed:

  1. Click in the Comments box to select it.

  2. Type the comment you wish to make with the file being committed.

  3. Click OK.

6.3.2.6 How to Revert Files to their Previous State

Use the Revert command to:

  • Undo changes that you have made locally to the contents of a file.

  • Change the status of a file that has been added, but not yet committed, back to unadded.

  • Stop a file that is scheduled for removal (in the Pending Changes window) from being removed from the Subversion repository.

To revert a file:

  1. Select the file in the Application Navigator or Pending Changes window and choose Versioning > Revert.

    The Revert Local Changes dialog is displayed with the file or files listed.

    For help while using the dialog, press F1 or click Help.

  2. To revert the listed file or files, click OK.

6.3.2.7 How to Replace a File with the Subversion Base Revision

Use this procedure to replace a file with the base revision. The base revision is the revision from which the one you are currently working on originated.

To replace a file with the Subversion base revision:

  1. In the Application Navigator, select the file to be replaced.

  2. Choose File > Replace With Base Revision. The Replace With Base Revision dialog opens. Check that the file that you want to replace is shown in the dialog.

  3. To replace the file, click OK.

6.3.2.8 How to Compare Files in Subversion

Use these procedures to compare files that are under Subversion control with other revisions of the same files, or with other files.

To compare revisions of a file:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Revision, Latest Revision, or Other Revision.

    If there are no differences, a message is displayed. Otherwise the revision or revisions are shown in the Compare panel of the History tool.

To compare a file with another file:

  1. From the context menu for the file, choose Compare With > Other File.

    The Select File to Compare With dialog is opened.

  2. Select the file to be compared.

    The files are shown in the Compare panel of the History tool.

To compare two files:

  1. Select the two files in the Application Navigator.

  2. From the context menu for one of the files, choose Compare With > Each Other.

    The files are shown in the Compare panel of the History tool.

You can hide (and later expose) the Compare panel of the History tool to view other panels in JDeveloper.

6.3.2.9 How to Resolve Conflicts in File Versions

If there is a conflict between your copy of the file and the one in the Subversion repository, the icon next to the affected file will include an exclamation point. You will not be able to submit such a file to the Subversion repository. To overcome this problem, you should do one of the following:

  • Revert to a non-conflicting version of the file.

  • Resolve the conflict using the JDeveloper merge tool.

  • Indicate to the Subversion control system that the conflict has been resolved (Versioning > Mark Resolved), even if no changes have been made (usually necessary only for binary files).

Another reason you might need to do this is if you have resolved the conflict yourself in the file, rather than using the merge tool. This might be the case if you have chosen to merge files at the server rather than the more usual solution of merging files locally.

To revert to a non-conflicting file version:

  • Select the file in the Application Navigator and choose Versioning > Revert.

To resolve the conflicts using the merge tool:

  1. Select the file in the Application Navigator and choose Versioning > Resolve Conflicts.

    The file is opened with the Merge tab displayed, showing the merge tool.

  2. Use the merge tool to resolve the conflicts.

    For help while using the merge tool, press F1 or click Help.

To indicate that the conflict has been resolved, even if no changes have been made:

  • Select the file (usually a file with binary content) in the Application Navigator and choose Versioning > Mark Resolved.

6.3.2.10 How to Resolve Conflicts in Subversion

Use this procedure to merge two revisions of a file, where the revisions contain conflicting content. Conflicts are notified in the Pending Changes window: the outgoing status is "conflicts" or "conflicts on merge", and the Resolve Conflicts button is active.

To merge two revisions with conflicting content:

  1. On the Outgoing tab of the Pending Changes window, select the revision that has conflicts and click the Resolve Conflicts button. (You can also select the revision in the Application Navigator.)

  2. The merge tool is opened (as the Merge tab of the file editor).

    For help while using the merge tool, press F1 or click Help.

    The merge tool has three panels. The left panel contains the content of the version in the repository. The right panel contains the content of the most recent local version. The center panel contains the results of the merge. In the margins between the panels are symbols representing suggested actions to resolve each conflict.

  3. View the suggested actions for resolving the conflicts by reading the tooltip of the margin symbols.

    More suggested actions may be available from the context menus of the margin symbols.

  4. Resolve the conflicts by implementing a suggested action in each case.

    Accepting an initial suggested action may cause the appearance of additional suggested actions.

    You can also make changes to the content of the center panel by typing into it.

  5. To complete the merge, save the changes that have been made by clicking on the Save Changes button on the merge tool (not the JDeveloper Save option).

6.3.2.11 How to Resolve Property Conflicts in Subversion

Subversion allows you to create and save properties associated with folders or files. These properties have a name and a value string.

You can resolve any such conflicts using Subversion's Resolve Tree Conflicts feature.

To resolve Subversion property conflicts:

  1. In the Application Navigator, select the element under Subversion control that has a property conflict.

  2. Click the right mouse button, and then select Versioning > Resolve Tree Conflict.

This displays the versions with the conflicting properties in two adjacent panes, as with the Version Compare.

To resolve the conflict, you can make changes in the Subversion Properties window.

6.3.2.12 How to Use the Merge Wizard

The Merge Wizard is instrumental to the way that JDeveloper supports Subversion merge tracking. Merge tracking in Subversion means in essence that Subversion remembers your merges so you don't have to. The Merge Wizard provides you with an easy way of selecting which components you wish to merge, such as specific revisions, branches, or change sets.

The Merge Wizard gives you a number of options:

Merge Selected Revision Range

Select this when merging a range of revisions to another branch, for example, when you are back-porting a group of bug fixes to the release branch.

Reintegrate a branch

Normally used when merging the changes on a branch back to the trunk, for example, if you completed the work on a feature branch and want to reintegrate the changes back to trunk.

Merge two different trees

Select this to merge the differences between two branches into the working copy.

Block specific revisions from being merged

Select this if you know that specific revisions are not yet ready, or not appropriate, to be merged into the trunk.

6.3.2.13 How to Work with Branches and Tags

When you wish to work on files independently of the main line of development (the "trunk") you can create a branch. Using the same feature, you can also create a tag, a collection of files that captures the state of development at a particular point.

When you wish to put the work you have being doing on a branch back into the main line of development, you can start the process by using the merge revision facility. This will compare the content of two revisions and apply the differences to the current working copy. You can also use this facility whenever you wish to copy changes made in one revision to another revision.

You may want to change your working copy so that it is based on a different branch. You can do this using the switch feature, either as part of branch creation or independently.

To create a branch or tag:

  1. Ensure that you have committed your files to Subversion before continuing.

  2. In the Application Navigator, select a project or file that is in the line of development that you wish to branch or tag.

  3. Select Versioning >Branch/Tag.

  4. Complete the Branch/Tag dialog.

    For help when completing the dialog, press F1 or click Help.

To use the merge facility (that is, to compare two revisions and apply the results to the working copy):

  1. In the Application Navigator, select a project or file that is in the start revision (that is, the resource that is to be compared against).

  2. Select Versioning > Merge.

  3. Complete the Merge dialog.

    For help when completing the dialog, press F1 or click Help.

To switch the working copy to be based on another location in the repository:

  1. In the Application Navigator, select a project or file that is in the current working copy.

  2. Select Versioning > Switch.

  3. Complete the Switch dialog.

    For help when completing the dialog, press F1 or click Help.

6.3.2.14 How to Add and View Subversion Properties

Subversion lets you define and add properties to various levels of the elements in the Application Navigator: files, folders, and other resources. You can define these properties and use them as a way of tracking files or folders that have something in common. For example, you can associate a specific Subversion property with a newly added feature. Viewing all files or folders with this Subversion property lets you see all the files associated with this feature: an HTML file, a JavaScript file, a class definition file, or any other elements that are involved in adding this new feature to your application.

If your team has been using Subversion properties for some time, you can use the View Subversion Properties menu to see a list of all elements that use a selected Subversion property. You can also compare the Subversion properties between different versions.

To view a list of Subversion properties:

  1. Select an element under Subversion control from the Application Navigator.

  2. Select Versioning > Subversion > View Subversion Properties.

If your project needs a new property for tracking and managing a particular aspect (such as a new feature or a bug fix), you can also add new properties.

To add a new Subversion property:

  1. Select an element under Subversion control from the Application Navigator.

  2. Select Versioning > Subversion > Add Subversion Property.

  3. Enter the values for the property, then click OK. Refer to the following section for examples of Subversion properties and how to use them.

6.3.2.14.1 Example of Subversion Properties

When you add or edit Subversion properties, the dialog lets you select or specify the following elements:

Resource file

The file (or folder or other resource) to which this property is to be applied. To change this value, select a different file or resource. Note that if you wish to add this property at the application or project folder level, edit the resource file entry so that it refers to the folder, not the file.

Property name

Select a property name from the available list, or enter a new name to create a new Subversion property. Preface the new property name with svn: to be tracked as a Subversion property.

Value string

Enter the string to be displayed with this Subversion property when you view properties. For example, you can associate a specific Subversion property with a particular bug identification number or a specific upcoming release.

Note that the Value String might differ depending on the property. For instance, consider a property named svn:externals meant to record the connection between a local file and its external URL in the SVN repository. This property's value string would be a pair of text strings, respectively showing the local directory where the external file is to be checked out and the URL to the external file in the SVN repository

Assume for this example that the resource file is D:\temp and the property name is svn:externals. The value string (a value pair) might be:

external_libs https://ukp16449.uk.oracle.com/repos/trunk/FOD/StoreFront.jar

This indicates that the file StoreFront.jar held in the Subversion repository at that URL is to be checked out to D:\temp\external_libs. If the Value String entries were held in a specific file pointed to from this property, use the Value File entry.

Value file

If you know you will be adding the same Subversion property to a number of resources in your application, you can save the value string in a text file. Click Browse to select the text file that contains the value string you wish to use.

Set property recursively

Select this if you wish Subversion to apply this property to all files and elements below the current level in the application or project hierarchy.

6.3.2.14.2 Specifying a Revision Number with a Subversion External Property

When you set an external property with a revision number, make sure you follow the correct format for the value string. You can use either of the following as the value string for a property of type svn:external to set the ExternalWebINF revision to 16, using the JDeveloper integrated Subversion:

ExternalWebINF -r 16 https://myserver.myteam.com/svn/repos/public-html/WEB-INFhttps://myserver.myteam.com/svn/repos/public-html/WEB-INF@16 ExternalWebInf

However, note that with Subversion 1.4 clients, only the first format is accepted.

6.3.2.15 How to View the Status of a Subversion File

Use this procedure to check the content status and any associated property status of a file that is under Subversion source control. You can also refresh the status of a file.

To view the status of a file:

  1. With the file selected in the Application Navigator, open the context menu and select Versioning > Properties.

  2. Select the Versioning tab.

The status labels shown are those used by Subversion to describe the source control status of content and any associated property.

The main statuses for content are:

  • added - The content has been added to source control but has not yet been committed to the Subversion repository.

  • modified - The property has been locally modified since it was copied from the repository.

  • unmodified (normal) - The property is unmodified since it was last updated from the Subversion repository.

  • conflicted - There were conflicts when the property was updated from the Subversion repository.

  • deleted - The file (content and any associated property) will be removed from the Subversion repository with the next commit action.

The main statuses for associated properties are:

  • modified - The property has been locally modified since it was copied from the repository.

  • unmodified (normal) - The property is unmodified since it was last updated from the Subversion repository.

  • conflicted - There were conflicts when the property was updated from the Subversion repository.

6.3.2.16 How to Refresh the Status of Files Under Subversion Control

The source control status of a file is indicated in the JDeveloper navigators (Application Navigator and Team Navigator) by icon overlays, as below.

If the status of a file is changed outside JDeveloper, for example by using a Subversion client application, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the navigator matches the true status of the file in the source control system, you can perform a manual refresh.

To refresh the status of files in JDeveloper:

  • Select View > Refresh.

6.3.2.17 How to Remove Files from Subversion Control

If you wish to remove a file from Subversion control, use the JDeveloper Delete feature. This performs a "safe delete," which searches for usages of the file you are deleting and provides you with a dialog with options for proceeding.

To remove a file from Subversion control:

  1. In the Application Navigator, select the file to be removed from Subversion.

  2. Select Edit > Delete (or right-click the file and select Delete).

  3. Make sure that Delete Safely is selected.

  4. Click OK.

    If JDeveloper finds usages of the file you are deleting, a dialog will offer you options for proceeding. Choose the appropriate option, then click OK.

6.3.3 How to Use Export Features

Subversion provides features for creating and applying patches—methods for determining changes between two revisions of a file, and then applying those changes to a third file. In addition, Subversion contains features for exporting the details about repository connections, as well as files in the repository.

6.3.3.1 How to Create and Apply Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

    The Select Patch Context dialog may open. For help while using this dialog, press F1 or click Help.

    The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1 or click Help.

To apply a patch:

  1. In the navigator, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Versioning > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1 or click Help.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1 or click Help.

  6. To apply the patch, click OK.

6.3.3.2 How to Export Subversion Controlled Files from JDeveloper

You can export copies of JDeveloper files that are under Subversion control. You can do this from the Application Navigator, in which case the files will be exported from the Subversion "working copy", or from the Subversion Navigator, in which case the files will be exported from the Subversion repository. If you export using the Subversion Navigator, you can specify which revision of the files to export. Exporting the files means copying them to a local file system directory that you specify.

To export files from the Subversion "working copy":

  1. In the Application Navigator, select the project containing the files that you wish to export.

  2. Select Versioning > Export Files.

    An Export Files dialog opens.

  3. In the Destination Path box, enter or browse to the location where you want the files to be copied to.

  4. To export the files, click OK.

To export files from the Subversion repository:

  1. In the Subversion Navigator, select the repository node or directory containing the files that you wish to export.

  2. Select Versioning > Export Files.

    An Export Files dialog opens.

  3. In the Destination Path box, enter or browse to the location where you want the files to be copied to.

  4. If you want to export a particular revision of the files, select Use Revision and enter the revision number in the adjacent text box.

  5. To export the files, click OK.

6.3.3.3 How to Export and Import Subversion Repository Connection Details

You can export the details of your Subversion repository connections to a file. You can subsequently import the connection details from the file to recreate the Subversion repository connections.

To export Subversion connection details to a file:

  1. In the Subversion Navigator, select the Subversion node and, from the context menu, choose Export Connections.

    The Export Subversion Connections dialog opens.

  2. Enter a location and name for the file that will contain the connection details, then click OK.

To import Subversion connection details from a file:

  1. In the Subversion Navigator, select the Subversion node and, from the context menu, choose Import Connections.

    The Import Subversion Connections dialog opens.

  2. Browse to the file that contains the connection details that you wish to import, then click OK.

6.4 Using Concurrent Version System (CVS) with Oracle JDeveloper

JDeveloper allows you to use the source control features of Concurrent Versions Support (CVS). Once you have installed the CVS extension, JDeveloper works in a seamless manner with CVS so that you can connect to the CVS repository, check out files, work on them and commit changes, all from within the JDeveloper navigators and menus.

Note:

For extensive information about how to use and administer CVS, see the CVS online manual at http://www.cvshome.org.

6.4.1 How to Set Up CVS with Oracle JDeveloper

In general, CVS uses a common repository of files, accessible to JDeveloper, that you and your team share while developing a software project. To modify files in that repository, you first check them out so that CVS tracks the who, when, and what of file access. In the event that two team members edit the same file at the same time, CVS contains tools that help you determine whether those changes conflict, and to resolve problems that may arise and merge these simultaneous changes into a single, comprehensive file. Finally, CVS lets you check these changed files back into the repository so that your build tools will have access to the latest files, with new and/or merged content.

Before you can use CVS to manage your shared content, you need to connect JDeveloper to CVS. This means configuring JDeveloper, making a connection to your team's CVS repository, creating a local repository, and more. The topics in this section cover all the steps you'll need to make sure CVS is available from JDeveloper after downloading the CVS extension from Check For Updates. If your team is already using CVS, you should check with them for specifics on how CVS is implemented in your organization.

The process of setting up CVS with JDeveloper involves configuring JDeveloper, creating a CVS connection, importing files for the project into your CVS repository, and then checking out the CVS modules to be edited.

6.4.1.1 How to Configure JDeveloper for Use with CVS

Before you can use CVS, you need to configure JDeveloper by setting preferences.

To configure JDeveloper for use with CVS:

  1. Choose Tools > Preferences, then select Extensions from the left panel of the Preferences dialog.

  2. In the right panel, ensure that Versioning Support n.n is checked.

  3. In the left panel of the Preferences dialog, open the Versioning node and then the CVS node. The main CVS preferences panel is shown. Other CVS preferences panels are shown when you click on the items beneath the CVS node.

  4. Make changes to the preferences as required. For more information about the specific preferences, press F1 or click Help.

  5. If you wish to use binary file types with CVS, select the File Types node in the right panel, and use the File Types page to create the binary file types that you want to use with CVS.

    For help while using this page, press F1 or click Help.

  6. Click OK to close the Preferences dialog.

To select CVS as the versioning system:

  • Choose Versioning > Version System: [...] > CVS.

After you have configured JDeveloper and selected CVS as the versioning system of course, you are ready to make the connection to CVS so that you can view and access files in the CVS repository

6.4.1.2 How to Create a CVS Connection

Before you can work with a CVS repository through JDeveloper, you must create a connection to it. When you create a local CVS repository, you can choose to create a connection to the repository automatically

CVS connections are shown in the CVS Navigator. You can subsequently edit the connection details.

To create a CVS connection:

  1. In the CVS Navigator (View > CVS Navigator) right-click the CVS node and choose New CVS Connection.

    The Create CVS Connection wizard is opened.

  2. Complete the Create CVS Connection wizard.

    For help when using the wizard, press F1 or click Help.

To edit a CVS connection:

  1. In the CVS Navigator (View > CVS Navigator) right-click the connection name and choose Properties.

    The Edit CVS Connection wizard is opened.

  2. Use the wizard to make changes as required.

    For help when using this wizard, press F1 or click Help.

6.4.1.3 How To Import JDeveloper Project Files Into CVS

Before you can start using your JDeveloper project with CVS, you have to import the project files into the CVS repository. This copies all your folders and files to the CVS repository and places them under source control.

You import your project files into the CVS repository using the Import to CVS wizard.

To use the Import to CVS wizard:

  1. Choose Versioning > Import Module. The Import to CVS wizard is displayed.

  2. Complete the import as prompted by the wizard. For help when using this wizard, press F1 or click Help.

Before you can change any files, you have to copy them back to your machine, where you can work on them locally.

6.4.1.4 How to Check Out CVS Modules

This is a configuration task you perform when you first start to use JDeveloper with files and folders that are under CVS source control. You perform this task once, after (if necessary) importing your JDeveloper project into the CVS repository.

To check out modules from the CVS repository:

  1. In the CVS Navigator, select the CVS module that you want to check out.

    Either:

    Choose Versioning > CVS > Check Out Module.

    or:

    from the context menu, select Check Out Module.

    The Check Out from CVS dialog is displayed.

  2. Complete the dialog. For help when using this dialog, press F1 or click Help.

6.4.2 How to Configure CVS For Use with JDeveloper

In addition to setting up JDeveloper to be able to use CVS, there are certain tasks you need to perform to make CVS usable with JDeveloper. Some of these tasks may be performed by your administrator. You should always check to make sure which of these tasks have been performed in your installation.

In general, you need a local CVS repository for storing files as you are working on them. You may also need to configure a secure shell (SSH) for communicating with CVS, and you may need to choose a character set. Finally, you will need to log in to CVS.

6.4.2.1 How to Create a Local CVS Repository

From within JDeveloper, you can create a new CVS repository on your local file system. This feature is available only if you are using external CVS client software, rather than the internal CVS client installed as part of the CVS extension to JDeveloper.

To create a local CVS repository:

  1. Select Versioning > Create Local Repository.

  2. In the Repository Folder box, enter the path of a directory where you want the new local repository to be created.

    You can specify or select an existing directory if it is empty, or you can specify a new directory. If the directory you have specified exists and is not empty, you will see a warning dialog telling you to specify an empty or new directory for the repository.

  3. If you want to create a connection to the local repository that you are creating, make sure that the Create Repository Connection box is checked.

    The connection will be given a name in the form :local:{path}. If you later want to change this name, you can do so through the CVS Navigator: from the context menu of the connection name, open the properties dialog and, on the Name tab, overtype the existing name with a new one.

  4. Click OK. You will see a confirmation dialog when the new local repository has been created.

6.4.2.2 How to Configure SSH (Secure Shell), CVS and JDeveloper

JDeveloper supports SSH Levels 1 and 2 as access methods for CVS repositories.

6.4.2.2.1 Configuring for SSH Level 1 (SSH)

JDeveloper does not provide a direct way of using SSH Level 1 as an access method for the CVS repository. It is however possible to configure SSH Level 1 so that it can be used for remote shell access.

To configure SSH Level 1 to enable remote shell access:

  1. Generate public and private keys using the command: ssh-keygen

  2. Concatenate the ~/.ssh/identity.pub public key file with ~/.ssh/authorized_keys on the machine with the CVS repository.

Before running JDeveloper and attempting to use CVS with SSH Level 1, users should be explicitly authorized and the environment correctly configured. Follow the steps below to configure the environment correctly.

To configure the environment for SSH Level 1:

  1. Set the CVS_RSH environment variable to the location of the SSH client.

  2. At the UNIX command line, enter ssh-agent {shell}, and then press Enter.

  3. At the UNIX command line, enter ssh-add, and then press Enter.

  4. Start JDeveloper.

  5. Select External as the CVS access method when using the CVS Connection Wizard.

6.4.2.2.2 Configuring for SSH Level 2 (SSH2)

JDeveloper provides a direct way of using SSH2 as an access method for the CVS repository.

To use SSH2 for remote shell access:

  1. On the JDeveloper CVS preferences page, set the CVS Client preference to Internal to JDeveloper [...].

  2. Start the CVS Connection Wizard.

  3. While using the CVS Connection Wizard, on the Connection page, choose Secure Shell via SSH2 as the Access Method. For more help at this stage, press F1 or click Help.

  4. On the Connection page, click Generate SSH2 Key Pair. This opens the Generate SSH2 Key Pair dialog. For help using this dialog, press F1 or click Help.

  5. After generating the SSH2 key files, an information dialog will appear that explains where to install the files.

  6. Install the SSH2 key files as instructed in the dialog.

  7. Complete the CVS Connection Wizard to create the CVS connection.

If you are using an internal CVS client, you can generate SSH2 key files at any time by choosing Versioning > Administration > Generate SSH2 Key Pair. If you are using an external CVS client, this menu option is unavailable.

6.4.2.3 How to Choose a Character Set (Local Client Only)

If your installation uses a local CVS client, you need to choose a character set.

For each CVS repository connection, you can choose the character set to be used for the encoding of files. The default is to use the character set specified by the platform/operating system.

You can change to the IDE default or to a specific character set through the Set Encoding dialog.

To choose a character set:

  1. Select a connection in the CVS Navigator.

  2. Clicking the right mouse button and choose Set Encoding.

  3. Select the desired character set.

6.4.2.4 How to Log In to CVS

Some types of connection to a CVS repository require you to log in independently of making the connection. If you cannot access any CVS features even though a CVS connection exists, you need to log in.

To log in to a CVS repository:

  1. In the CVS Navigator, select Versioning > Log In.

    If the Log In menu option is unavailable but the Log Out option is available, you are already logged in.

  2. In the Log In To CVS dialog, enter your password. If you want your password to be remembered and supplied automatically when you connect to the CVS repository in future, check the Connect Automatically on Startup box.

  3. Complete login by clicking OK.

6.4.2.5 How to Access Local Files with CVS

If JDeveloper finds a path to a CVS client on your machine, the JDeveloper CVS preferences will by default be set to use that CVS client (rather than the internal CVS client installed with JDeveloper). If no path to a CVS client is found, the preferences will be set to use the internal CVS client.

The internal CVS client cannot be used to access a local CVS repository (that is, one on your own machine). If you wish to access a local CVS repository, you must install a full client/server version of CVS onto your machine and set the JDeveloper CVS preferences accordingly.

If you wish to use an external CVS client, we recommend the following:

  • CVSNT 2.0.58a for Windows platforms

  • cvshome's CVS 1.11.9 for other platforms

Note:

You may already have a CVS installation that is client-only. This will not be able to access a local CVS repository, and you should install a full client/server version instead. If you are unable to expand the connections node in the CVS Navigator or open the list of modules from the Get Module List button in the CVS wizards, you probably have client-only CVS software that is attempting to access a local CVS repository. You can check which type of CVS installation you have by typing cvs -v at the CVS command prompt. A client-only installation will display (client) at the end of the version information line, whereas a client/server installation will display (client/server).

To access CVS through a firewall:

If you are accessing a CVS server through a firewall, you can connect to it if:

  • the firewall allows TCP/IP communication on the CVS port, or

  • you use a CVS client that supports HTTP Tunneling (for example, CVSNT).

If there is an authentication failure when you log in, try using the CVS command line to connect. If this fails, the connection may be being blocked by the firewall, and you should contact your network administrator.

If necessary, you can alter the value of the CVS root variable to support connection through a firewall.

6.4.2.5.1 Handling CVS File Types

The CVS administrator has to configure the CVS repository for the automatic handling of binary files produced by JDeveloper, such as image file formats.

Where other file types are updated, CVS attempts to merge them. If you do not want is to occur, you must change the configuration of the CVS repository.

For more information about CVS, refer to the CVS documentation, or see the CVS website, http://www.cvshome.org. This is also where you can download CVS software.

6.4.3 How to Use CVS After Configuration

Once JDeveloper is configured and your project files are available in the CVS repository, you will most likely use a workflow that follows the basic sequence of update, checkout, modify, and commit. In addition, you may occasionally need to resolve edit conflicts, and merge the resulting file(s) into the repository.

6.4.3.1 How to Update a Project, Folder, or File in CVS

The CVS update operation updates your local files with data in the CVS repository. Alternately, you can choose to completely replace your local files with those held in the CVS repository.

You can update individual files (including project files), or you can update the entire contents of a project folder.

You can view the contents of the CVS repository through the CVS Navigator. The nodes under CVS Server unfold to reveal the structure and file content of the CVS repository. You can open a read-only version of a CVS repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the CVS repository since you checked out or last committed your local versions.

To update an individual file (including a project file):

  1. Select the file(s) in the Application Navigator, and then choose Versioning > Update.

  2. Set the options as required. For information about these options, press F1 or click Help.

  3. To update all the files listed, click OK.

To update the contents of a project folder:

  1. Select the project folder(s) in the Application Navigator and then, from the context menu, choose Update Project Folders.

  2. Set the options as required. For information about these options, press F1 or click Help.

  3. To update all the files listed, click OK.

To update files shown in the Pending Changes window:

  1. With the Pending Changes window in Incoming Changes mode, select the files that you want to update.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Update button.

6.4.3.2 How to Edit and Watch Files in CVS

Editing and watching are available only when an external CVS client executable is used.

These procedures allow you to obtain and release an editor on a file, to know who else in your team is editing files, and to know who is watching for files to be edited. Two or more developers retain the ability to edit the same file at the same time.

To set up JDeveloper to use editing and watching:

  1. Open the preferences page obtainable from Tools > Preferences | Versioning | CVS.

  2. Ensure that External Executable is selected and that valid details are entered.

  3. Select Run CVS in Edit/Watch Mode.

  4. Open the preferences page obtainable from Tools > Preferences | Versioning | CVS | General.

  5. Deselect Automatically Make Files Editable.

To obtain an editor on a file:

  1. With the file selected in the Application Navigator, select Versioning > Edit.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. To set up a watch for this file, select the Set Watch Actions checkbox and select a watch action from the drop-down list.

  4. Click OK.

To release an editor on a file (to unedit a file):

This action reverses changes made in the current edit. Any local file modifications will be lost when the editor is released.

  1. With the file selected in the Application Navigator, select Versioning > Unedit.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

To turn on or turn off the file watching facility:

  1. In the Application Navigator, select a project containing files about which you want to be notified.

  2. Select Versioning > Watch.

  3. In the Watch CVS Files dialog, choose Turn On Watching or Turn Off Watching from the Command Type drop-down list.

  4. Click OK.

To add yourself to the list of people who receive notification of work done on files:

  1. In the Application Navigator, select the project containing the files about which you want to be notified.

  2. Select Versioning > Watch.

  3. Check that you want the operation to apply to all of the files in the file selection box.

  4. On the Watch Settings tab, choose Add File Watch as the Command Type from the drop-down list.

  5. Optionally, check the Set Watch Actions checkbox and choose the particular actions that you want to be notified about.

  6. Click OK.

To remove yourself from the list of people that receive notification of work done on files:

  • Follow the procedure for adding yourself to the list (above), but choose Remove File Watch from the Command Type dropdown list.

To see who is watching for changes being made to files:

  • Select Versioning > Edit Notifications.

The Edit Notifications window is opened. The Watchers tab shows the files that are being watched and the user(s) who are currently watching for changes.

To see who is currently editing files:

  • Select Versioning > Edit Notifications.

The Edit Notifications window is opened. The Editors tab shows the files that currently have editors on them and the user(s) who have obtained those editors.

6.4.3.3 How to Commit Changes to CVS

Use these procedures to update the CVS repository with the latest version of the files you have been working on, and to add any new files to or remove any unwanted files from the CVS repository.

You can perform this on a single file, or in the context of a project. When in the context of a project, JDeveloper determines which files have changed since they were last committed and displays them as a list.

If you select a project to be committed that includes files that are not yet part of CVS version control, the Add Files to CVS message dialog will open. To obtain information about using this dialog, press F1.

You can view the current contents of the CVS repository through the CVS Navigator. The nodes under CVS unfold to reveal the structure and file content of the CVS repository. You can open a read-only version of a CVS repository file by choosing Open from its context menu. This will let you see what changes have been made to the files in the CVS repository since you checked out or updated your local versions.

To commit individual files shown in the Application Navigator:

  1. Select the file(s) in the Application Navigator, and then choose Versioning > Commit.

    The Commit to CVS dialog is displayed with the file(s) listed.

  2. Set the options on the Commit to CVS dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) in the CVS repository, click OK.

To commit the contents of project folders shown in the Application Navigator:

  1. Select the project folder(s) in the Application Navigator and, from the context menu, choose Versioning > Commit Project Folders.

    If there are files in the project that are not under CVS control, you will be asked whether you want to add them.

    The Commit to CVS dialog is displayed with the folder(s) listed.

  2. Set the options on the Commit to CVS dialog as required.

    To obtain more information about the options, press F1 or click Help.

  3. To update the listed file(s) in the CVS repository, click OK.

To commit files shown in the Pending Changes window:

  1. With the Pending Changes window in Outgoing Changes mode, select the files that you want to commit.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Commit button.

6.4.3.4 How to Merge Files in CVS

Use this procedure to merge two revisions of a file, where the revisions contain conflicting content. Conflicts are notified in the Pending Changes window: the outgoing status is "conflicts" or "conflicts on merge", and the Resolve Conflicts button is active.

To merge two revisions with conflicting content:

  1. On the Outgoing tab of the Pending Changes window, select the revision that has conflicts and click the Resolve Conflicts button.

  2. The merge tool is opened (as the Merge tab of the file editor).

    For help while using the merge tool, press F1.

    The merge tool has three panels. The left panel contains the content of the version in the repository. The right panel contains the content of the most recent local version. The center panel contains the results of the merge. In the margins between the panels are symbols representing suggested actions to resolve each conflict.

  3. View the suggested actions for resolving the conflicts by reading the tooltip of the margin symbols.

    More suggested actions may be available from the context menus of the margin symbols.

  4. Resolve the conflicts by implementing a suggested action in each case.

    Accepting an initial suggested action may cause the appearance of additional suggested actions.

    You can also make changes to the content of the center panel by typing into it.

  5. To complete the merge, save the changes that have been made, using the Save button.

6.4.4 How to Work with Branches in CVS

CVS lets you define branches, used when development needs to be carried out separately from the main (or trunk) branch of a project. JDeveloper gives you access to CVS branches in your repository through the Tag, Branch and Merge menu.

In CVS, you can create a separate branch when you want to carry out specific work (such as bug fixes or specialized feature development) without any impact to the main set of files, also called the trunk.

Once you have created a branch, you interact with it as normally with CVS -- check out files, commit changes, etc. You can switch back and forth between branches, and you can merge the changes you have made to your branch back into the trunk.

CVS also lets you apply tags to specific branches, or to specific files in a branch (as well as generating a new tag for the branch you create, when you create it).

6.4.4.1 How to Create a New Branch

You create a new branch when you are beginning a project based on an earlier version of your code repository, such as for fixing bugs after a major release, or working on specific features for a subset of your customers.

To create a new branch:

  1. In the CVS repository, select the file or folder on which you wish to base your new branch, then click the right mouse button.

  2. Choose Branch > Branch in CVS.

  3. Type in the branch name. JDeveloper converts the branch name to the default tag for the branch, by appending _BASE to the branch name as you type it.

  4. Choose whether the branch source is the trunk or the working copy. If you select the trunk, the HEAD revision of every file is branched.

  5. Click Save.

The base tag is applied before the branch is created, allowing you to specify these versions as a merge point in future.

You can also specify that you wish to create your new branch from an existing branch, by choosing the branch to use as the base.

To create a new branch from an existing branch:

  1. Click Details.

  2. Select the desired branch from the list of existing branches.

6.4.4.2 How to Use Branches in CVS

Branch selection is integrated into a number of CVS functions. You can switch branches or versions for files you are editing or have checked out; you can choose tags, branches, or version dates while updating the contents of your work area, as well as while you are checking out a CVS module.

6.4.4.2.1 How to Switch the Branch or Version

You can switch the branch or version of a file you are editing, either from the JDeveloper Versioning menu or from the file or project's context menu.

To select a branch, version or date from the Versioning menu:

  1. From the Versioning menu, choose Tag, Branch or Merge > Switch Branch or Version.

  2. Click the chooser to display a list of branches or versions.

  3. Select the branch or version you wish to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Click OK.

To select a branch, version or date from the project's context menu:

  1. Choose Versioning > Switch Branch or Version.

  2. Click the chooser to display a list of branches or versions.

  3. Select the branch or version you wish to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Click OK.

6.4.4.2.2 How to Choose a Branch while Updating

When you are updating your content to capture the latest revisions to the repository, you have the option of branch (via its associated tag) at the same time.

To select a tag and branch while updating:

  1. From the project's context menu, choose Update Project Folders.

  2. In the Update from CVS dialog, check the box marked Use Revision, Tag or Date, then click the chooser icon.

  3. Select a tag to use.

  4. Optionally, click Add Date to specify a date to use.

  5. Check any other boxes (Overwrite Local Changes, Prune Empty Folders, etc.) that you wish to apply to the current update, then click OK.

6.4.4.2.3 How to Choose a Branch While Checking Out

As with other CVS operations, tags and branches are integrated into the process of checking out a CVS module.

To choose a branch while checking out:

  1. Click the right mouse button on the content in the Versioning Navigator to bring up the context menu, then choose Check Out Module.

  2. Check the box labeled Use Revision, Tag or Date, then click the chooser to select a tag.

  3. Select a tag. Optionally, you can click the Add Date button to specify a date. When you have made your selection, click OK to close the Tags dialog.

  4. Choose any other options (Force Match, Ignore Child Folders, etc.), then click OK to close the Check Out from CVS dialog.

6.4.4.3 How to use Tags in CVS

Tags are a way of identifying branches, branch-specific content, or other content that you wish to identify and manipulate as a single logical group. You can tag files, folders, or projects. You can then later use these tags to identify branches, update files from a branch with a specific tag, and other operations.

You can select and browse tags from context menus as well as the Versioning > CVS > Tags menu. The availability of tags differs depending on the context of the operations you are performing on your content.

6.4.4.3.1 How to Add a Tag to a Project

You can identify a project by adding a tag to it. You can then operate on this project by selecting the tag from any of the CVS menus that contain the tag chooser.

To add a tag to a project:

  1. Select the project you want to tag.

  2. Choose Versioning > CVS > Tag, Branch and Merge > Tag.

  3. Type the tag you want to use, or click the chooser icon to browse the existing tags.

  4. Optional: Choose Use Revision, Tag or Date, then type the tag or click the icon to browse the list.

6.4.4.3.2 How to Apply Tags While Updating a Project or File

You can choose and apply a tag while using the Update from CVS dialog.

To select an existing branch, version or date from the Projects view:

  1. From the project's context menu, select Versioning > Tag.

  2. Choose Use Revision, Tag or Date.

  3. Click the tag chooser icon.

  4. Choose a tag from the list that appears.

6.4.4.3.3 How to Delete a Tag

You can also delete a tag. Deleting a tag removes it from any resources to which you have applied it. Deleting the tag does not delete the content to which the tag was applied; it merely removes it from the list of available tags.

To delete a tag:

  1. Select Versioning > Tag, Branch and Merge > Delete Tag.

  2. Click the chooser icon. Choose the tag you wish to delete, then click OK.

In this context, only existing tag versions (regular non-branch tags) can be selected.

6.4.5 How to Work with Files in CVS

As a very general rule, working with files in CVS means checking out the latest version of a file, making your edits, and checking the file in with your changes. Occasionally, if you and a colleague have made edits to the same file, you may need to merge your changes to make sure your work is not lost. Other functions of CVS are also available, such as adding a new file or removing unused/obsolete files from the repository, but your general workflow will follow the checkout-edit-checkin pattern.

The file operations in CVS include refreshing the display of CS objects, adding and removing files, using templates, comparing files, replacing a file in CVS, viewing the history and status of a file, locking and unlocking files, and working with revisions and tags.

6.4.5.1 How to Refresh the Display of CVS Objects

The source control status of an object is indicated in the Application Navigator by an icon overlay, as listed in Table 6-1.

Table 6-1 CVS Object Status

Icon Description

Added icon

The object has been copied from the CVS repository and added to your working files directory.

Not added icon

The object is not under CVS source control, but may be added to the CVS repository.

Conflicts icon

There were conflicts when the object (a file) was updated from the CVS repository. In this case, you have to manually edit the file to resolve all the points of conflict.

Scheduled for removal

The object has been scheduled for removal from the CVS repository with the next commit action.

Modified

The object is out of synch with the CVS repository due to local or remote changes.

Unmodified

The object is unmodified since it was last copied from the CVS repository.

Unmodified read-only

The object is unmodified since it was last copied from the CVS repository but is read-only.

Sandbox

The package or node is a CVS sandbox folder.

COnfused composite

The apparent object may comprise several underlying objects, the statuses of which may not all be identical.


If the status of an object is changed outside JDeveloper, for example by checking in an object using external source control software, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Application Navigator matches the true status of the object in the source control system, you can perform a manual refresh.

To refresh the status of objects in JDeveloper:

  • In the Application Navigator or CVS Navigator, click the refresh button.

6.4.5.2 How to Add and Remove Files

You can add a file to CVS only if it is part of a project that is already under CVS version control.

When you create a new file, for example a new class, it has to be added to source control before you can use the other CVS operations on it. The file is added to source control locally, and the CVS repository is not updated. The file is identified in the Application Navigator by the icon +.

To add a file to CVS through the Application Navigator:

  1. Select the file in the Application Navigator and choose Versioning > Add (or, if the file is binary, Versioning > Add as Binary). JDeveloper usually recognizes binary files and adds (Binary) after the file name in the navigator. The Add to CVS dialog (or Add to CVS as Binary dialog) is displayed, with the file listed.

  2. Click OK.

    The file will be added to the CVS repository when the next commit is performed.

To add files shown in the Pending Changes window:

  1. With the Pending Changes window in Candidate Files mode, select the files that you want to add to source control.

    To obtain more information about the Pending Changes window, press F1 or click Help.

  2. Click the Add button.

To remove a file from CVS:

When you remove a file from CVS it is removed from your local disk.

  1. In the Application Navigator, select one or more files to be removed, then choose Versioning > Remove.

  2. The Remove from CVS dialog is displayed with the files listed.

  3. Click OK.

The file or files will be removed from the CVS repository when the next commit is performed.

6.4.5.3 How to Use CVS Templates

Many team environments require the developer to enter comments when a file is checked in. These comments might include bug report numbers, dependencies on other files, or some other explanatory information to be stored in connection with the file being committed to the repository.

JDeveloper lets you create and select templates for use with such comments. The templates are available from the Commit menu.

To create a new template:

  1. Select Tools > Preferences > Versioning > CVS > Comment Templates.

  2. Click Add.

To select a template:

  1. Click on Choose a template or previous comment.

  2. Select the template from the list.

  3. Click OK.

To make a comment to a file being committed:

  1. Click in the Comments box to select it.

  2. Type the comment you wish to make with the file being committed.

  3. Click OK.

6.4.5.4 How to Compare Files in CVS

Use these procedures to compare revisions of files that are under CVS source control. You can compare a file with its immediate predecessor, or you can compare with any of the file's previous revisions.

To compare a file shown in the Application Navigator:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Revision, Head Revision or Other Revision.

  3. If you are comparing with previous revisions, these are listed in the Compare CVS File dialog: Select the file that you want to compare with.

    If there are no differences, a message is displayed. Otherwise the Compare tool is displayed.

To compare a file shown in the Pending Changes window:

You can compare a file in the Pending Changes window either with a previous revision or with the HEAD revision, depending on which mode the window is in. To obtain more information when using the Pending Changes window, press F1.

  • With the window in Outgoing Changes mode, select the file to be compared, then select the Compare with Previous Revision button.

  • With the window in Incoming Changes mode, select the file to be compared, then select the Compare with Head Revision button.

If there are no differences, a message is displayed. Otherwise the Compare tool is displayed.

6.4.5.5 How to Replace a File with a CVS Revision

Use this procedure to replace a file with the base or head revision, or with a file with a specific revision number or tag. The head revision is the latest one. The base revision is the revision from which the one you are currently working on originated.

To replace a file with a CVS revision:

  1. In the navigator, select the file to be replaced.

  2. Do one of the following:

    • To replace with the base revision, choose File > Replace With > Base Revision. The Replace With Base Revision dialog opens.

    • To replace with a specific revision number or tag, choose File > Replace With > Tagged Revision. The Replace With Tagged Revision dialog opens.

    • To replace with the head revision, choose File > Replace With > Head Revision. The Replace With Head Revision dialog opens.

  3. Check that the file that you want to replace is shown in the dialog.

  4. When replacing with a specific revision number or tag, enter the revision number or tag into the text box on the dialog.

  5. To replace the file, click OK.

6.4.5.6 How to View the History and Status of a File

The history and status of a file will tell you what has been done to it, and what has been done to it last. This can help you make the determination of what you need to do to bring the file up to date, or to begin making your own modifications.

Use this procedure to open the History Viewer and view the history of CVS files.

To view the history of a project or file:

  • With the project or file selected in the Application Navigator, choose Versioning > Version History from the context menu.

    For more information while using the History Viewer, press F1.

Use this procedure to check the status of a file that is under CVS source control. You can also refresh the status of files under CVS control.

To view the status of a file:

  1. With the file selected in the Application Navigator, open the context menu and select Versioning > Properties.

  2. Select the Versioning tab. The status of the file is the first item on the tab.

Possible statuses are:

  • Changed locally - the file has been locally modified since it was copied from the repository.

  • Changed in repository - the file has been modified by another user since it was copied from the repository.

  • Locally removed - the file will be removed during the next commit.

  • Locally added - the file will be added during the next commit.

  • Up-to-date - the file is up-to-date with the latest CVS repository revision.

  • File has conflicts - these may have resulted from a file update or commit action. If necessary, consult your CVS administrator for assistance.

  • Needs merge or needs patch - the file has been updated externally, for example, by another user.

  • Modified - the file previously had merge conflicts, but the timestamp has changed since.

6.4.5.7 How to Lock and Unlock Files

Note:

The locking of files is not supported in newer releases of CVS client software and this facility may be removed in future releases of JDeveloper.

You can choose to prevent other users working on a file while you are working on it yourself. This is not normally considered necessary, because CVS can usually reconcile differing versions of files as they are being committed to the CVS repository. The JDeveloper compare and merge facilities will reconcile differing versions of files automatically, or present you with a tool for doing so manually if there are serious conflicts.

You may want to ensure that a file is worked on only by you, until you have finished working on it. This might be because a file is in binary format and therefore inherently difficult to merge. In this case, you can lock the file that you want to work on. The file is locked in the CVS repository, and other users are prevented from accessing it. When you want to let others work on the file, you unlock it.

To lock files in CVS:

  1. With the file or files that you want to lock selected in the Application Navigator, choose Versioning > CVS> Administration > Lock.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

To unlock files in CVS:

  1. With the file or files that you want to lock selected in the Application Navigator, choose Versioning > CVS> Administration > Unlock.

  2. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  3. Click OK.

6.4.5.8 How to Work with Revisions and Tags

These procedures allow you to work with revisions and tags.

To open a CVS file revision:

This procedure will obtain a revision of a file from the CVS repository so that you can view it or save it locally.

  1. With the file selected in the Application Navigator, choose Versioning > Open Revision.

  2. Set the options on the dialog as required. To obtain descriptions of the options, press F1 or click Help.

  3. Click OK.

To assign CVS tags:

This procedure will assign symbolic tags to the local CVS revisions of selected files.

  1. In the Application Navigator, select a single file, a project or a workspace. If you select a project or a workspace, all the files within the project or workspace will be selected for tagging.

  2. Choose Versioning > Tag > Tag.

  3. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  4. Enter a name for the tag in the Tag Name box.

  5. Set the other options as required. To obtain descriptions of the options, press F1.

  6. Click OK.

To delete CVS tags:

This procedure will delete symbolic tags from the local CVS revisions of selected files.

  1. In the Application Navigator, select a single file, a project or a workspace. If you select a project or a workspace, the tag will be deleted from all the files within the project or workspace.

  2. Choose Versioning > Tag > Delete Tag.

  3. Check that you want the operation to apply to all of the files highlighted in the file selection box.

  4. Enter the name of the tag in the Tag Name box.

  5. Click OK.

To view CVS tags:

This procedure will display a dialog containing information about any existing tags that have been applied to the file revision.

  1. From the context menu of the file, choose Versioning > Properties.

  2. Select the Versioning tab. The sticky tag, date and options (if any) are shown, as is a list of existing tags for the file revision.

To reset CVS tags:

This procedure will remove any sticky tags or dates that have been applied to the selected files and reset them to the HEAD revision.

  1. In the Application Navigator, select the file or files whose tags you wish to reset.

  2. Choose Versioning > Tag > Reset Tags.

6.4.6 How to Use External Tools and Export Features

At times, you may wish to use CVS with external tools (for comparing versions of files to be merged, for example) or to create and apply patches for projects you are developing with files under CVS control. Additionally, you may find it necessary to export a CVS module, or to copy the CVSROOT value to the clipboard. These procedures explain how.

6.4.6.1 How to Use an External Diff Tool with CVS

JDeveloper has an integrated compare viewer that works well for most circumstances. However, you may prefer to use another compare tool or the simple output from CVS DIFF. JDeveloper lets you integrate third party tools and applications. This procedure describes how to use the External Tools support in JDeveloper to integrate external compare viewers.

To integrate CVS DIFF:

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable
    The location of your CVS installation (for example c:\cvsnt\cvs.exe) or just cvs

    Arguments
    -d ${cvs.root} diff ${file.name}

    Alternate arguments
    -d ${cvs.root} diff -r ${cvs.revision} -r ${cvs.second.revision} ${file.name}

    Run Directory
    ${file.dir}

    Enter the alternate arguments if you want to integrate a tool that compares two specific CVS revisions when the history tool is visible.
  4. On the Display page, enter a caption for the diff tool (for example CVS Diff with Repository) in the Caption for Menu Items box.

  5. On the Integration page, choose how you want the diff tool to be integrated into JDeveloper. For example, select the Tools Menu, Navigator Context Menu, and Code Editor Context Menu items.

  6. On the Availability page, select When a File is Selected or Open in the Editor.

  7. Click Finish.

To integrate a third party diff utility:

You can use external tools macros to view differences between two revisions in the history tool using a third party utility such as Araxis Merge. The following steps will install a menu item to invoke Araxis Merge. For other utilities, consult the documentation of the utility to determine which command line arguments need to be passed in.

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable The path to the third party tool (for example c:\araxismerge\compare.exe)

    Arguments
    /wait /title1:"${file.name} revision ${cvs.revision}" /title2:"${file.name} revision ${cvs.second.revision}" /2 ${cvs.revision.file} ${cvs.second.revision.file}
  4. On the Display page, enter a caption for the third party tool (for example Araxis Diff) in the Caption for Menu Items box.

  5. Complete the remainder of the wizard as required. For help when using the wizard, press F1 or click Help.

  6. Click Finish.

To integrate other CVS commands:

You can take advantage of the supplied external tool macros to easily integrate other CVS commands into JDeveloper. An example is the CVS annotate command (sometimes referred to as "blame"), which shows a summary of who changed each line of code and when the change was made. To integrate a tool for CVS annotate, set the following options in a new tool:

  1. In JDeveloper, select Tools > External Tools.

  2. Click Add. This opens the Create External Tool wizard.

  3. On the External Program Options page, enter the following information:


    Program Executable
    The path to the CVS executable (for example, C:\cvs\cvs.exe)

    Arguments
    -d ${cvs.root} annotate ${file.name}

    Run Directory
    ${file.dir}
  4. Complete the remainder of the wizard as required. For help when using the wizard, press F1 or click Help.

  5. Click Finish.

6.4.6.2 How to Export a CVS Module

You use the CVS Export wizard to export the revisions of files for a module, creating a deployment-ready file structure.

To use the CVS Export wizard:

  1. Choose Versioning > Export Module. The CVS Export wizard is displayed.

  2. Complete the export as prompted by the wizard. To obtain more information when working with the wizard, F1 or click Help.

The files are exported to the location you have specified.

6.4.6.3 How to Copy the CVSROOT Path to the Clipboard

You can copy the path of the CVSROOT from a node in the CVS Navigator to the Clipboard, for use in other applications.

To copy the CVSROOT path to the Clipboard:

  1. In the Connection Navigator, right click the connection name.

  2. From the context menu, choose Copy CVSROOT.

The full path of the CVSROOT is copied to the Clipboard, from where you can paste it into another application.

6.4.7 How to Create and Apply Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

    The Select Patch Context dialog may open. For help while using this dialog, press F1.

    The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1.

To apply a patch:

  1. In the navigator, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Versioning > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1 or click Help.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1.

  6. To apply the patch, click OK.

6.5 Using Perforce with Oracle JDeveloper

Perforce uses a local directory structure to receive files that are going to be placed under formal source control. This location is called the "Perforce client workspace". Files created in (or moved into) JDeveloper must be stored in this location. Once files are in your Perforce client workspace, you bring them fully under source control by submitting them to a central location called the "Perforce depot". Files must be submitted to the Perforce depot before they can be versioned and accessed by other users.

6.5.1 How to Set Up Perforce with JDeveloper

Before using Perforce with JDeveloper, in addition to downloading the Perforce extension, you need to install a number of Perforce features so that they are available to JDeveloper. Once installed, you configure JDeveloper and connect to the Perforce client workspace. Finally, you need to bring your working files under Perforce control so that they are available from within JDeveloper while using Perforce.

6.5.1.1 How to Install Perforce Components for Use with JDeveloper

There must be at least one Perforce server installed, on a machine that is accessible to the intended JDeveloper users. If a Perforce server installation does not already exist, obtain the necessary software (for example, from www.perforce.com) and install it in accordance with Perforce's instructions. Record the identity of the machine on which the Perforce server software has been installed: you will need this when you connect to it through JDeveloper.

Perforce Client Installation

You must install the Perforce client application on the machines that contain (or that will contain) JDeveloper. The Perforce client application can be installed from the same software as the server software, obtainable from www.perforce.com. The installation must include the "Command Line Client (P4)" and, for Windows installations, "Visual Merge for Windows (P4WinMrg)".

When you first run the Perforce client application, you will be required to create a Perforce client workspace. The Perforce client workspace is where the working copies of files under Perforce control will be stored. You can use the JDeveloper default directory as the Perforce client workspace, whether or not it already contains JDeveloper files. The JDeveloper default directory is <installation_directory>\jdev\mywork. Alternatively, you can accept the default Perforce client workspace, or specify one of your own. In these cases, you should note the location you have used, because you will need to specify it when creating applications and projects in JDeveloper.

f you set up passwords in the Perforce client application, you will also need to use them when connecting to Perforce through JDeveloper.

JDeveloper Installation

JDeveloper must be installed in the normal way. Each installation of JDeveloper can act as a client application for Perforce. You can install JDeveloper on every machine that you wish to be a Perforce client, or you can use a mixture of JDeveloper installations and Perforce's own client applications. The JDeveloper and Perforce client applications will work together in a seamless manner. In addition to the JDeveloper embedded support for Perforce, you will also be able to access a Perforce client application through the JDeveloper interface.

6.5.1.2 How to Configure JDeveloper for Use with Perforce

Before you can configure JDeveloper to use Perforce, you must have installed the Perforce server and client software.

To configure JDeveloper for use with Perforce:

  1. Choose Tools > Preferences, then select Extensions in the left pane of the Preferences dialog.

  2. In the right pane, make sure that Versioning Support n is checked, then click Configure.

  3. Ensure that Versioning Support for Perforce n is checked.

  4. In the left pane of the Preferences dialog, open the Versioning node and then the Perforce node. The main Perforce preferences panel is shown. Other Perforce preferences panels are shown when you click on the items beneath the Perforce node.

  5. Make changes to the preferences as required. For more information about the specific preferences, press F1.

  6. Click OK to close the Preferences dialog.

To select Perforce as the version system:

  • Choose Versioning > Version System: [...] > Perforce.

6.5.1.3 How to Connect to Perforce

Before Perforce operations become available within JDeveloper, you must connect to Perforce.

To connect to Perforce manually:

  1. Choose Versioning > Connect to Perforce.

    The Connection dialog is opened. The username, port and client information should have been derived automatically and should now appear in the Connection dialog.

  2. If not already present, enter the correct username, port and client information.

  3. If the Perforce server has been set up with password protection, enter the password. (If you want the password to be remembered for the next time you make a connection, check the Remember Password box.)

  4. If you want to test the connection to the Perforce server, click the Test Connection button. The results will be displayed in the rectangular text area.

  5. To complete the connection, click OK.

To connect to Perforce automatically when you start JDeveloper:

  1. Choose Tools > Preferences, then select the Versioning node and then the Perforce node.

  2. Check the Connect Automatically on Startup box.

  3. To close the Preferences dialog, click OK.

6.5.1.4 How to Make Multiple Connections to Perforce

In some development environments, you may need to make more than one connection to Perforce. For example:

  • Your organization uses one Perforce server for development and another Perforce server for test.

  • You wish to connect using two different Perforce clients.

  • You wish to use different Perforce user IDs.

The Perforce extension to JDeveloper permits all these operations. You begin by giving each Perforce connection a name as you create it.

To create a named Perforce connection:

  1. Choose Versioning > Connect to Perforce.

    The Connection dialog is opened. The username, port and client information should have been derived automatically and should now appear in the Connection dialog.

  2. If not already present, enter the correct username, port and client information.

  3. Enter a name to use for this Perforce connection. Make sure it is different from any other Perforce connection that you currently have open.

  4. If the Perforce server has been set up with password protection, enter the password. (If you want the password to be remembered for the next time you make a connection, check the Remember Password box.)

  5. If you want to test the connection to the Perforce server, click the Test Connection button. The results will be displayed in the rectangular text area.

  6. To complete the connection, click OK.

Note that your Perforce changelist will display the connection that applies to each file in the changelist.

6.5.1.5 How to Bring Files Under Perforce Control

Files that you create within JDeveloper, or files that you bring into JDeveloper from outside, must be brought under Perforce control before you can use the JDeveloper Perforce versioning facilities with them.

If you have an existing JDeveloper project that you wish to bring under Perforce control, use the Import to Perforce wizard.

To put individual JDeveloper files under Perforce control:

  1. Select the files in the navigator and choose Versioning > Open for Add.

    The files can be your work files, or they can be the application and project files used by JDeveloper.

    The Add Files to Perforce dialog is displayed with the files listed.

  2. If you wish to lock the files, making them unavailable to others for editing, check the Lock Files box.

  3. To add the files to Perforce control, click OK.

    The files are now shown in the navigator with a red cross, meaning that they are stored in your Perforce client workspace but not yet in the Perforce depot. Files must be added to the Perforce depot before they can be versioned and accessed by other users.

  4. To add files to the Perforce depot, select the files in the navigator and choose Versioning > Submit.

    The Submit Files dialog is displayed with the files listed.

  5. Add your versioning comments in the Comments box.

    You will later be able to see these comments when viewing the list of versions of a particular file.

  6. To submit the files to the Perforce depot, click OK.

    The files are now shown in the navigator with a green dot, indicating that they are known to the Perforce depot and are up to date.

To bring files created outside JDeveloper under Perforce control:

  1. Copy or move the files into an existing \src directory under the JDeveloper file storage directory (which should be the same as the Perforce client workspace).

  2. Close and reopen JDeveloper.

    The files should now appear in the navigator, within the project whose \src directory you used. The files are marked with a white-on-blue diagonal cross, showing that they are known to JDeveloper but not under source control.

  3. Bring the files under Perforce control as described in the previous procedure.

6.5.1.6 How to Import JDeveloper Files Into Perforce

Before you can start using existing JDeveloper project and source files with Perforce, you have to import them into your Perforce client workspace. Once they are in your Perforce client workspace, you bring them fully under source control by submitting them to the Perforce depot.

You import JDeveloper project and source files into your Perforce client workspace using the Import to Perforce wizard.

To use the Import to Perforce wizard:

  1. If you have not already done so, connect to Perforce by choosing Versioning > Connect to Perforce.

  2. In the Application Navigator, select the JDeveloper project that you want to bring under Perforce control.

  3. Choose Versioning > Import Project. The Import to Perforce wizard is displayed.

  4. Complete the import as prompted by the wizard. To obtain more information when working with the wizard, press F1.

    The project and files will be shown in the navigator. If you have chosen to display overlay icons, these will indicate the current source control status of the files.

  5. To bring the files fully under Perforce source control, submit them to the Perforce depot.

6.5.2 How to Work with Files in Perforce

Perforce provides features for creating and applying patches—methods for determining changes between two revisions of a file, and then applying those changes to a third file. In addition, Perforce contains features for exporting the details about repository connections, as well as files in the repository.

6.5.2.1 How to Synchronize Local Files With the Controlled Versions

Another person may edit a file through their Perforce client and submit their changes to the Perforce depot. This will cause your copy of the file to become out of date compared with the controlled version.

To test that your view is showing the latest file statuses:

  • Choose View > Refresh.

    A file that is out of date with the controlled version is shown with an exclamation point icon.

To bring your files up to date compared with the controlled version:

  1. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  2. Select the files in the navigator and choose Versioning > Sync.

    The Sync Files dialog is displayed with the files listed.

  3. Complete the dialog.

    For more information about the dialog options, press F1.

  4. To synchronize the files, click OK.

    Your local files are replaced with copies of the controlled versions. The icon shown next to the files changes to a green dot.

6.5.2.2 How to Synchronize Files With the Perforce Navigator

The Perforce Navigator lets you browse the Perforce depot and update your working directory from content at the depot. Using the navigator, you can select folders or files to sync to your client workspace, downloading content from the Perforce Server to your computer. If new files are detected in the depot, you have several options for handling them.

If you opens a connection node and no connection has been made, Perforce displays the connection dialog.

To synchronize your files using the Perforce Navigator:

  1. Expand the content under Perforce in the Versioning Navigator, selecting the folders and/or files you wish to synchronize. When you expand to the level of the project you're working on, right-click the file or folder, and then select Sync From Depot. This displays the Sync From Depot dialog.

  2. The project you selected displays in the Name pane of the Sync From Depot dialog. Below that are fields you can select or specify:

    Head Revision

    Synchronize to the Head revision of your project. If you select this, the Sync From Depot dialog displays the Force sync checkbox. Select Force Sync if you wish to download the depot content to your working directory regardless of the contents of each (for example, if you know you want to start with a clean download of the depot's contents).

    Revision Number

    Select this to synchronize to a specific revision number. The Sync From Depot opens the Target field; use the Target field to type the revision number to which you wish to synchronize your local working copy.

    Changelist

    Select this to synchronize to a specific changelist. The Sync From Depot opens the Target field; use the Target field to type the name of the change list from which you wish to synchronize your local working copy.

    Label Name

    Select this to open files with a specific label (typically, used to identify a specific branch). The Sync From Depot opens the Target field; use the Target field to type the name of the label from which you wish to synchronize your local working copy.

    Date

    Select this to specify a date (and, optionally, time) from which you wish to synchronize your local files. The Sync From Depot opens the Target field; use the Target field to type the date (in either yyyy/mm/dd or yyyy/mm/dd:hh:mm:ss format) of the files from which you wish to synchronize your local working copy.

    Choose the field that applies to your current project, then click OK.

  3. If the depot contains files that do not exist in your source, Perforce tells you that new files were detected, and lists the following options:

    Open files in active project

    Copy the files, and open them in the project you have selected.

    Create new project from files

    Creates a new project, using the files Perforce has detected.

    Open editors onto files

    Open the files in editor windows, so that you can review them and determine the best resolution (keep, rename, discard, or modify).

    Do not open files

    Leaves the files unopened, without copying them from the depot to your working directory.

6.5.2.3 How to Filter Files By Perforce Workspace

If you have a very large number of files in your Perforce depot, it can be much easier to navigate to the files you're working on by filtering files in the Perforce workspace. You can do this by setting things up in the Perforce client, and then displaying the filtered view in JDeveloper.

Filtering files in Perforce (specifically, p4v) requires making sure that you are viewing the Depot Tree, then select the Filter icon > Tree Restricted to Workspace View.

To filter files in JDeveloper:

  • Version Navigator > Perforce > Connection name > Context menu - Filter by Client Workspace.

You will only see a difference in the JDeveloper Version Navigator if the Perforce client has a rule that restricts the Perforce workspace. (In p4v, the rules are shown and set in the View field of the Workspace dialog for the selected workspace.) You could restrict the workspace view in your p4v client with a rule like the following:

//depot/JDeveloper_1013/... //<client name>//JDeveloper_1013

In JDeveloper, if you select Filter by Client Workspace, the navigator would be filtered so only //depot/JDeveloper is shown.

6.5.2.4 How to Edit Files

By default, you can start editing a file under Perforce control just by opening it from the navigator. While the Perforce server is being contacted, you may experience a delay before you can type into the opened file. If you would prefer files to remain closed until you manually open them for editing, set the Automatically Open Files for Edit preference to off. The following procedure works whichever way the preference is set.

To edit a file under Perforce control:

  1. Select the file in the navigator and choose Versioning > Open for Edit.

    The Open Files for Edit dialog is displayed with the file listed.

  2. If the file is out of date with the controlled version and you wish to edit the controlled version, check the Sync files to box.

    If you do not obtain the controlled version before editing the file, you may create a conflict between your file and the version in the Perforce depot. You will then have to resolve the conflict before your changes can be accepted into the controlled version.

  3. If you wish to lock the file, check the Lock Files box.

    Locking a file means that others can edit the file but cannot submit the file until the person who applied the lock has released it.

  4. To make the file editable under Perforce control, click OK.

    The file will be indicated to Perforce as editable. A red check mark is added to the file's icon in the navigator.

  5. To edit the file, choose Open from the file's context menu.

  6. Make your changes and save the file.

    You can also close the file if you wish.

The changes that you made to the file are now saved in your Perforce client workspace. To add your changes to the controlled version of the file and make them available to other users, you must now submit them.

6.5.2.5 How to Submit Changed Files to the Perforce Depot

Any changes that you make to a file are initially saved in your Perforce client workspace. To add these changes to the controlled version of the file and make them available to other users, you must submit them. In the following procedure, if the Submit menu option is unavailable, it is because there are unresolved conflicts between your copy of the file and the one in the Perforce depot. Before proceeding, you will have to resolve the conflicts or revert the file to a non-conflicting version.

To submit changes to the Perforce depot:

  1. With the file selected in the navigator, choose Versioning > Submit.

    The Submit Files dialog is displayed with the file listed.

  2. Add your versioning comments in the Comments box.

  3. To submit the files to the Perforce depot, click OK.

    The file is now shown in the navigator with a green dot, indicating that it is up to date compared with the version in the Perforce depot.

6.5.2.6 How to Resolve Conflicts in File Versions

If there is a conflict between your copy of the file and the one in the Perforce depot, the icon next to the affected file will include an exclamation point. You will not be able to submit such a file to the Perforce depot. To overcome this problem, you should either revert to a non-conflicting version of the file, or resolve the conflict. You can resolve the conflict using the locally installed Perforce client application, or another merge tool of your choice, as specified on the Preferences page (Tools > Preferences > Versioning > Perforce > Version Tools).

To revert to a non-conflicting file version:

  • Select the file in the navigator and choose Versioning > Revert.

To resolve conflicting file versions (assumes use of Perforce merge tool):

  1. Open the Perforce client by choosing Versioning > Resolve.

  2. In the pending changelists for the client, identify the change.

  3. Resolve the conflict using the Perforce tools.

    If you cannot automerge the conflicts, run the merge tool and use its facilities to create a definitive version from the conflicting data.

  4. Accept the merge.

  5. Submit the merge.

  6. In JDeveloper, use View > Refresh to obtain the green dot on the file.

    The file will still be marked as open for edit.

  7. Submit the file.

6.5.2.7 How to Resolve Conflicts in File Versions

If there is a conflict between your copy of the file and the one in the Perforce depot, the icon next to the affected file will include an exclamation point. You will not be able to submit such a file to the Perforce depot. To overcome this problem, you should either revert to a non-conflicting version of the file, or resolve the conflict. You can resolve the conflict using the locally installed Perforce client application, or another merge tool of your choice, as specified on the Preferences page (Tools > Preferences > Versioning > Perforce > Version Tools).

To revert to a non-conflicting file version:

  • Select the file in the navigator and choose Versioning > Revert.

To resolve conflicting file versions (assumes use of Perforce merge tool):

  1. Open the Perforce client by choosing Versioning > Resolve.

  2. In the pending changelists for the client, identify the change.

  3. Resolve the conflict using the Perforce tools.

    If you cannot automerge the conflicts, run the merge tool and use its facilities to create a definitive version from the conflicting data.

  4. Accept the merge.

  5. Submit the merge.

  6. In JDeveloper, use View > Refresh to obtain the green dot on the file.

    The file will still be marked as open for edit.

  7. Submit the file.

6.5.2.8 How to Refresh the Status of Files under Perforce Control

The source control status of a file is indicated in the JDeveloper navigators by icon overlays, as listed in.

Table 6-2 Perforce Status Icons

Icon Meaning

Not in depot

The file is in the Perforce client workspace but is not yet submitted to the Perforce depot.

Ready for deletion

The file will be deleted when next submitted to the Perforce depot.

Out of date

The file is out of date compared with the Perforce depot.

Overlay not open

The file is up to date compared with the Perforce depot.

Open for Edit

The file is open for edit.

Locked

The file is locked.


If the status of a file is changed outside JDeveloper, for example by using a Perforce client application, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Application Navigator matches the true status of the file in the source control system, you can perform a manual refresh.

To refresh the status of files in JDeveloper:

  • Select View > Refresh.

6.5.2.9 How to Delete Files

If you wish to delete a file that it is under Perforce control, you should do so using the Perforce facilities within JDeveloper or the Perforce client application. You should not use the Erase From Disk or Delete commands to delete a file that is under Perforce control, as this may cause versioning problems.

To delete a file under Perforce control:

  1. Select the file in the navigator and choose Versioning > Open for Delete.

    The Delete Files dialog is displayed with the file listed.

  2. Click OK.

    The file is deleted from the local file system. A black diagonal cross is added to the file's icon in the navigator.

If you need to retrieve a file that has been deleted, you will need to use the Perforce client. To do this, select Versioning > Perforce > Launch Perforce Client.

6.5.3 How to Work with Changelists

In Perforce, changelists let you group files together to simplify operations. Once files are grouped in a changelist, you can check them out and submit them all in a single operation.

In Perforce, changes are submitted to a Perforce repository using a changelist. This lets you group changes to several files into a logical unit, and then submit this unit to the Perforce repository in one operation.

You can have more than one changelist. You may find it useful to create changelists for specific projects, for related groups of files, or for any other grouping of files that you find create a logical unit, based on the way you and your team work. You can also move files from one changelist to another.

In general, you use changelists by following this workflow: create a changelist, add files to your changelist, edit your files and submit your changelist with the edited files.

You can also browse existing changelists through the Changelist Browser. The Changelist Browser also lets you create, submit, and move files between changelists. If the submit operation fails on any file in the changelist, then the whole changelist fails. This means the Perforce repository is left in a consistent state.

6.5.3.1 How to Create a Perforce Changelist

A Perforce changelist lets you manipulate a number of changed files and folders in a single operation, simplifying the process when you have several files that you have been working on.

To create a Perforce changelist:

  1. From the Versioning menu, select Perforce > Create Changelist.

  2. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  3. Select the files to be added to the changelist, or click Select All to add all displayed files to this changelist.

  4. Add comments to this changelist, if desired. You can choose a previous comment (with the option of editing it if necessary), or you can select your comment template.

  5. When you have set up the changelist as desired, click OK.

6.5.3.2 How to Annotate a Perforce Revision or Changelist

Annotating a Perforce revision or changelist lets you store the Perforce revision or changelist as a comment linked to every file in the revision. When you modify these files later in Perforce, you can view the sequence of revisions or changelists to these files, as annotations to the files.

To add annotations to a changelist:

  1. From the Versioning menu, select Versioning > Perforce > Perforce Pending Changelists.

  2. Select the changelist to view by clicking the Use Changelist selector.

Any previous annotations will be visible in the Comments field of the changelist.

6.5.3.3 How to Add Files to a Perforce Changelist

A Perforce changelist lets you manipulate a number of changed files and folders in a single operation, simplifying the process when you have several files that you have been working on. When you add files to Perforce, you can select the changelist to which these files will be added at the same time, through the Open for Add menu.

To add files to a changelist:

  1. From the Versioning menu, select Perforce > Open for Add.

  2. Select the changelist to use by clicking the Use Changelist selector.

6.5.3.4 How to Submit a Perforce Changelist

Once you have made a series of edits to your files, you are ready to submit them in Perforce. If you have created a changelist, you can submit all the files on that changelist in a single operation, or select just the ones you have edited and submit them.

To select and submit the files in a changelist:

  1. From the Versioning menu, select Perforce > Submit Changelist.

  2. Enter a description of the changes you have made in the Description field.

  3. Check the files you wish to submit. Use the Select All and Deselect All buttons if required.

6.5.3.5 How to Use the Changelist Browser

The Changelist Browser lets you see, at a glance, the state of all the pending changelists in your Perforce repository. Each pending changelist is shown with its name, description, and contents. The default changelist is always shown at the top of the browser. Under each changelist, you can browse the files that are associated with that changelist. Additionally, the Perforce connection and client are displayed at the top of the browser.

From the Pending Changelist browser, you can create and submit changelists, move files between changelists, and refresh the browser.

To create a changelist with the Changelist Browser:

  1. From the Versioning menu, select Perforce > Create Changelist.

  2. From the Connection drop-down list, select the preferred Perforce connection (if you have more than one) for this changelist.

  3. Select the files to be added to the changelist, or click Select All to add all displayed files to this changelist.

  4. Add comments to this changelist, if desired. You can choose a previous comment (with the option of editing it if necessary), or you can select your comment template.

  5. When you have set up the changelist as desired, click OK.

To submit a changelist:

  1. From the Versioning menu, select Perforce > Submit Changelist.

  2. Enter a description of the changes you have made in the Description field.

  3. Check the files you wish to submit. Use the Select All and Deselect All buttons if required.

To move files between changelists:

  1. Click the right mouse button the file in the Changelist Browser and select Move File to Changelist.

  2. Select the changelist to which you wish to move this file, then click OK.

You can also refresh the changelist browser by pressing F1.

6.5.4 How to Create and Apply Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

    The Select Patch Context dialog may open. For help while using this dialog, press F1.

    The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1.

To apply a patch:

  1. In the navigator, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Versioning > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1.

  6. To apply the patch, click OK.

6.6 Using Serena Dimensions with Oracle JDeveloper

JDeveloper allows you to use the source control features of Dimensions. JDeveloper integrates the repository management and file access features of Dimensions so that you can access your repository, check files in and out, and view the checked-in versions of files under Dimensions control.

Dimensions is a popular version-control system that is part of a larger content-management and workflow control package. JDeveloper includes an extension which allows you to access the version-control features of Dimensions from within the JDeveloper IDE.

To use Dimensions from within JDeveloper, you need to complete several simple setup operations, to ensure that your Dimensions repository is available and your working files are under Dimensions control.

You can then set the current project for JDeveloper, under the control of Dimensions.

After setting up Dimensions and JDeveloper, your typical workflow will probably follow this basic sequence:

  • Check out files to be edited

  • Make edits and do other content development

  • Check files in to the repository

In addition to the general workflow outlined here, you may also find it useful to undo a file checkout.

6.6.1 How to Set Up Dimensions and JDeveloper

Before you can use Dimensions as your version control system with JDeveloper, you need to perform some initial setup operations. This setup involves connecting to a Dimensions repository, learning how to disconnect if required, and choosing the initial project in JDeveloper.

6.6.1.1 How to Connect to a Dimensions Repository

You connect to a Dimensions repository when you want check out files, synchronize your working copies with the common repository, or check files in before a build. Once you are connected, most file operations in Dimensions are available from the context menu for a file, folder or project.

To create a Dimensions profile:

  1. Select Versioning > Dimensions > Connect to Dimensions.

  2. In the Profile field, type a name for the profile you plan to create. Use a name which will be easy to identify when you are choosing between multiple profiles later

  3. Enter the username and password you use to log in to the Dimensions server for the project for which you are creating this profile.

  4. Enter the server's URL (for example, myserver.mycompany.com), the database name and the database connection. You should be able to obtain this information from your Dimensions administrator.

  5. Click OK.

To connect to a Dimensions repository with an existing profile:

  1. Select Versioning > Dimensions > Connect to Dimensions.

  2. Enter the username and password you use to log in to the Dimensions server.

If you are connecting to Dimensions for the first time, you will need to create a profile for this connection. You can have multiple profiles for connecting to different servers and databases, if you use Dimensions for multiple projects.

6.6.1.2 How to Disconnect from a Dimensions Repository

Disconnecting from a Dimensions repository lets you connect to another repository, if your organization uses more than one repository or more than one version control system. You also need to disconnect from Dimensions if you plan to connect with a different profile.

To disconnect from a Dimensions repository:

  1. Select Versioning > Dimensions > Disconnect from Dimensions.

  2. Click OK.

6.6.1.3 How to Add Files to Dimensions Control

As you create new files for your projects and applications, you need to add them to Dimensions control so that they are available to your other team members and to the build system.

To add files to Dimensions control:

  1. Select the file, then click the right mouse button and select Versioning > Dimensions > Add.

  2. When JDeveloper displays the Add Items dialog, select the item you wish to add, type a comment (optional), and then click OK.

6.6.1.4 How to Remove Files from Dimensions Control

If a file no longer applies to the project you are working on, you can remove it from Dimensions control.

To remove a file from Dimensions control:

  1. Click the file in the Application Navigator to select it.

  2. Select Versioning > Dimensions > Remove.

  3. Click OK.

6.6.1.5 How to Set the Current Project

Setting the current project lets Dimensions know which of your local directories to monitor for changes versus the Dimensions repository. Once you have set the current project, Dimensions will display files with unsaved changes in the Pending Changes list, as well as making the files in that project available in the Application Resources navigator and more.Before you can set a project, you must be connected to Dimensions.

To set the current project:

  1. Select Versioning > Set Current Project.

  2. To select a project from your local workspace (such as the default directory, JDeveloper/mywork), select Use Global Project. If you are working in the default project defined by your Dimensions administrator, select Use Default Project.

  3. Select the product and project from the drop-down selection boxes.

  4. Enter the root directory for this project's files in your local file system, or click Browse to choose from a list.

  5. Click OK.

6.6.2 How to Work with Files in Dimensions

After initial setup, most of your work in Dimensions will involve files. You will need to add files to (and, occasionally remove files from) the Dimensions repository. You can browse files from the Versioning Navigator, where you can check them out, check them in, and otherwise manipulate them. Additionally, Dimensions lets you view a copy of a file in the repository so you can search for changes from a version of the same file that you are working on.

6.6.2.1 How to Import Files to Dimensions

If you have created a new JDeveloper application, you can add all that application's files to Dimensions in a single operation by using the Import Wizard.

To import files to Dimensions:

  1. Create an application (File > New > Applications > select application type).

  2. Version the application (right-click selected project > Version Project > Dimensions).

  3. Create a connection to source control (right-click selected version control system in Versioning Navigator > New Dimensions Connection > enter Dimensions connection data). This opens the Import to Dimensions wizard, displaying the Welcome screen.

  4. From the Welcome screen, click Next to continue, or select Skip this page next time to proceed to the Destination page the next time you use the Import to Dimensions Wizard.

6.6.2.2 Using Navigator Icon Overlays

JDeveloper uses several overlays on the file navigator icons to represent the state of the associated file in Dimensions, as listed in Table 6-3.

Table 6-3 Dimensions Status Icons

Icons Description
Not under Dimensions control

File not under Dimensions control:

The file is not under Dimensions control

Extracted by multiple users

File extracted by multiple users

The file has been extracted by others, but is available for checkout

Extracted by others

File extracted by others

The file has been extracted by others and is not available for checkout

Extracted by single user

File extracted by single user

The file has been extracted by a single user, but is available for checkout

Not extracted

File not extracted

The file has not been extracted

Not authenticated

File not authenticated

The user has not logged into the Dimensions server

Removed from server

File removed from server

The local file has been removed from the Dimensions server


6.6.2.3 How to Download a Dimensions Project

Downloading files from the Dimensions repository to your local working directory is the key to working in Dimensions. You can do this after you have connected to Dimensions. Once you have signed in to the Dimensions server, use the Versioning Navigator to navigate to the content you wish to work with. After you select a folder, Dimensions lets you download the contents of the folder (giving you the option of expanding subfolders) to your local working directory.

Now that you have copied the content from the Dimensions repository to your working directory, you need to set this content as the current project in Dimensions.

To download from the Dimensions repository:

  1. Click the + next to the Dimensions entry in the Versioning Navigator. This displays the profile with which you connected to the Dimensions server.

  2. Click the + next to your profile name. This expands the list of projects on the Dimensions server that are available to your profile. Depending on the number of projects and the connection speed, this may take a few minutes.

  3. Browse the available projects, clicking the + to expand project categories and folders. When you have identified the content you wish to work with, select the folder, click the right mouse button and select Download.

  4. Specify the download location and settings as follows:

    • Destination

      Enter the location of your local work area. Use the Browse button to select from a directory browser.

    • Expand Substitution Variables

      Select if your project uses substitution variables that you wish to expand when downloading to your work area.

    • Use database timestamps

      Select if you wish the local file copies to be created with the same timestamps they have in your Dimensions repository. If you leave this unselected, files will be created with timestamps reflecting the date and time you downloaded them.

    • Recurse

      Select if you wish Dimensions to expand (recurse) directories, checking out all files in all directories of the project.

    • Overwrite local files

      Select to overwrite any local files in your work area with content from the repository. Any changes you have made to the local files and have not yet checked in will be lost.

  5. Click OK.

6.6.2.4 How to Check Out Files

Checking out files from the Dimensions repository to your local working directory lets you make changes which will be tracked against the changes of others on your team. To do this, use the Dimensions Web client; your Dimensions administrator will have the URL and any login information you need to access the Dimensions Web client.Once you have signed in to the Dimensions Web client, use the left-hand pane to navigate to the content you wish to work with. The Web client displays this content in the right-hand viewing pane. If you select a folder, Dimensions will check out the contents of the folder (giving you the option of expanding subfolders) to your local working directory.You can control whether Dimensions automatically checks out files when you open a Dimensions-controlled file in JDeveloper. Select the Tools > Preferences > Versioning > Dimensions > General page. The option Automatically Check Out Files lets you specify whether Dimensions is to check out a file from the repository when you edit your local working copy.

To check out content from the Dimensions repository:

  1. Select Versioning > Dimensions > Check Out. This displays the Check Out dialog.

  2. In the field titled Check out contents of project folder to, enter or browse to the path to which you wish to check out the files (by default, this is JDeveloper/mywork).

  3. The Dimensions Web client presents the following options; select the ones you require for the project you are working on:

    • If writable workfile exists:

      Select Overwrite to force Dimensions to overwrite any writable file with the same name in your working directory. Otherwise, select Don't overwrite.

    • Relate to Requests

      You can associate this checkout (and any changes you make as part of this checkout) to a request (a means of tracking build changes, bug fixes, and more) that is maintained by Dimensions. The Dimensions version control system is part of a much larger project-management system with integrated workflow, bug tracking, and more. For details, refer to the on-line help for the Dimensions Web client.

    • Include subdirectories

      Select this if you wish to check out not only the content you have selected, but also the content of subdirectories inside the selected folder. If you perform local builds for testing and verification, and therefore need access to all the files in the project, you should select this.

  4. Click OK.

Now that you have checked out the content from the Dimensions repository to your working directory, you need to set this content as the current project in Dimensions.

When you have made the required changes and verified them locally, you can check in your changed files.

6.6.2.5 How to Undo a File Checkout

Undoing a file check out essentially leaves the file in the repository untouched, while removing any record from the repository's database that pertains to who checked out the file and when it was checked out. This not only leaves the file unchanged since the last checkin, it also leaves the file available to be checked out by other team members.Note that undoing a check out will essentially discard any work you've done since checking out the files. Use your judgment as to whether undoing a file checkout is the most effective solution to the situation you find yourself in, and consider whether saving a local copy (outside your local Dimensions directory) will be worthwhile.

To undo a file checkout:

  1. Click the right mouse button on the file in the Pending Changelist, then select Undo Check Out. This opens the Undo Check Out dialog.

  2. In the After Undo Check Out field, select how you want Dimensions to leave your local copies:


    Leave workfile as read only
    Select this to leave all copies in your local directory unchanged and in read-only mode. This is safest if you have made many changes that you wish to retain for future use.

    Replace workfile with latest copy
    Select this to have Dimensions update your local directory to the latest versions of all files, from the Dimensions repository. This ensures that you will have the up-to-date versions to work from, but it will overwrite any changes you have made.

    Delete workfile
    Select this to have Dimensions delete all checked-out files from your local directory. This is the surest way to start with a "clean sheet," by checking out all files in the project again.
  3. In the Include subdirectories field, select whether you want Dimensions to apply the previous choice (leave workfile as read only, replace workfile with latest copy, or delete workfile) to all subdirectories under the one you have selected. Depending on how your subdirectories are structured, you can use this to control the granularity of which files and what content you choose to undo.

  4. Click OK.

After undoing a check out, you will need to check out the latest content before you can work in Dimensions again.

You may also wish to get a copy of the Dimensions-controlled content on your local working directory.

6.6.2.6 How to Check In Files

After making and verifying your changes to the content for which you are responsible, you make your work available to the rest of the team by checking it in to Dimensions. This uploads your work to the Dimensions repository, where it will be available to other team members and to your organization's build process.

To check in files to Dimensions:

  1. Click the right mouse button on the file in the Pending Changelist, then select Check In. This opens the Check In dialog.

  2. In the Check In dialog, make the appropriate selections for the work you are checking in:


    Check In from directory:
    Enter the directory in your local file system from which you are checking in new work, or click the button next to the field to open a file system browser.

    Include subdirectories
    Check this if the work you are checking in includes files in subdirectories under that which you have selected.

    If workfile is unchanged:
    Check this to determine how Dimensions is to handle unchanged content in your working directory. You can choose to Check in your unchanged files, which will update the time stamp in the Dimensions repository, or Undo checkout, which removes any record, from the Dimensions database, of your having checked out the unchanged files.

    After Check In:
    This tells Dimensions how to leave the content in your local working directory. You can select Leave workfile as read-only, in which case Dimensions will leave the file as you left it but mark it read-only to prevent making unrecorded changes to the file while not under Dimensions control. Alternatively, you can select Delete workfile, which removes the local copy of your file (and all other files you are checking in). Whichever you select, you will need to check out the files from Dimensions again before resuming work.

    Description
    Enter a description of the changes you are making. You can include bug-tracking numbers or other information to help identify and track the specific checkin you are making at this time; however, tracking the files against the Dimensions request system is a more effective way of keeping tabs on changes.
  3. Click OK.

6.6.2.7 About the Pending Changes List

The Pending Changes list displays files, folders and other elements that have been created or modified and not yet added to Dimensions. This includes:

  • files which you have edited in JDeveloper

  • all files in a new project that you have created in JDeveloper and not yet placed under Dimensions control

  • any file for which some Dimensions-related activity needs to be performed.

Files are added to the Pending Change list when you save a copy locally.

6.7 Using Rational ClearCase with Oracle JDeveloper

JDeveloper allows you to use the source control features of Rational ClearCase release 4.0 onwards (including ClearCase 2002). JDeveloper works in a seamless manner with ClearCase so that once you have it configured you can add files to source control, and check them in and out from the navigators

The JDeveloper Rational ClearCase extension allows you to use the source control features of Rational ClearCase inside JDeveloper. Once you have JDeveloper configured to work with your ClearCase installation, you can add files to source control, and check them in and out from the navigators.

To work in ClearCase, you have to store your workspaces, projects and files on your ClearCase view; before new projects and files are under ClearCase source control, you have to explicitly add them to ClearCase. Once your files are added to your ClearCase view, you can check them in and out, compare versions, review file histories, and (if necessary) remove files from ClearCase

6.7.1 How to Configure JDeveloper to Use Rational ClearCase

To use ClearCase with JDeveloper, you must have ClearCase 4.0 or greater client installed on the same machine as JDeveloper.

To configure JDeveloper to use ClearCase:

  1. Select Tools > Preferences, then unfold the Versioning and ClearCase nodes.

  2. Set the preferences as required. Note that there are several pages of preferences for ClearCase. For information about the specific preferences, press F1.

  3. Close the Preferences dialog by clicking OK.

If you have not chosen (in the preferences) to have connections made automatically, make sure that you have a connection to the ClearCase server, then select Versioning > Connect to ClearCase.

Now that you have configured JDeveloper to work with ClearCase, you can access files and folders that already exist in a mounted ClearCase view. New files and folders must be created in or copied to your ClearCase view.

To add new files to ClearCase, see Section 6.7.2, "How to Add a File to ClearCase".

6.7.2 How to Add a File to ClearCase

To work in ClearCase, you have to store your workspaces, projects and files on your ClearCase view, and before new projects and files are under ClearCase source control, you have to explicitly add them to ClearCase. The comment pane in the Add to ClearCase dialog allows you to build up comments for different groups of files. The comments you type apply to the files you have selected. For example, you can select all the files and type a global comment. Next, select a smaller number of files. The first comment is displayed and you can add to it. Then you can select just a single file in this group and add another comment specific to that file.

To add one or more files to ClearCase:

  1. Select the files in the navigator, and choose Versioning > Add. The Add to ClearCase dialog is displayed, listing the items you have selected.

    If you want to continue working on the files, leave the Check In box clear. If you check the box, the files will be checked in and you must check them out when you want to work on them.

  2. To add the files in the list to ClearCase source control, click OK. You may see one or more messages asking whether you should add folders to ClearCase. Click Yes.

6.7.3 How to Refresh the Status of Objects under ClearCase Control

The source control status of an object is indicated in the Application Navigator by an icon overlay, as below.

Table 6-4 Status icons for ClearCase

Icon Description

checked out

The object is checked out and can be modified.

checked in

The object is checked in and must be checked out before it can be modified.


If the status of an object is changed outside JDeveloper, for example by checking in an object using external source control software, the new status might not immediately be shown in JDeveloper. To ensure that the status indicated in the Application Navigator matches the true status of the object in the source control system, you can perform a manual refresh. To refresh the status of objects in JDeveloper, select Versioning > Refresh States.

6.7.4 How to Remove a File From ClearCase

You can remove a file from ClearCase if you no longer need it. The files are removed from the current version of the directory which contains them.

To remove a file from ClearCase:

  1. With the file or files selected in the navigator, choose Versioning > Remove. The Remove from ClearCase dialog is displayed with the files listed.

  2. To remove all the listed files from ClearCase, click OK.

The files are removed from the current version of the directory, and you will no longer be able to work with them.

6.7.5 How to Check In a File to ClearCase

When you have finished working on a file, you should check it into ClearCase.

To check in files shown in the Application Navigator:

  • Select the files in the Application Navigator, and choose Versioning > Check In.

The Check In to ClearCase dialog is displayed listing the files that you selected.

If you want to check in the files even though they are identical to the previous versions in ClearCase, check the Force Check In Where Files Are Identical box. If you do not check this box, the file may remain checked out, depending on how ClearCase handles files of that type. If the file remains checked out, you can use the Undo Checkout command to return the file to its previous checked in state.

Type comments for this checkin into the Comments box or, to use the same comments for the check in that were used for the checkout, check the Use Checkout Comments box.

To check in the listed files, click OK. The files in the list are checked in to ClearCase source control.

To check in files shown in the Checked Out Files window:

  1. Select the files in the Checked Out Files window that you want to check in. To obtain more information about the Checked Out Files window, press F1.

  2. In the button bar of the viewer, click the Check In button.

6.7.6 How to Check Out a File From ClearCase

To work on a file, it must be checked out from ClearCase.

Files will be checked out automatically when you start to change them, if the Automatically Check Out Files preference is set on the ClearCase preferences page (available by choosing Tools > Preferences and selecting ClearCase). This preference applies to data files, workspace files and project files. For data files, the file is checked out when you begin to edit in the source view. If you check out a file unintentionally, immediately use Versioning > Undo Checkout to revert.

To check out one or more files manually:

  1. Select the files in the Application Navigator, and choose Versioning > Check Out. The Check Out From ClearCase dialog is displayed listing the items you have selected.

    If you want to prevent another user from checking out the same files and then checking them in before you do, check the Check Out Reserved To User box.

  2. Type comments about this checkout into the Comments box.

  3. To check out the listed files, click OK.

The files in the list are checked out from ClearCase source control and you can work on them.

Checked out files are shown in the Checked Out Files window. This window opens when files are first checked out. You can open it at other times by selecting Versioning > View Checked Out Files.

6.7.7 How to Undo a ClearCase Checkout

If you have checked out a file but not made any changes to it, or if you want to discard the changes you have made, you can undo the last check out of that file.

Caution:

You may lose you work if you use this on a file that you have changed since it was checked out.

To undo checkout for one or more files:

  1. Select the files in the navigator, and choose Versioning > Undo Checkout. The Undo Clearcase Checkout dialog is displayed listing the items you have selected.

  2. To undo the checkout for all the listed file, and lose any changes that you have made to those files, click OK.

6.7.8 How to List ClearCase Checkouts

You may want to see all the files that you have checked out from ClearCase, for example to see which files need to be checked in before performing another action.

To list ClearCase checkouts:

  • Choose Versioning > View Checked Out Files. The Checked Out Files viewer is displayed.

6.7.9 How to Compare Files Checked In to ClearCase

Use these procedures to compare versions of files that are under ClearCase source control. You can compare a file with: its immediate predecessor any of the file's previous revisions any other file on your file system.

You can choose which Compare Viewer to use (JDeveloper or ClearCase), by setting an option on the ClearCase Version Tools preference page under Tools > Preferences.

To compare a file with its immediate predecessor:

  • With the file selected in the Application Navigator, choose Versioning > Compare with Previous Version.

If there are no differences, a message is displayed. Otherwise, a Compare Viewer is displayed through which you can find and reconcile the differences.

To compare a file with another revision:

  • With the file selected in the Application Navigator, choose Versioning > Compare. Ensure that the Predecessor File Revision option is chosen.

Previous versions of the file are listed in the Compare ClearCase File dialog. Select the version you want to compare the current file with and click OK.

If there are no differences, a message is displayed. Otherwise, a Compare Viewer is displayed through which you can find and reconcile the differences.

To compare a file with a file outside ClearCase source control:

  • With the file selected in the Application Navigator, choose File > Compare With > Other File.

The Select File to Compare With dialog is opened.

Browse to and select the file you want to compare the current file with, and then click Open.

6.7.10 How to Display the History of a ClearCase File

Use this procedure to display the history of a file that is under ClearCase source control.

To display the history:

  • With the file selected in the navigator, choose Versioning > View History.

6.7.11 How to Display the Description of a ClearCase File

Use this procedure to display the description of a project or a file that is under ClearCase source control.

To display the description:

  • With the file selected in the navigator, choose Versioning > View Description.

The description appears in the Messages Log window.

6.8 Using Team System with Oracle JDeveloper

Oracle JDeveloper's Team System extension allows you to use the source control features of Microsoft Visual Team System inside JDeveloper. Once you have JDeveloper configured to work with Team System, you can add files to source control, and check them in and out from the navigators.

To begin using Team System with JDeveloper, you must first create a workspace using Team System software, and then populate this workspace with content from the Team System server. Files are checked out to the workspace, where they can be worked on. Files newly created within JDeveloper must be added to version control. Changed and new files are made available to other users by checking them in to the Team System server.

6.8.1 How to Set Up Team System and JDeveloper

Before beginning to use Team System with JDeveloper, there are some initial steps you need to follow:

  1. Set up the Team System client software. See Section 6.8.1.1, "How to Set Up Team System for Use with JDeveloper."

  2. Configure JDeveloper for use with Team System, including the preferences and other settings for making Team System the source control system recognized by JDeveloper. See Section 6.8.1.2, "How to Configure JDeveloper for Use with Team System."

In practice, Team System (like any version control system) consists of operations that you use at varying times depending on the place in the product lifecycle. For example, if you create a new file, you'll need to add it to Team System control. Other operations you may perform, depending on the stage of development, include:

6.8.1.1 How to Set Up Team System for Use with JDeveloper

To set up Team System for use with JDeveloper, follow these steps:

  1. Install the Team System server.

  2. Install the Team System client software.

  3. Connect the Team System client software to the Team System server.

  4. Use the Team System client software to create one or more workspaces.

  5. Use the Team System client software to populate the workspace(s) with content from the Team System server.

Instructions for doing the above are given in the Team System online help.

6.8.1.2 How to Configure JDeveloper for Use with Team System

Once you have set up Team System for use with Oracle JDeveloper, you are ready to configure JDeveloper to use Team System. In addition to the steps in Section 6.8.1.1, "How to Set Up Team System for Use with JDeveloper," make sure you have already i * Installed the JDeveloper Team System VCS extension (from the Official Oracle Extensions and Updates center).

To configure JDeveloper for use with Team System, carry out the following activities in JDeveloper:

  • Set preferences.

  • Select Team System as the JDeveloper versioning system.

  • Set the workspace to use with JDeveloper.

  • Create a JDeveloper project to hold the workspace files.

  • Refresh the workspace folders in JDeveloper.

To set JDeveloper preferences for use with Team System:

  1. Choose Tools > Preferences, then select Extensions in the left pane of the Preferences dialog.

  2. In the right pane, make sure that Versioning Support n is checked, then click Configure.

  3. Ensure that Versioning Support for Team System n is checked

  4. In the left pane of the Preferences dialog, open the Versioning node and then the Team System node. The main Team System preferences panel is shown. Other Team System preferences panels are shown when you click on the items beneath the Team System node.

  5. Make changes to the preferences as required.

    For more information about the specific preferences, press F1.

  6. Click OK to close the Preferences dialog.

To select Team System as the versioning system:

  • Choose Versioning > Version System [...] > Team System.

To set the workspace to use with JDeveloper:

  1. Choose Versioning > Set Workspace.

  2. Select the required workspace from the list.

To create a JDeveloper project to hold the workspace files:

  1. Select File > New to open the New Gallery.

  2. Use the New Gallery to create a new application and project.

  3. In the Application Navigator, select the newly created project and click the Add to Project Content button in the toolbar.

    This opens the Project Content page of the Project Properties dialog.

  4. Use the Add button in the Java Content area to add the location of the workspace.

    If your workspace contained Java sources, a dialog is displayed through which you should confirm that you want the sources added to the project content.

    To avoid confusion, you may wish to remove non-workspace locations from the Java Content list.

  5. Click OK to close the Project Properties dialog.

To refresh the workspace folders in JDeveloper:

  • Choose Versioning > Refresh Workspace Folders.

6.8.2 How to Work with Files in Team System

In addition to the file system operations you are probably familiar with from most version control systems (that is, checking files in and out, adding files to the repository, etc.), Team System lets you specify individual file versions from the server.

6.8.2.1 How to Get Versions of Files from the Team System Server

JDeveloper lets you get (from the Team System server) a version of a file that is in the Application Navigator. You must previously have used the get command in the Team System client software to populate your workspace with source files.

You can use this procedure to obtain the following versions of files: the latest version; files from a previously saved named changelist; files with a particular date stamp; files from a previously created named label; files from a particular workspace version.

The version obtained from the Team System server will replace the version currently in the Application Navigator.

To get versions of files from the Team System server:

  1. In the Application Navigator, select the application, project or files to set the scope of the Get operation.

  2. Select Versioning > Get.

    The Get dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.8.2.2 How to Add FIles to Team System Control

Use to bring files under Team System source control. The files will be added to the Team System server and made available to other users when you next check in the file.

To add files to Team System Control

  1. In the Application Navigator, select the file that you want to add to Team System control.

  2. Select Versioning > Add.

    The Add dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

  4. To add the file to the server and make it available to other users, check in the file.

6.8.2.3 How to Check Out Files

Use to check out files so that you can work on them. The files must already by under Team System source control.

To check out files:

  1. In the Applications Navigator, select the application, project or file that you want to check out.

  2. Select Versioning > Check Out.

    The Check Out dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.8.2.4 How to View the Status of a File

Use this procedure to check the status of a file that is under Team System source control. See also Section 6.8.2.5, "How to Refresh the Status of Files."

To view the status of a file:

  1. With the file selected in the Application Navigator, open the context menu and select Versioning > Properties.

  2. Select the Versioning tab.

The status labels shown are those used by Team System to describe the source control status of the file.

The main statuses are:

  • Edited - In JDeveloper, the file is checked out and may have been modified.

  • Unchanged - In JDeveloper, the file is currently checked in.

  • Scheduled for addition - In JDeveloper, the file has been added (that is, brought under source control) but not yet checked in.

6.8.2.5 How to Refresh the Status of Files

The source control status of a file is indicated in the JDeveloper navigators by icon overlays, as below.

Table 6-5 File status icons in Team System

Icon Description

Checked in

The object is checked in and must be checked out before it can be modified.

Checked out

The object is checked out and can be modified.

Unadded

The object is not under source control.

File added

The file has been brought under source control but has not yet been checked in to the Team System server.

scheduled for removal

The object has been scheduled for removal from the Team System server the next time it is checked in.


To refresh the status of files in JDeveloper:

  • Select View > Refresh.

6.8.2.6 How to Check In Files

Use to check in a file to the Team System server. A checked in version of a file can be seen and worked on by other users.

To check in files:

  1. In the Application Navigator, select the file that you want to check in.

  2. Select Versioning > Check In.

    The Check In dialog is opened.

  3. Complete the dialog.

    For information while using the dialog, press F1.

6.8.2.7 How to Resolve Conflicts in File Versions

If there is a conflict between your copy of the file and the one in the Team System server when you attempt to check it in, you will see a message box saying that the operation cannot be completed. To overcome this problem, you must first cancel the check-in operation, then do one of the following:

  • Revert to a non-conflicting version of the file.

  • Resolve the conflict using the merge tool in the Team System client software.

To revert to a non-conflicting file version:

  • Select the file in the Application Navigator and choose Versioning > Undo.

6.8.2.8 How to Undo Changes to Files

Use to undo the most recent change to a file.

To undo changes:

  1. In the Application Navigator, select the file whose last change you want to undo.

  2. Select Versioning > Undo.

    The Undo dialog is opened.

    The change will be undone when you click OK.

6.8.2.9 How to Replace a File with the Team System Base Version

Use this procedure to replace a file with the base version. The base version is the version from which the one you are currently working on originated.

To replace a file with the Team System base revision:

  1. In the Application Navigator, select the file to be replaced.

  2. Choose File > Replace With > Base Version.

    The Replace With Base Version dialog opens.

  3. Check that the file that you want to replace is shown in the dialog.

  4. To replace the file, click OK.

6.8.2.10 How to View the History of a File

Use this procedure to open the History Viewer and view the history of files held under Team System control.

To view the history of a file:

  • With the file selected in the Application Navigator, choose Versioning > Version History from the context menu.

For more information while using the History Viewer, press F1.

6.8.2.11 How to Compare Files In Team System

Use these procedures to compare files that are under Team System control with other versions of the same files, or with other files.

To compare versions of a file:

  1. From the context menu for the file, choose Compare With.

  2. Select either Previous Version, Latest Version or Other Version.

If there are no differences, a message is displayed. Otherwise the version or versions are shown in the History tool.

To compare a file with another file:

  1. From the context menu for the file, choose Compare With > Other File.

    The Select File to Compare With dialog is opened.

  2. Select the file to be compared.

    The files are shown in the Compare tool.

To compare two files:

  1. Select the two files in the navigator.

  2. From the context menu for one of the files, choose Compare With > Each Other.

The files are shown in the Compare tool.

6.8.2.12 How to Shelve and Unshelve Files

Shelving lets you save file changes in the Team System server without having to check the files in. As part of the shelving process, you can choose either to continue to work on the changed files or to remove them from view and revert to unchanged versions.

When you later want to make use of the file changes that were shelved, you can unshelve them.

If you decide you no longer want to keep changes that were shelved, you can delete the shelveset that you put them in.

To shelve a set of file changes that have not been checked in:

To shelve a set of file changes that have not been checked in:

  1. In the Application Navigator, select the versioned project containing the files.

  2. Select Versioning > Shelve.

    The Shelve dialog opens.

  3. Complete the dialog.

For information while completing the dialog, click F1.

The file changes will be shelved when you click OK.

The file icons in the Application Navigator will change to reflect the new file statuses, if any.

To unshelve a set of file changes:

  1. In the Application Navigator, select the versioned project into which you want to unshelve the file changes.

  2. Select Versioning > Unshelve.

    The Unshelve dialog opens.

  3. Select the shelveset name for the shelveset containing the file changes.

The file changes will be unshelved when you click OK.

Files deleted since the shelveset was created will be reinstated and the file icons in the Application Navigator will change to reflect the new file statuses.

To delete a shelveset:

  1. Select Versioning > Delete Shelveset.

    The Delete Shelveset dialog opens.

  2. Select the name of the shelveset that you want to delete.

The shelveset will be deleted when you click OK.

6.8.2.13 How to Delete Files

Use to delete files from your workspace and from the Team System server.

To delete a file:

  1. Select the file in the Application Navigator and choose Versioning > Delete.

    The Delete dialog is displayed with the file listed.

  2. Click OK.

    On the Outgoing tab of the Pending Changes window (Versioning > Pending Changes), the file will be indicated as ready for deletion: a black diagonal cross is added to the file's icon.

  3. To complete the deletion of the file, select it in the Pending Changes window and choose Versioning > Check In.

    The Check In dialog is opened.

  4. Add your comments, if any, and click OK.

The file is deleted from your workspace and from the Team System server.

6.8.3 How to Use Import and Export Features

The JDeveloper import and export features allow you to create and apply patches from just the changes or revisions between two versions of a file.

6.8.3.1 How to Create Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To create a patch:

This generates a patch comprising the differences between a controlled revision of a file and a revision of the file held locally.

  1. In JDeveloper, open the file for which you want to create a patch.

  2. Click the History tab.

    The History view lists all the revisions of the file. In the lower portion of the History view, the left pane shows the contents of a local revision, and the right pane shows the contents of the controlled revision.

  3. Select the revision combination for which you want to create a patch.

  4. From the context menu, choose Generate Patch.

The Select Patch Context dialog may open. For help while using this dialog, press F1.The Generate Patch dialog opens. Complete the dialog as required. For help while using the dialog, press F1.

6.8.3.2 How to Apply Patches

You may wish to record the changes between two revisions of a file, then apply those changes to a third file. You do this by creating a patch and then applying it.

To apply a patch:

  1. In the navigator, select the resource to which you want to apply a patch.

    The resource can be an application, a project, or a source file.

  2. Select Versioning > Apply Patch.

    If you chose to apply a patch to a project, the Select Patch Context dialog opens, through which you should specify whether you are applying a project file (.jpr) patch, or whether you are updating the contents of a project.

    The Apply Patch dialog is opened.

  3. In the grid at the top of the Apply Patch dialog, check that the target resources are correctly identified.

  4. Choose the source of the patch. For more information about this and the other options on the dialog, press F1.

  5. Click Preview. This opens the Apply Patch Preview window, in which you can accept or reject particular changes. For more information about the options in the Apply Patch Preview window, press F1.

  6. To apply the patch, click OK.

6.9 Using WebDAV with JDeveloper

Web-based Distributed Authoring and Versioning, or WebDAV, is an extension to HTTP which allows users to edit and manage files on WebDAV-enabled servers in a collaborative fashion. WebDAV connections in JDeveloper allow you to view files hosted on WebDAV servers in the same way as you would files on the local file system. Files located on WebDAV servers, accessed using WebDAV connections in JDeveloper, can be viewed in the same way as files stored on the local file system or LAN.

As WebDAV clients provide access using HTTP, files can be accessed through firewalls (configured to support WebDAV extensions) that would otherwise prevent FTP file transfer. The JDeveloper read-only implementation of WebDAV supports the current WebDAV 1.0 standard, which does not support versioning. As a WebDAV client, JDeveloper can connect directly to any Oracle Internet File System, allowing you to view WebDAV files from the database.

6.9.1 WebDAV Server Requirements

You must run a WebDAV server to use JDeveloper as a WebDAV client. The WebDAV server must be one of the following:

  • Oracle Internet File System 8.1.7 (or above)

  • Apache 1.3.19 (or above)

    Note:

    If the Apache server is version 1.x, the mod_dav module must also be installed.

  • A server that conforms to the WebDAV 1.0 standard

Note:

If you access the Internet through a firewall, it must be configured to process the extended HTTP commands used by WebDAV.

If your web server is configured to redirect URLs to a different server (for example, if you are using JkMount in Apache to redirect requests for certain file extensions to Tomcat), be aware that WebDAV will not be available for those resources if the server you are redirecting to does not support WebDAV in that context.

If you'd like to find out more about WebDAV, see the following Web sites:

  • http://www.webdav.org

  • http://httpd.apache.org/docs-2.1/mod/mod_dav.html

6.9.2 How to Create a WebDAV Connection

WebDAV connections created in JDeveloper allow you to view files and folders as part of a JDeveloper project.

Note:

The same URL cannot be used for more than one WebDAV connection on the same JDeveloper client.

To create a WebDAV connection in JDeveloper:

  1. In the New Gallery, choose General > Connections > WebDAV Connection, then click OK.

  2. Use the WebDAV Connection dialog to create a connection.

    For more information while using the dialog, press F1.

6.9.3 How to Access a WebDAV-Enabled Server Via a Proxy Server

If you access the internet via a proxy server you need to configure JDeveloper before accessing WebDAV-enabled servers on the internet.

To access a WebDAV-enabled server via a proxy server:

  1. Check with your network administrator to ensure that your proxy server is WebDAV-enabled.

  2. In JDeveloper choose Tools > Preferences, click Web Browser and Proxy in the left pane of the Preferences dialog box, make sure that the Use HTTP Proxy Server checkbox is checked, then enter the details for the proxy.

  3. If the WebDAV-enabled server you want to access is inside your firewall and you do not need to go through your proxy server to access it, add the name of the WebDAV server to your default web browser's proxy exceptions list. This is normally set on the browser's preferences/settings page with the other proxy settings.

6.9.4 How to Modify a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Application Navigator, listed under the Connections node.

Existing WebDAV connections can be modified.

To modify a WebDAV connection:

  1. Right-click the WebDAV connection that you want to modify.

  2. Choose Properties.

  3. On the WebDAV Connection Properties dialog, change the details of the WebDAV connection.

    For help while using the dialog, press F1.

  4. Click OK.

6.9.5 How to Refresh a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Application Navigator, listed under the Connections node.

To ensure that the folders and files accurately reflect the current contents of the WebDAV server, you can manually refresh the display of a WebDAV connection.

Note:

All folders and files listed for the WebDAV connection are refreshed. The properties of the folders and files, and their contents, are refreshed.

To refresh the entire contents of a WebDAV connection:

  1. Right-click the WebDAV connection that you want to refresh.

  2. Choose Refresh.

6.9.6 How to Delete a WebDAV Connection

WebDAV connections are shown in the Application Resources section of the Application Navigator, listed under the Connections node.

Deleting a WebDAV connection from JDeveloper does not affect any of the files or folders on the WebDAV server itself.

To delete a WebDAV connection:

  1. Right-click the WebDAV connection you want to delete.

  2. Choose Delete.

You can subsequently recreate the connection, in which case the files and folders that were part of it will be shown beneath it again.