Using and hacking Subclipse - the Subversion plugi

Using and hacking Subclipse - the Subversion plugin for Eclipse
by
Eugene Kuleshov
11/30/2005
Abstract
Subversion
(SVN) is a version control system that is a compelling replacement for CVS. It supports several important features missing in CVS, such as versioned renames, directories, and metadata; and atomic commits and remote access over HTTP/HTTPS. Many open-source projects, including projects hosted on BEA's dev2dev
CodeShare
site, use Subversion as a version control system. There is a short guide on how to set up a command-line SVN client and Tortiose SVN for Windows for CodeShare. However, it would make sense to work with Subversion repositories right from your IDE.
This article describes how to use Subversion with the Eclipse IDE. In particular, it examines the installation and use of the
Subclipse plug-in
. Along the way, I also show you how to use the resulting configuration to modify or extend the Subclipse plug-in itself.
Installing Subclipse
The best way to install Subclipse is to use the Eclipse Update Manager. In Eclipse 3.1 it is located under the Help -> Software Updates -> Find and Install... menu. Select Search for new features to install, and add New Remote Site using http://subclipse.tigris.org/update as the URL.

Figure 1. Install Subclipse using the Eclipse Update Manager.
After scanning for updates, you'll see a list of available features. Subclipse 0.9.33 was the latest update at the time I wrote this article.

Figure 2. Select the latest update of Subclipse.
On the next screens you will be asked to accept the license and to choose an installation location. I recommend that you don't install new plug-ins (including Subclipse) into the default Eclipse installation directory. It is better to put these plug-ins into an external extension location. This makes it easier to manually uninstall these features if needed, and also makes possible the sharing of plug-ins between multiple Eclipse installations, such as release, early access stable (M1, M2, and so on) and integration IDE builds.

Figure 3. Choose an installation location.
At this point the Update Manager downloads and installs the selected features and asks you to restart Eclipse.
Once Eclipse has restarted, you'll see a new section for SVN in the Preferences dialog as well as additional views for Subversion activities. These views can be added to the Java Perspective using the Window -> Show View -> Other... menu.

Figure 4. Add views for Subversion activities.
I usually add the SVN Repository view to Quick Views and SVN Resource History to one of the tab groups at the bottom of the work area in a Java Perspective. By doing this, they're both nearby and available during development activities. This also makes it convenient to use drag-and-drop to run some tasks like "get resource history" (from the resource-oriented views such as Navigator, Package Explorer, SVN Repository, and Synchronize to the SVN Resource History view).
Configuring an SVN Interface in Subclipse
You can configure Subversion servers to use one of the following protocols:

• The svn protocol is a lightweight, stateful protocol used by standalone Subversion servers (svnserve). The secure version, svn+ssh, uses ssh-based tunneling.
  
• The http protocol is based on a WebDAV extension and usually is deployed as a module on Apache HTTP server. The secure version uses https, and this is the protocol used by the Subclipse installation on dev2dev CodeShare.
  
• The file protocol is used to access locally available Subversion repositories (for example, one on the shared drive) and is the least efficient option.

Subclipse uses special adapter abstractions to work with the above protocols. One of the following adapters can be selected in plug-in properties at the Window -> Preferences -> Team -> SVN dialog.

Figure 5. Select an adapter.
Each adapter has its own advantages:

• 
  JavaSVN
  is the only entirely Java-based Subclipse client, and is enabled by default. Note that JavaSVN does not support the file:/// protocol.
  
• JavaHL is a thin wrapper around the native Subclipse API. This adapter is prebuilt for Win32 platforms but has to be built manually on all others (unless your Unix distribution includes it).
  
• The command-line adapter should be used only if JavaHL can't be installed, and your Subclipse repository uses the file:/// protocol.

In most cases you can stay with JavaSVN and choose the JavaHL or command-line adapter only when needed. Links in the
Resources section
can help to resolve specific cases, such as configuring an HTTP proxy, SSL client certificates, and so on.
Connecting to an SVN Repository on CodeShare
At this point you can connect to Subversion repositories. For projects hosted on dev2dev CodeShare, you'll find a repository URL on the access options page available from the Version control project menu.
Here is an example
. The CodeShare SVN server requires the same user name and password you use for the dev2dev site.

Figure 6. Connect to Subversion repositories.
If the connection parameters are correctly set, you'll see an SSL certificate confirmation dialog.

Figure 7. Accept the SSL certificate.
After accepting the certificate you should be able to browse the repository and check out existing projects.

Figure 8. View existing projects in the SVN repository.
You should now be ready to start using Subversion and the Subclipse plug-in!
Checking Out Existing Projects From SVN
As you can see in an SVN Repository view, a common layout can be found in many CodeShare projects as well as other projects using Subversion. They often look something like this:
  https://xjms-ra.projects.dev2dev.bea.com/svn/xjms-ra
   +-- branches
       +-- www
       +-- xjms-ra
           +-- mqseries (work in progress)
           +-- activemq
   +-- tags
       +-- xjms-ra
           +-- 0.0.1 (stable versions or releases)
           +-- 0.0.2
   +-- trunk
       +-- www     (project web site)
       +-- xjms-ra (project source)
