ClearTeam Explorer – Adding Eclipse Projects to IBM ClearCase Source Control

The ClearTeam Explorer (CTE) plugin for Eclipse allows developers to work in their Eclipse environment within an IBM ClearCase (CC) controlled filesystem. In this discussion, I will assume that the IBM ClearCase environment is one that has been set up with IBM ClearCase UCM projects and components by your CC administrator. Also under assumption is that the development tool is Eclipse with the ClearTeam Explorer IDE plugins installed.
​

The scope of this discussion is to show how the Eclipse Project Set mechanism can be used to handle the importation of a set of Eclipse projects that are under CC source control. In this scenario, we are also going to assume that we have a UCM project ready for use. Additionally, we have joined the UCM project, and have created and set a current working UCM activity for our development view. Additional information on the handling of Eclipse projects in IBM ClearCase can be found in my previous posting about adding projects to source control.

Basic Project Import 
When opening Eclipse with a new workspace, there are multiple ways of importing projects into the workbench. You can choose File->Import from Eclipse’s pulldown menu, navigate through General->Existing Projects into Workspace and browse to a folder location known to have projects in them. Any projects in the folder tree beneath that point will show up in a check-box list and you can select any or all for import into the workbench:

This works well whenever you have a single tree to search for projects. So long as you keep projects segregated in this way, you can do this importation once and you’re good to go, but there is no guarantee that projects are managed in this way. At HCL, we have more than one VOB (Versioned Object Base) that contain many Eclipse projects and as an ensemble, comprise the ClearTeam Explorer project. Using the above technique every time we needed to begin with a new workspace, we would have to run the import several times for each set up. While one can manage projects by folder, at some point reuse of various Eclipse projects for other purposes will ensure the above situation occurs. For newcomers to a team, this won’t be ideal. Finding the needed material in multiple files systems (in CC’s case, VOBs) is obviously an inconvenience. Eclipse very effectively handles this issue via the “Team Project Set”. 
​
As the name implies a Project Set is exactly that. Kept in a file of opaque strings (embedded in XML), the Project Set File contains all the required details for the Eclipse workbench to read in and pass that information to the CTE’s Project Set handler. The handler then imports each project it can find in the Project Set File (.psf file) and opens it so that it is ready for use in the workbench. 

Creating the Project Set 
For first-time operations, you must start by creating the Project Set. This means that for existing systems, you must do it the “hard way” for the first time. Consider the screenshot below:

Here we have an Eclipse workbench populated with a few projects. Here we have a number of Java projects that are CC controlled in our workspace. What isn’t shown here is how groups of projects are on different paths. The CTE Explorer Navigator shows the following:

The important thing here is that the individual Eclipse projects are in three different VOBs and hence three different paths. A key point here is that Eclipse’s “Import Existing Projects”, depending on where you tell it to start, could find all these projects, but the more subfolders it can see the longer it will take. 
​
I can also import projects from the CTE Navigator (right click on a project root -> Import Project…). This helps of course but if I have other views that I also use (different development streams for example), multiple import gestures must be repeated for those cases as well. Here is a screenshot illustrating the process:

Note below the “Import Project…” but greyed out, is “Import Project Set”. (This is what it’s all about but more on that later.) This is another way to populate your workspace… any folder that contains a “.project” file can be imported into the workspace via the IBM ClearCase perspective - perhaps a bit more convenient but you still hunt around somewhat. 
​
So now we’ll do our colleagues a favor by creating the Project Set. To do this, go to a perspective such as the Java perspective. Select all projects in the Package Explorer and right click, invoking “Export…”:

The Export wizard will open:

Take note I have typed in the word “team” into the filter so that only items in the Team portion of the wizard will show. Otherwise this item would be a bit “busier”! At this point you simply click “next”. Then you are presented with the next page that, if needed, will allow you to refine your selections:

Click “Next” again once we have verified the selections are correct:

Click Finish and the file is saved. 

