| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide 10g Release 3 (10.1.3.0) Part Number B28967-02 |
|
|
View PDF |
The source control system used for the SRDemo application was CVS. This chapter contains advice for using CVS with ADF projects, and general advice for using CVS with JDeveloper.
This chapter includes the following sections:
This section contains advice specifically for using CVS with an ADF project, for example the SRDemo application.
A CVS client lets you import your work into CVS or check it out from CVS control. The CVS client can be a standalone program, or it can be integrated into an IDE, as it is with JDeveloper. The SRDemo application was created using the JDeveloper internal CVS client.
You set up JDeveloper to use CVS by ensuring that Support for CVS n.n is checked on the Extensions preferences page (Tools > Preferences |Extensions | Versioning Support n.n | Configure) and that CVS is selected from the dropdown list on the Versioning preferences page (Tools > Preferences | Versioning).
Preferences for using CVS are set by selecting Tools > Preferences |Extensions | Versioning | CVS and its subpages.
The SRDemo application was created using the default preferences for CVS, although you may want to consider setting the timeout to ten minutes (Operation Timeout on the General subpage), especially if you have a slow connection to a remote server.
JDeveloper will work with the CVS version control system to keep files within a multi-file component synchronized, for example, by automatically checking out all the files that are dependent on a file that you expressly check out. However, when working with Oracle ADF-base JSP pages, you should be conscious of the dependencies between the various, related artifacts.
For example, when you commit a JSP page like SomeName.jsp, if changes you made in JDeveloper have caused the associated SomeNamePageDef.xml file to be modified, it will also appear in the Outgoing page of the Pending Changes window. On the other hand, if SomeName.jsp is a new JSP page on which you've dropped some databound controls, its associated SomeNamePageDef.xml file will also appear in the Candidates page of the Pending Changes window, and the DataBindings.cpx file will appear as a modified file in the Outgoing page. By understanding these relationships, you can better decide which files need to be committed together as part of the same CVS transaction to ensure that other developers who update their project from the source control server receive a consistent set of related files.
Most JDeveloper and ADF objects will be created only once per project and will by definition have the same name regardless of who sees or uses them. However, some objects like database connections could theoretically be left to the creativity of each team member in their own JDeveloper environment, even though they map to the same connection details. Avoid such naming differences for otherwise common connection definitions when working with ADF under version control since the discrepancy will cause unnecessary differences in your data-sources.xml files. Team members should agree up front on a common, case-sensitive connection name and that should be used by every member of the team.
In general, you should commit your work after it has been tested and are satisfied that it is working. The longer you work on a set of components without testing the changes and checking them in, the greater the chances that other developers will have modified them too, resulting in merge conflicts and the need to resolve them.
Make sure to have an active CVS connection open in the CVS navigator when you are performing any kind of renaming or refactoring operations. If you do so, these will be automatically handled as appropriate file deletes and adds in the source control system. If you are not in the context of a CVS connection when you make these kinds of changes, then the next time you connect to source control, your renamed files may inadvertently show up as new files.
When renaming files (for example, through refactoring), you should commit the files as soon as practicable after you have renamed them. This is because renaming a file through JDeveloper involves a CVS delete operation and a CVS add operation, and an added file needs to be committed to make it available to other developers. However, you should still test the changes before committing them. A typical scenario would be to refactor the files, then rerun the unit tests, then commit the files.
When developing new features, you may have to depart from the normal rule of unit testing files before committing them, if other members of the team need to work on the files in order to complete the unit of work that is to be tested. In this case, the files will need to be committed before testing so that other members of the team can obtain them from the CVS repository.
When committing work to CVS, always add comments describing the changes you have made. You add comments in the Comments box of the Commit to CVS dialog (Versioning > Commit).
It is preferable to perform, at regular intervals, a clean checkout from the CVS repository to a fresh directory (using Versioning > Check Out Module). Simply updating your working copy from the repository (using Versioning > Update) can hide problems such as incomplete commits.
You could use Apache Ant, which is integrated into JDeveloper, to create a script that will automatically check out the full source and build it. If the build completes successfully, this will be confirmation that everyone has committed all the changes required to make the system perform correctly. Otherwise, the build will break and problems will be signalled. To find out how to use Apache Ant to create build scripts, search for "About Ant Integration in JDeveloper" in the JDeveloper online help.
If you manually add navigation rules to the faces-config.xml file (using the XML view or the Overview screen), you must switch to the visual diagram view of faces-config before checking in the faces-config.xml file. Doing so will cause the diagram file (faces-config.oxd_faces) to register the metadata change and force it to reflect the rule change. It also ensures that the faces-config.oxd_faces file is marked for commit and that the two files will not get out of synchronization.
If you don't do this, the diagram file will no longer be in step with the XML metadata and will give errors. If this happens, the solution is to manually delete the diagram file and let JDeveloper re-create it when it next attempts to open the file. That file is \model\public_html\WEB-INF\faces-config.oxd_faces under the userinterface/viewcontroller project.
This section contains advice for using CVS with JDeveloper generally.
Divide the development work between several projects.
Consider using a code formatter, possibly as part of an Apache Ant build script. JDeveloper's code formatter is available from the Code Style page of the Preferences dialog (Tools > Preferences | Code Style). You can use this to create and export a standard format that all team members can import, thus allowing them to share the same built-in code formatting rules.
Build the code before checking it into CVS and before doing a CVS update.
Consider running a continuous integration tool. The tool should rebuild the whole project whenever someone commits changes to the CVS repository and should notify developers when code they have committed breaks the build by requesting that the code be fixed. Running a continuous integration tool will improve confidence in the quality of the code in the CVS repository, encourage developers to update more often, and lead to smaller updates and fewer conflicts. An example of a continuous integration tool is Apache Gump (http://gump.apache.org/).
Before importing modules, configure the CVS repository to import binary file types as binary (rather than as text), to prevent them from being corrupted.
This section contains advice for developers working with files under CVS control.
Always perform an update (Versioning > Update) or module checkout (Versioning > Check Out Module) before you start editing files to make sure that you are working with the most recent versions.
While you can commit your work one file at a time using the Versioning > Commit menu option, Oracle recommends using the Pending Changes window. To show this window, choose Versioning > Pending Changes from JDeveloper's main menu. When working in a team, before committing the files you've been working on, you will typically use the Pending Changes window in the following sequence:
Use the Outgoing Page to add new files to source control.
First, use the Outgoing page to see all of the new files you've created in the current workspace. To be sure the list is as up to date as possible, click the Refresh icon in the page toolbar. Decide which of the new files should be added to source control, and select all of these. Finally, use the Add option on the context menu to add the selected files to source control. The longer you work on a set of components without testing the changes and checking them in, the greater the chances that other developers will have modified them too thereby resulting in merge conflicts and the need to resolve them.
Tip:
Do not commit the
WEB-INF\temp directory because this is a directory containing cached images that ADF Faces generates once on demand at runtime.Use the Incoming Page to update workspace files from other team members.
Second, use the Incoming panel to review whether any changes made by other developers on your team might affect the work you're about to check in. If other team members may have created files in new directories that you do not yet have in your copy of the project, use the Update Project Folders option on the context menu of the workspace or on an individual project to ensure your local working area reflects those new directories. Again, you should click the Refresh button to ensure that you're seeing the most up-to-date list of incoming files. If team members have changed files unrelated to your work, you can choose to update your copies of those files if useful to you for testing. If they have changed files that are the same as ones you have modified, then JDeveloper will show the incoming status as conflicts on merge. You need to update the files and address any merge conflicts before the CVS server will allow you to check in.
Resolve any merge conflicts if necessary.
After performing an update that encountered merge conflicts, JDeveloper displays an exclamation point next to each conflicting file in the Application Navigator. Also, in the Pending Changes window's Outgoing page the outgoing status will be shown as conflicts. You can resolve the conflicts using JDeveloper's built-in merge tool. Right-click the file and choose Resolve Conflicts from the context menu. Three versions of the file will be shown: on the left will be the version in the CVS repository, on the right will be the current local version, and in the middle will be an editable version that represents the result of the merge. Symbols in the margin between the three panels indicate the suggested action for resolving each conflict.
By selecting an appropriate icon in the margin and using the context menu, you can insert changes from the file on the left side or the right side after the adjacent difference.
Tooltips explain the suggested action of each conflict. You can accept the suggested actions or edit the text directly. To complete the merge, you must save the changes that have been made, using the Save button in the merge window's toolbar. If this is not enabled, you may need to use the Mark as Resolved or Mark All As Resolved options in the context menu. Once you've saved the merged version of the file, the merge tool window becomes blank and JDeveloper removes the conflict symbol from the navigator icon and you will be able to commit the merged file to the CVS repository. You can close the merge tool window and proceed to the next conflict, if any.
Use the Outgoing Page to commit your changes.
Finally, use the Outgoing page of the Pending Changes window to commit your changes to source control. There may be some files that are modified but which you don't want to commit. For example, each time you run your application on the embedded OC4J server, JDeveloper may refresh the contents of your project's data-sources.xml and/or jazn-data.xml file. You may not want to keep checking in modified versions of these each time. In addition, there may be files you modified, but whose changes you don't wish to keep. As you can do at any time, you can choose Versioning > Undo Changes from the context menu for such a file in the Application Navigator. This will revert the file to the latest checked-in version in source control. Finally, select the files you want to check in, and choose Commit on the context menu.
Tip:
Be aware that the Commit All button on the toolbar of the Pending Changes window will commit all files in the Outgoing list. Use the technique described above to commit selected files.To prevent accidental corruption of the CVS repository, do not change repository configuration files manually. If you need to change a CVS configuration file, check out CVSROOT as a module, modify the specific configuration file locally, and then commit it to the repository.
