Version Control for ADF-JHeadstart Applications

We are currently very busy with a major rewrite of the JHeadstart Developer's Guide for the upcoming JHeadstart release. Not only will we document  the numerous new features, we also take the opportunity to add chapters and sections that discuss many frequently asked questions over on the JHeadstart Discussion Forum. One such popular topic is team-based development. A whole new chapter will be devoted to this topic, including a section on version control. Since the content of that section includes useful information for versioning ADF applications in general, and is independent of ADF and JHeadstart versions, we will share a preview of it with you through this blog post.

The following topics are discussed:

  • Version control models
  • Requirements for a good version control system
  • Which files to version?

Version Control Models

When selecting a version control system, you have to
choose between two basic models of version control: file locking and version merging.
Wikipedia provides the following definitions for these two models
  • File Locking: The simplest method of preventing concurrent
    access problems is to lock files so that only one developer at a time has write
    access to the central "repository" copies of those files. Once one
    developer "checks out" a file, others can read that file, but no one
    else is allowed to change that file until that developer "checks in"
    the updated version (or cancels the checkout).

    locking has merits and drawbacks. It can provide some protection against
    difficult merge conflicts when a user is making radical changes to many
    sections of a large file (or group of files). But if the files are left
    exclusively locked for too long, other developers can be tempted to simply
    bypass the revision control software and change the files locally anyway. That
    can lead to more serious problems.
  • Version Merging: Most version control systems,
    such as CVS and SubVersion, allow multiple developers to be editing the same file
    at the same time. The first developer to "check in" changes to the
    central repository always succeeds. The system provides facilities to merge
    changes into the central repository, so the improvements from the first
    developer are preserved when the other programmers check in.

    concept of a reserved edit can provide an optional means to explicitly
    lock a file for exclusive write access, even though a merging capability

For developing applications using JDeveloper, ADF and JHeadstart,
we recommend to use the version merging model, for the following reasons:

  • It is a file-oriented development environment. Even for
    small to medium-sized applications, you will easily have hundreds of files to
    manage. It is inevitable that at some point multiple developers need to modify
    the same files. Using the file locking
    model this means that developers will have to wait for each other to finish
    a task and check in again. Although the number of  �locking conflicts� can be
    reduced by a smart distribution of development tasks, it is our experience that
    you can never entirely avoid it.
  • The files that most often are modified simultaneously
    by multiple developers are XML files, which by its structured nature are very
    well suited for automatic merging by version control systems. It is our
    experience that a version control system like SubVersion is also very good at
    merging Java files, the other most used type of file in this development environment.
  • When generating your application using JHeadstart, many
    files are modified during a generation run. When using the file locking approach,
    you need to know upfront which files will be modified by the JHeadstart
    Application Generator: all these files need to be checked out prior to
    generation, otherwise they remain read only and will not be modified by JHeadstart.
    It requires in depth knowledge of JHeadstart and ADF to be able to correctly �predict�
    which files will be modified in a specific generation run.  With the version merging approach this is not
    an issue, once you have finished a development task, the version control system
    will tell you which files have been modified and need to be committed to the
    version control repository.

Requirements for Good Version Control