You should also note here that the path I’ve chosen is in my web view’s local file area and that it is in the VOB \ucm_comp1. There is a good reason for this. I will add this file to source control in this easily findable location. That means anyone who creates a view that can use this VOB, will be able, in only one gesture, import the Project Set into the Eclipse IDE workspace, and I can either use the Import Project Set Eclipse wizard from a workspace or I can import the Project Set by right clicking on the .psf file in the IBM ClearCase perspective itself. 
​
If the Project Set has to be altered due to projects being added or removed, for example, then you go to the IBM ClearCase Perspective in Eclipse, check out the .psf file and re-run the export after making the any necessary workspace changes. 

Importing the Project Set Using the IBM ClearCase Perspective 
In this scenario, I’m going to run through the steps you’d take if you had just created a new CC view e.g. joined a UCM project for example and gone through the view creation process. As with individual projects in ClearTeam Explorer, if you can find a file with the “.psf” extension on it you can import it. In the tantalizing screenshot we had earlier, I showed you the basic import gesture for the CTE Navigator and Details panel. Now we are going to do a Project Set import using a totally unpopulated UCM view. If you are familiar with view creation wizards in CTE you’ll recall that upon view creation you get prompted to configure the view by loading VOBs (for web/snapshot types). With PSF (Project Set File) import, we do not even need to set load rules in the view (for web/snapshot types). First, we’ll need to tweak CTE (keep in mind that this example is web-view centric, and that we’ve already authenticated with a CCRC WAN Server) to view unloaded VOBs and elements. Here is what the CC perspective would look like just after view creation/configuration minus the load rules:

Now we click on the circled item above and select the two “Unloaded…” items:

As this is a pulldown menu, you must do this in two gestures. Also keep in mind that when you do this, you must be connected to a CCRC WAN Server. Information on remote items can hardly be expected to be obtainable if there is no means to get it! Finally, do NOT leave these settings this way once you finished dealing with it. Since this requires server contact, browsing will necessarily be a lot slower. You only do this when you need to find specific unloaded items. Now we can navigate the unloaded CC file system. Recall that I added my psf file into CC control, right in the \ucm_comp1 directory:

And there it is… Now right click on that and you’ll see that the Import Project Set action is now active:

Once selected you’ll be prompted to load the psf file:

Click “Apply” and the psf file loads, leading you to this prompt:

Upon clicking “Apply”, each individual project will have a load rule placed into the view’s configuration specification individually. This is a great way to avoid the loading of more than you need. Now if we examine the view’s config spec before and after:

You can see the before and after… each project has an individual load rule without you having to know anything more than the location of Project Set File in the repository. 
​
On the other hand, if the Project Set File is somewhere on the local filesystem, I would have had to pick the view manually (obviously the view is “pre-picked” in the scenario I ran through) but loading would still take place (provided I was connected to a server), with the only difference being I would have had to select a view when presented with the view picker. There are other nuances… suppose you had some or all projects already loaded… in that case you would be prompted with an additional dialog:

The items checked would be removed from the workspace and re-loaded. If there were many additional projects you wanted to load, and you did NOT want to reload any of the shown items, you click “Deselect All” prior to proceeding. But for example, if you were switching to a new view with the same project names… then you would want to force the reloading into the workspace. We consider the use of one Eclipse workspace for each IBM ClearCase view a best practice which, if followed, makes it far less likely you would need to overwrite projects in your workspace. We recommend naming each workspace with the view tag. For example, I generally follow a naming convention that contains my name, a version, view type and development or integration identifier: petrakis_9.0_web_dev, petrakis_9.0_web_int 

This identifies the two view types as mine, for version 9 UCM stream, web view, development and integration. I would then have two workspaces to service each of these views with the same names. I can easily switch between the two workspaces using “File->Switch Workspace->Other” gesture in the Eclipse UI:

In some cases, I may run two Eclipse instances to have both workspaces open, which I find useful when I’m needing to deliver and build a change in the integration view prior to completing the delivery. Since both Eclipse instances have access to all view tags, I will do the work in my “dev” workspace, however the UCM operations I will perform in the so-called “int” workspace. I’ll have the projects loaded in the “int” workspace so that I can force the deliver from the “dev” view into the “int” view. Upon refresh of the “int” workspace, I’ll get a build and I’ll know (before completing the deliver) if the code has a build issue. If it does I undo the deliver and try again! 