A trunk folder contains the mainline development source; a tags folder contains stable snapshots or releases; and a branches folder contains code from alternative lines of development. In Subversion, tags and branches are just a versioned copy of the selected source snapshot. Refer to the
Subversion book
for more details.
You can select the trunk or a specific tag or branch for a current project in the SVN Repository view and choose the Check Out As... action from the pop-up menu. You will then be guided through a standard New Project Wizard that allows you to choose project type (for example, Java or Simple Project), project name and location as well as configure the Java build path if necessary.
Configuring an SVN Repository for a New CodeShare Project
The version control repository is an important part of any project infrastructure. For open-source projects (including those hosted at CodeShare) it also plays a key role in the communication between developers and other community members. For example, it allows end users to contribute patches to the most recent code and provides an early update mechanism for important fixes. Because of this role, it is important to configure the SVN repository for a new project and put all project code under version control from the very beginning.
When a new CodeShare project is created, the SVN repository contains trunk, tags, and branches folders, as well as a www module under trunk, which contains an index.html file for a project Web home page. You can verify that in SVN Repository view and create missing folders using actions from a pop-up menu in this view.
Let's assume all source code, build scripts, documentation, and other project resources are organized as an Eclipse project. Then you can use the Team -> Share Project... action from a pop-up menu on a Package Explorer or Navigator view. The Share Project Wizard will let you select the SVN repository type, and then on the next page you can choose one of the existing repositories or configure a new one.

Figure 9. Select the SVN repository type in the Share Project Wizard.
On the next screen you should specify a module name. Since we should create modules under the trunk folder in order to match the CodeShare project layout, specify trunk/ as a module name, such as trunk/xjms-ra.

Figure 10. Specify a module name.
After confirmation, Subclipse creates the module and imports all project files into the SVN repository.
Working With an SVN Repository
When a project is connected to an SVN repository, a Team pop-up menu in the Package Explorer and Navigator views will show all Subversion-specific actions. You can directly run Commit, Update, Add to svn:ignore, and other actions as described in the
Version Control with Subversion
book. The content of this book is also available as part of the Eclipse help system at Help -> Help Contents -> Version Control with Subversion.
The Subclipse plug-in also allows the use of Eclipse's Team Synchronize view, which can give a good overview of what is going to be committed and what has been changed by other developers and needs to be updated from the repository. Most of the SVN commands can be also executed from this Synchronize view.
To add a project or working set to the Synchronize view you can use the Team -> Synchronize with Repository pop-up menu or Synchronize... wizard button located on a main toolbar. If you can't see this button, then Team commands should be added to the current perspective; you can add them using the Customize Perspective dialog available from the pop-up menu on the main toolbar (click any empty space), and then save the perspective under the same name using the Window -> Save Perspective As... menu.

Figure 11. Add command groups to the current perspective.
Choose the Synchronize... action in the toolbar drop-down to start the wizard. On the first screen it again allows you to select the SVN version tracking system and then shows the standard resource selection panel, where you can choose to synchronize an entire workspace, select some set of projects, or use a named Working Set.

Figure 12. Synchronize a workspace, working set, or selected resources.
Once created, the Synchronize view can schedule an automatic refresh with the version control system. This can be configured from the Schedule... menu in a Synchronize view menu. This will help you stay up to date, and allows you to see all incoming changes from other developers.

Figure 13. Schedule automatic refreshes.
Since Subclipse is still evolving, there is a chance you'll run into a bug, or you won't find some features you really want. This brings us to the next topic.
Patching Subclipse
When you run into issues in Subclipse you have several choices. If the issue is a showstopper you can simply decide not to use the product, or wait for the next version. You can also search through the
issue tracking system
and the mail list archives

[[email protected]?subject=][email protected][/email]
and

[[email protected]?subject=][email protected][/email]
with some chance of finding a workaround or explanation of what you are doing wrong. If that does not help, you can politely ask in the mailing list about the issue. If you are interested in trying to solve the problem yourself, then the following paragraphs will give you a brief introduction in how to start debugging and patching Eclipse. However, if you have a serious intention to contribute, it is a good idea to subscribe to the