When selecting a version control system, make sure the
system provides functionality to address the following requirements:
  • It supports the Version Merging model (see
    previous section).
  • It provides a so-called Atomic Commit. With this we mean that when you have modified
    a number of files that you want to commit to the version control repository,
    you want either the entire transaction to be committed, or the entire
    transaction to be rolled backed when a version conflict is detected which
    cannot be solved by an automatic merge. In other words, either all files are
    committed succesfully, or none of the files are committed. A version control
    system like CVS does not support an atomic commit. This means that some files might
    be committed to the repository, and then a version conflict is detected and the
    rest of the files cannot be committed. When this happens, you end up with an
    inconsistent situation in your version control repository since there are many
    interdependencies between files in an ADF environment. Obviously, when other
    developers update their local copies with this inconsistent set of files, they are
    likely to run into all sorts of problems and error messages.
  • It detects file changes by comparing file content
    rather than the timestamp of the file. This requirement is particularly
    important when using JHeadstart: when you regenerate your application using the
    JHeadstart Application Generator, the content of many files might remain the
    same, although the file is recreated with a new timestamp.  When you commit your work after you completed
    a development task, you do not want a new version of all these unmodified files
    to be committed to the repository. Otherwise, it will be really hard to find back
     versions that contained a real change, being
    a version you might want to revert to when you want to undo some work.
  • An efficient and easy to use user interface to perform
    common versioning tasks. Developers should spend as little time as possible
    with version control tasks. An intuitive user interface for common tasks like
    updating their local copy, committing changes, reverting to previous versions,
    resolving merge conflicts, and creating application releases is essential to
    meet this requirement. Ideally, the versioning user interface is integrated
    with JDeveloper, although in our experience it is not a big deal to switch with
    Alt-Tab to a stand-alone GUI for versioning when JDeveloper integration is not
    available, or less feature-rich.
A popular open source version control system that meets
all of the above requirements is SubVersion (also known as SVN) . SubVersion
has been built by the same community that is responsible for CVS. It is
intended as a replacement for CVS, keeping all the good things of CVS, and fixing
the bad things (like the absence of an atomic commit).

TortoiseSVN is an excellent stand-alone SubVersion GUI for
the Windows platform, nicely integrated with MS Windows Explorer.  JDeveloper integration is also available.

The JHeadstart team has successfully used SubVersion and
TortoiseSVN on a number of projects, see also the JHeadstart blog post "Managing Your Project Files: Using Subversion". This does not imply you should make the
same choice. Version control is no rocket science, any system that meets the
above requirements will do the job.

Which Files to Version?

We recommend to version all files in your project, except

  • derived files like all compiled Java classes and XML and
    property files that are copied to the classpath. In SubVersion, the easiest way
    to exclude these files is by adding the root directory of the classpath
    (typically  the /classes directory) to
    the ignore list. This can be done by a right-mouse-click on the folder, and then
    choose Tortoise SVN -> Add to Ignore List �
  • files in the temporary directory created by ADF Faces. When
    running your application in JDeveloper, a /temp directory is created under
    the WEB-INF directory, which holds cached ADF Faces files like images and
    stylesheets. This directory is not required to run your application and does
    not need to be versioned.
  • the files created by JDeveloper in the root:
    appname-data-sources.xml, appname-jazn-data.xml, appname-oc4j-app.log,
    appname-oc4j-app.xml and application.log. If you are using JAAS-JAZN authorization,
    you do might want to version appname-jazn-data.xml since it holds the users and
    roles you have defined in JDeveloper for the project.
  • the faces-config diagram files, with extension �.oxd_faces�.
    When generating your application with JHeadstart, the faces-config diagram
    typically looks rather messy, so unless you spend some time in cleaning up the
    diagram, it doesn�t make a lot of sense to version these files. They are
    usually created in a separate folder (/model by default), so you can exclude the
    whole folder from versioning.
Hint: when using TortoiseSVN, the �Add to Ignore List�
option in Windows Explorer is only available on unversioned folders directly
below a versioned folder.  When committing
a project for the first time, it is easier to exclude folders using the right-mouse-click
popup menu in the Commit dialog.


Thanks for yet another very useful post. If possible, can you also post something on what's better way to migrate existing project from CVS to SVN. Also, to add to the 'Which Files to Version?' section: When workspace level datasource is used, we need to commit the appname-data-sources.xml file as-well. An better alternative to version controlling the appname-jazn-data.xml and appname-data-sources.xml, is to create a custom deployment descriptors from jDeveloper using the OC4J Deployment Descriptors Wizard, and then version them instead.

Posted by rutwik on August 27, 2007 at 08:51 PM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed

Java EE Consultants - JHeadstart, ADF, JSF


« July 2016