Importing via Project Set from the Java Perspective 
The obvious difference here is that we’ll fire off the Eclipse Import/Export wizard by right clicking on an empty workspace (alternately use the File->Import… gesture) and selecting Import:

Which in turn brings up the Import wizard:

Now click Next to get the input dialog for your Project Set:

Note in this case that the psf file happens to be in some random location on the “C” drive, not in a CC view. Because of this when I click “Finish” I get the following dialog:

Without a IBM ClearCase view, there is no path. That is why CC has views… as if you didn’t know that! I can select any of these views that make sense. Note that there are two dynamic views in this list. I’ve been using web views in the above examples. Also, you do have to keep in mind what kind of view it is. I am using UCM so I need to keep in mind which ones are the appropriate views. Since you will be the one creating the views, it’s important that you do keep track of them. Once I choose the appropriate view (in this case, it’s testernt_PROJ1_web_dev) then you can click “OK”. The system will then make the appropriate server calls checking each entry in the .psf file for a corresponding Eclipse .project file. Once it finds location in a VOB for an entry, it knows the project is usable and offers to load anything not loaded:

So now we are at the same place as when we instigated a load from the CC perspective. As before, projects already loaded in the workspace will be offered up to be reloaded. Clicking Apply finalizes the process unless there are some same-name projects already in the workspace… Once loading is done, you get a popup telling you the projects have been imported and you simply click on the “OK” button. 

Parting Thoughts 
We use IBM ClearCase and Eclipse for our development of CTE and the CTE plugins… this should come as no surprise! We also make heavy use of IBM ClearCase’s UCM development model to ensure that we keep out of each other’s way when doing development. I want to stress here that our way of accomplishing our work is to keep to a few, relatively simple best practices that help immensely to keep our personal workspaces organized. Three key ideas I like to use with project set usage are: 

1. Use separate workspaces for each view. Using multiple IBM ClearCase views allows you to easily isolate work that must be done in parallel. Creating one Eclipse workspace for each view extends the same benefits to Eclipse. When you need to work on activity in another view, you simply switch your Eclipse workspace to the one using that view (we suggest you give the workspace the same name as the view it is using). If you need to switch back and forth between workspaces frequently, you might be better off having multiple Eclipse instances running simultaneously, each using one of the pertinent workspaces. 

2. Create you project sets early and keep them up to date. When you do this, creating new views and workspaces become are not a large overhead proposition. You also do not have to keep groups of projects segregated in a single place which makes reusing plugins very easy. Your project set, properly maintained, will always be able to find what you want to load, no matter how scattered about it is. You don’t have to worry about keeping a specific workspace or view ever again.

3. Maintain your project set file in a VOB! With this approach, you just need to create a view and you’ll only need to know where in the vob the .psf file is. Once you navigate to the psf file through the CTE Explorer, all you need to do is fire the import gesture on a right-click. CTE does the rest. You want to explore a variation to the code? Switch your workspace to a new one, create a new view (in UCM you can use a different stream which helps keep it isolated even better), load up the psf file through that view and you are ready to experiment. 

Conclusion 
I’ve touched upon some of my favorite ways of using the Team Project Set feature of Eclipse. Having this mechanism makes it very easy to move from one UCM project to another or one view to another in the case of a base IBM ClearCase scenario with branching. Populating new workspaces with this mechanism is very easy… you can export workspace settings for use in other workspaces and then use the psf mechanism to pull in the needed projects and maintain a set of standard practices with less fuss. This makes setting up an Eclipse workspace with IBM ClearCase-controlled Eclipse projects very easy and repeatable.

John Petrakis
​Solutions Architect at HCL

John is a technical contributor to the IBM ClearCase product family and has worked extensively on the ClearTeam Explorer and ClearTeam Explorer plugins for Eclipse along with other integrations for IBM ClearCase.