[[email protected]?subject=][email protected][/email]
mailing list to coordinate your efforts with other developers and align your ideas with the project roadmap.
It is really easy to get started, even if you haven't worked on an Eclipse plug-in before. You'll need to get Subclipse projects into the Eclipse workspace. The Subversion repository for the Subclipse project is located at
http://subclipse.tigris.org/svn/subclipse/
, and you can either use a previously installed Subclipse plug-in or external tools such as a command-line Subversion client or TortoiseSVN to check out the code. It is also a good idea to register on the
tigris.org
Web site and request an Observer role for the Subclipse project. Then you will be able to use the same user name to connect to the Subversion repository ("guest"/"guest" also works fine for read-only access), and you will also have permission to comment on issue tracker (an integrated Bugzilla repository) as well as attach patches to issues (if you've made any).
Once connected to the version control repository you'll need to check out the following projects into your workspace. For each module select Check Out As..., choose a location and project name (I recommend to use the actual plug-in names as in the following table), and click Finish.
Repository Path
Jar or Eclipse Plug-in Name
Description
trunk/svnClientAdapter
svnClientAdapter.jar
For non-Windows or when you need to build svnClientAdapter or JavaHL
trunk/subclipse/core
org.tigris.subversion.subclipse.core
Eclipse-specific plug-in backend
trunk/subclipse/javahl-win32
org.tigris.subversion.javahl.win32
Prebuilt native Windows binaries for svnClientAdapter and JavaHL
trunk/subclipse/ui
org.tigris.subversion.subclipse.ui
Eclipse-specific UI
trunk/subclipse/feature-plugin
org.tigris.subversion.subclipse
About. No code
trunk/subclipse/feature
org.tigris.subversion.subclipse (feature)
Subclipse feature
trunk/subclipse/book
org.tigris.subversion.book
Eclipse help section with "Version Control with Subversion" book
trunk/subclipse/book-feature
org.tigris.subversion.book (feature)
Feature for "Version Control with Subversion" book
trunk/subclipse/update-site
-
Update site for Subclipse and "Version Control with Subversion" book features
For development and testing you'll need only org.tigris.subversion.subclipse.core, org.tigris.subversion.subclipse.ui, and either org.tigris.subversion.javahl.win32 or svnClientAdapter. Other modules are required only to package a complete plug-in feature or build an update site.
When all the projects are in your Eclipse workspace, you can try to run it. Use the Run -> Run... menu (or Debug to run under debugger), create a new launch for an Eclipse Application type, and select the Subclipse plug-ins from the Workspace Plug-Ins list. If you are running an IDE with an installed Subclipse, then you should also uncheck the Subclipse plug-ins in the External Plug-Ins list, but keep all other plug-ins selected.

Figure 14. Run the Eclipse application.
Click Run (or Debug), and if everything has been configured correctly you'll get a second Eclipse Workbench window; you should be able to open Subclipse views and connect to repositories as with the main Eclipse instance. At this time, if running under debugger you can start putting breakpoints in Subclipse classes or Eclipse core classes used by Subclipse, and the debugger will stop on those breakpoints. A good starting point is the org.tigris.subversion.subclipse.ui.actions package in the org.tigris.subversion.subclipse.ui plug-in, which contain Subclipse-specific UI actions available in menus or toolbars. Note that actions can be registered with the UI either declaratively in plugin.xml (usually action element) or programmatically in the Java code, so you have to look in both places.
Assuming the tricky part is done and you've managed to implement your changes, it's time to create a patch and attach it to an original issue in the Subclipse
issue tracking repository
. Before creating a patch, make sure to pick up the most recent changes (if there are any) from the version control repository and test your changes for the last time. If everything is okay, then use the Team -> Create Patch... menu to start the wizard. Select Save To Clipboard or Save In File System, and specify if you need subdirectories to be recursively scanned for the changes.

Figure 15. Create a patch.
Once the patch is created you can send it to the [email protected] mailing list, or create an issue in the issue tracker and attach it there.
Conclusion
Open-source extensions to the Eclipse platform, such as the Subclipse plug-in, can increase developer productivity, reduce the possibility of making mistakes, and improve communication within a development team. This article has demonstrated how to install, configure, and use the Subclipse plug-in to interact with a Subversion version control system from within the Eclipse IDE.
Using the Subclipse plug-in as an example, the article also demonstrated how to set up an environment for Eclipse plug-in development, how to debug existing plug-ins, and how to create patches. Virtually any Eclipse user can contribute ideas and patches to the open-source extensions as well as to the Eclipse platform itself.
References

• 
  Subversion
  - the home of Subversion
  
• 
  Version Control with Subversion
  - a great book on Subversion
  
• 
  Subclipse - Subversion Plug-in for Eclipse IDE
  
  
• 
  JavaHL for Mac OS X
  
  
• 
  Building JavaHL from sources
  
  
• 
  Configuring an HTTP proxy connection for JavaHL and command-line adapters
  
  
• 
  Configuring an HTTP proxy connection for JavaSVN
  
  
• 
  Configuring SSL client certificates
  
  
• 
  Configuring an svn+ssh:// connection for JavaHL and command-line adapter on Unix
  
  
• 
  Configuring an svn+ssh:// connection for JavaHL and command-line adapter on Windows
  
  
• 
  Configuring an svn+ssh:// connection for JavaSVN adapter
  
  
• 
  Subclipse FAQ
  
  
• dev2dev
  Eclipse Technology Center
  

Eugene Kuleshov
is an independent consultant. He has over twelve years of experience in software design and development and specializing in application security, enterprise integration (EAI) and message oriented middleware.
最后来篇英文的,大家感觉怎么样?
中国有好多优秀的程序员,就因为英语成了他们的死穴,世界上就少了多少IT精英啊!!!