Oracle ADF Development Essentials: Part 1


Version Control with Subversion: Creating a Repository for Single-User Projects


Learn about using the open source version control system Subversion to manage your Oracle JDeveloper 11g projects, whether you’re working on your own or as part of a team.
In this installment , learn how to create a repository and start using Subversion for version control in a single-user environment.

By John Stegeman 

Published December 2008

Downloads:

Have you ever worked on a document, perhaps a term paper for school, and saved multiple copies over time so you could go back to an earlier version? Perhaps you’ve done the same thing in a programming project in which you saved multiple copies of your source code as you made changes, in case something went wrong, so you could go back to a prior stable version. If you’ve done either of these things, you’ve used a rudimentary form of version control.

For anything but the most trivial projects, however, you will quickly outgrow this simple method. You’ll also find this rudimentary method lacking if you work in a team environment where changes need to be shared among team members as well as tracked over time.

Development projects have been using formalized version control systems as a best practice for quite some time. Version control systems have several benefits for individuals as well as teams:

  • Different revisions of artifacts (source code files, documents, images, and the like) can be tracked over time; furthermore, old versions of the artifacts can be retrieved easily.
  • In a team environment, a repository of versioned artifacts can be made available to the entire team.
  • Information about each revision (metadata and comments) is available for annotating revisions.

Even for simple, single-developer projects, there are significant benefits to using a standard version control system. This article shows you how to get started on using a popular version control system (Subversion) with Oracle JDeveloper 11g.

Why Subversion?

Many version control systems are available today, both free and pay-to-use. Some you may have heard of are CVS, git, Microsoft Visual Source Safe, Perforce, Rational ClearCase, and Serena Dimensions, to name just a few. With all the available choices, why would you choose Subversion? Here are some of the reasons I selected Subversion for my Oracle Application Development Framework (Oracle ADF)-based projects:

  • It’s free. A former coworker of mine used to say, “If it’s free, I can’t afford it,” but Subversion is one piece of free software that actually works well.
  • It’s widely adopted and recognized as an industry-leading solution. A recent Forrester Research report showed Subversion as the sole leader in the sector.
  • Oracle JDeveloper 11g supports it. Although you can use any version control system with Oracle JDeveloper by using the system’s native client for interaction, having the experience integrated with the IDE makes things a lot easier.
  • All commits in Subversion are atomic. When you “commit,” or “check in,” your changes to the Subversion repository, either all of your changes will commit successfully or none of them will. This is especially important with Oracle ADF projects in which a logical object (such as an Oracle ADF business component) can be composed of multiple physical files. If commits were not atomic (as in CVS, for example), a glitch in network connectivity could leave some of the files for a logical object updated and others not—resulting in an unusable set of code.
  • It supports directory versioning as well as files. Addition, deletion, and moves of directories are tracked just as the same operations for individual files are.
  • It supports difference-based tracking for both text and binary files. Most version control systems store just the differences between different revisions of text files; Subversion can do this for binary files as well, meaning a decrease in the disk space needed for the repository.

Subversion Concepts

Because different version control systems use different terminology and, in some cases, different approaches to managing revisions, let’s explore a few key Subversion concepts:

A repository is a central location Subversion uses to store files and their revisions over time. Whereas some version control systems, such as git, provide a decentralized repository, Subversion uses a centralized approach.
A working copy is a local copy of some of or all the files from the repository that has been brought from the repository to the user’s local machine for modification. The process of obtaining a working copy from the repository is called “checking out.”

Subversion uses a copy-modify-merge paradigm for dealing with changes in a team environment. Some other version control systems use a lock-modify-unlock paradigm, wherein users must lock a file to modify it and unlock it when they are finished with their modifications. Although Subversion supports this approach, it’s normally used only with binary (nontext) files. With Subversion, multiple users can make changes to a file at the same time; in such cases, the multiple changes are merged (either automatically or manually).

An excellent free e-book is available for download that explains these concepts in more detail.

Installing Software and Setting Up a Repository

Before you can start using Subversion to store the revisions of your application, you need to set up a repository and provide access to it. Subversion provides three main ways to access a repository:

  • Through a local file system (the file: protocol)
  • Through a proprietary svn: network protocol
  • Through an Apache HTTP server configured with the appropriate modules (mod_dav and mod_dav_svn)

Although Oracle JDeveloper provides support for creating local repositories and accessing them via the file: protocol, this method isn’t very useful unless you are the only developer working on your project. The most common access method for Subversion repositories is via the HTTP/HTTPS protocols, using Apache. To create a repository and serve it up via Apache, you have to install and configure some software or connect to an existing Subversion repository. For some of my Oracle ADF projects, I have used commercial Subversion hosting services that provide a Web interface to create and administer repositories; this can be a convenient option, because the hosting firm will take care of backup for you and often provides integration with issue tracking software as well.

If you want to create your own repository, you will need to install and configure the Subversion software as well as Apache and the required modules. Many Linux distributions come with Subversion and Apache already configured. For Microsoft Windows, a company called VisualSVN has created a Windows installer for installing the Subversion software, a preconfigured Apache HTTP server, and an easy-to-use administration console. Although you can certainly install Subversion and an Apache HTTP server separately and use the command-line repository administration tools to create a repository, using the VisualSVN Server ( www.visualsvn.com/server ) is a quick way to get started.

The installation of VisualSVN Server is very straightforward; just download the installer and run it. I’ve included a screen shot of the important part of the setup, wherein you specify where the repositories should be stored, the port for the Apache HTTP server, and where your Subversion server should get its user and group information. I’ve specified options that are appropriate for a standalone installation, using HTTP (not HTTPS), and elected to manage my own users and groups instead of using the Windows users and groups:

Figure1

The installation takes only a few moments and creates a Windows service called Visual SVN Server. At the end of the installation, you’ll be given the option to start the VisualSVN Server Manager:

Figure2

VisualSVN Server Manager, you should see Repositories, Users, and Groups nodes. For this article, I created a repository called otn, by simply right-clicking the Repositories node and choosing Create New Repository... from the context menu:

Figure3

In the Create New Repository dialog box, simply fill in the repository name and check the check box to create the default repository structure (more on that in a minute):

Figure4

That’s all there is to creating your first Subversion repository! If you expand the otn repository in the VisualSVN Server Manager, you’ll see three directories: “trunk,” “branches,” and “tags.” This three-folder top-level structure is a commonly used convention for structuring Subversion repositories. Although you can use any top-level structure you like, the trunk-branches-tags structure is almost universally used, and I recommend that you follow the convention. The purpose of each of the directories is as follows:

  • trunk – This is where the main line of development takes place; in fact, some people refer to the trunk as the “mainline.”
  • tags – Identifying key points in the release lifecycle of an application involves tagging a specific revision of the code (more on this later). The tagged revisions are, by convention, stored in the tags directory.
  • branches – In anything more than trivial development projects, there will come a time when the source code needs to be “branched,” for any number of reasons (such as developing a new feature without affecting the trunk or for stabilizing the code for release). By convention, branches are created in the branches directory.

To show how Subversion works with multiple users, I also created two users for this article, by right-clicking the Users node in the VisualSVN Server Manager and choosing Create User.... My two users are named john and josephine.

Figure5

Figure6

Figure7

Adding your Application to the Repository (Importing)

Now that you have a Subversion repository, you can place your application under version control in your new repository (a process known as importing). Oracle JDeveloper provides a GUI interface to make this task quite easy. For this article, I’m using the simple Oracle ADF Fusion Web application with the standard two projects (Model for the Oracle ADF business components and ViewController for the UI); if you’d like to follow along, you can download the application from the link provided in the “Resources” section at the end of this article.

To place the application under version control, ensure that the application is the current one selected in Oracle JDeveloper; then select Version Application... from Oracle JDeveloper’s Versioning menu:

Figure8

When prompted, select Subversion as the repository type:

Figure9

If you don’t already have any Subversion connections defined, Oracle JDeveloper will prompt you to create a Subversion connection. If you already have one or more Subversion connections defined, you’ll be given a list of repository connections to choose from. For this article, I hadn’t defined any connections yet, so Oracle JDeveloper prompted me to create one. To create the Subversion connection, you need to know the repository URL. To get the URL by using the VisualSVN Server Manager, simply right-click the repository and choose Copy URL to Clipboard from the context menu:

Figure10

You can then paste the URL into the JDeveloper dialog box. After providing a username and a password, you can click Test Read Access to make sure everything is set up properly:

Figure11

The next step in importing your application is to specify which directory in the repository is to hold the application. As per our earlier discussion about the conventional layout of Subversion repositories, the trunk directory is where the main line of development occurs, so that’s the destination of our imported application:

Figure12

The next step is to indicate where the application’s source directory is on your local disk; Oracle JDeveloper usually gets this information right, and you won’t have to change it. Whenever you perform any action against a Subversion repository, it’s a good practice to provide a comment about what you did; the initial import of the application is no exception, so we provide a helpful comment:

Figure13

The next step of the import is to tell Subversion which files and directories we want it to ignore. We don’t usually want generated files (such as class files), temporary files, and so on stored in the Subversion repository, so we need to tell Subversion to ignore them. Without going into great detail about the mechanism, suffice it to say that Subversion uses a special property to identify what should be ignored. Oracle JDeveloper provides a good set of default ignore patterns, although you can add your own by using the Filters dialog box:

Figure14

When you import your application into Subversion, the original files on your local disk remain just a bunch of local files; the local copy has no connection to the repository at all (it’s just a local copy and not a Subversion “working copy”). The normal next step after importing your application is to delete your local copy and check out a working copy from the repository. Oracle JDeveloper gives you a shortcut in the next dialog box, Options:

Figure15

Now you can review the import options summary and complete the import:

Figure16

You can watch the import process progress in the SVN Console Log window of Oracle JDeveloper. Once the import is complete, you should see the progress of the checkout operation (if you checked the check box to automatically perform a checkout after the import). Once the checkout finishes, have a look at Application Navigator (you may need to click the refresh icon first). You should now see a lot more information, as shown here:

Figure17

  • Each project shows the repository from which the working copy originated (jstegema-lap.cisgi.com in this screen shot).
  • Each file has a “state overlay” icon in the lower left, showing the status of the working copy file. In this case, all the icons are circles, indicating that the files have had no local modifications since they were checked out.
  • Each file shows its version number (2 in this screen shot). The files are at version 2 (and not 1) because the creation of the repository was version 1 and the import of the application was version 2.

Making Local Changes and Committing Them to Subversion

The local copy of the application is now a Subversion “working copy,” meaning that the copy is associated with the subversion repository. Subversion maintains this association through the use of hidden directories in the working copy named .svn, as shown below:

Figure18

You shouldn’t alter the contents of the .svn directories, because they are maintained automatically by Subversion.

Now that our application is under version control, let’s make some changes to the application and save them to the Subversion repository. We make a simple change to the Regions entity object (EO) in the Model project to set its tuning properties for update batching:

Figure19

After making the change and saving the EO, you’ll notice a few changes reflected in Oracle JDeveloper. First, the state overlay icon for the Regions EO has changed to an asterisk, telling us that we have local changes that have not been saved (or “committed”) to the Subversion repository:

Figure20

Second, if you view the Subversion Pending Changes window:

Figure21

you’ll see the Regions.xml file you modified listed as an outgoing change:

Figure22

The Pending Changes window is a handy place to see which files in your current application have been changed in your working copy (Outgoing), which new files have been created in your working copy but not added to Subversion (Candidates), as well as what changes have been made in the Subversion repository by someone else but not applied to your working copy (Incoming). For now, because I am the only developer working on the application, there are no incoming changes, just the one outgoing change.

Next, I’ll complete my set of changes by setting the same tuning property for the Employees and Jobs EOs in the project. Once I’ve done that, the state overlay icons and Pending Changes window reflect that I have uncommitted local modifications in three files:

Figure23

Figure24

Now that I’ve made my changes, I’m ready to commit them to the repository. I’ll do that by committing all of the changes in my working copy, using Application Navigator’s shortcut menu:

Figure25

When I select Commit Working Copy..., Oracle JDeveloper prompts me to enter a comment. As we know, we should always provide a helpful comment so that the project team can see, at a glance, the changes that were made:

Figure26

After the changes are committed, the SVN Console - Log shows what was done:

Figure27

The state overlay icons also change back to filled circles to indicate that there are no uncommitted local modifications. The version number of the files I committed has also been incremented to show that the files are at version 3:

Figure28

The Pending Changes window shows no outgoing changes (we have committed all the local changes):

Figure29

Conclusion

You now have the information you need in order to start using Subversion with Oracle JDeveloper 11g in a single-user environment. The next article in this series will explore how things change when you add other developers into the mix and start making changes simultaneously.

Go to Part 2 | Back to TOC

 

More Good Stuff


John Stegeman ( http://stegemanoracle.wordpress.com) is an Oracle ACE director (Oracle Fusion Middleware) and the principal architect in the EMEA region for Cambridge Solutions, a global BPO and IT services firm. He has been working with Oracle products since 1990 and with Oracle JDeveloper since version 3.