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 a 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 project and components by your CC administrator.  Also under assumption is that the development tool is Eclipse with the ClearTeam Explorer IDE plugins installed.   

The goal of this discussion is to show how you can add existing and new projects to 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 activity for our development view.  We will also be using the default settings for the CTE plugin so that the behavior shown is what you get when the plugin is initially installed or a new Eclipse workspace is created. 

Existing Projects 

Occasionally, you might start working on an experiment in your Eclipse workspace that starts small but grows to the point it would be best to have it under source control.  The CTE plugin offers an easy way to handle this via the plugin’s Team -> Share command.   In your Eclipse workbench (the Eclipse UI), for example, the Java Package Explorer, you might have the following: 

The screenshot shows the Eclipse Package Explorer and a Java project.  The project’s property sheet is displayed showing the location of the project “NewJavaProject”.   The project’s filters are currently set so that the files .classpath, .project as well as the .settings folder and its contents are not shown. 

As seen in the property sheet the project was created in Eclipse’s default location used whenever you run the new project wizard, which is a folder in the current workspace’s root folder (the location used by Eclipse to store its metadata).  By default, this folder’s name is the same as the Eclipse project’s name but Eclipse allows them to be different if the user desires.  This Eclipse workspace location is not a IBM ClearCase-controlled location and an Eclipse workspace should never be under source control.  Our goal now is to have the project and all its content added to IBM ClearCase source control. 

Sharing Projects 

Sharing a project means putting it into IBM​ ClearCase source control and as a result makes it available to the other members of your development group.  The menu action is shown below: 

Notice that as mentioned, the files .classpath, .project and the .settings folder are now visible as I’ve removed the filter that normally hides so-called “dot files”.  The Share Project action is an Eclipse feature that the CTE plugin has implemented as required for moving a project’s contents into a IBM​ ClearCase-controlled environment.  Once invoked the Share Project wizard starts up: 

The first page of the wizard is for source control provider selection.  Here we specify the ClearTeam Explorer.  If there are other source control providers they would be listed here as well.  After clicking on “Next” you are presented with IBM​ ClearCase view selection page: 

The view selection page shows you all active, currently available views, including integration views.  You generally don’t want to share to an integration view.  Here I’ve selected my development view, testernt_PROJ1_dev, a Web view.  If you are not already logged into the CCRC WAN Server that controls that view you will be prompted to log in.  You’ll notice that on this dialog you can join a UCM project (which will allow the creation of additional views) or if you are using base CC, you can simply create a view.  The Start View button is there if you are using Dynamic or Automatic views.  If they are not currently running they will not show up in this dialog.  Once you start or create a view using these buttons, then it will also be available for selection.   

After we select a IBM​ ClearCase view, we must specify the repository or Versioned Object Base (VOB) that we want the Eclipse project to live in.  After clicking “Next” on the view selection page, you’ll be presented with the VOB selection page: 

If you want to use a private VOB, check the “Show all VOBs” check box since only public VOBs are normally displayed.   In most UCM environments, the IBM​ ClearCase administrator would have set up the UCM component VOBs as public so you would not need to do that.  Notice that you can navigate down into any subfolder of an available VOB and place your project there.  Here, I’ve chosen pjct_fld_2 as the destination of the Eclipse project.  At this point, once you click “Finish”, you will then be presented with add to source control options: 

As you can see, all artifacts except the project’s “bin” folder are selected to be added to source control.  “bin” is not added automatically because it is a build output folder; Eclipse will write all class files on a build here and it is normally not desirable to add these files to the repository.  I personally don’t add the .settings folder to source control either so I uncheck that selection but there are circumstances where it is needed such as when you have specific Java compiler requirements.  Obviously the bigger the project at this stage the longer the list is.  Also, you should note that the project has been moved from the Eclipse workspace to the filesystem location corresponding to the view/VOB path selected earlier.  Also note that the activity that is currently set in the IBM ClearCase view is being used.  You can change the activity for the add to source operation in the Activity dropdown (or create a new one or find one) and leave the IBM​ ClearCase view’s current activity as the active one once you are done by not changing the lower activity dropdown.  In this case I kept the currently set activity, and clicked “OK”.   
After the add to source control is complete what you’ll see in the workbench is: 

Since in this case I used a Web view each controlled artifact now appears annotated with a black rectangle indicating source-controlled status on the upper left of each controlled icon.  Note that the bin folder is absent.  The exact decoration depends upon specific preferences for the plugin that the user can set.  The prompting behavior can also be controlled by the user depending on the preferences set for when new files are added to the project, when they are edited and so on. 

Adding Additional Files 

Continuing your work, you will likely need to add more files to the IBM​ ClearCase-controlled project.  You can use Eclipse to create new files: select a package (eg. com.hcl.pnp.classes), right click and select “New -> Class” to start up the New Class wizard.  Upon completion, you will by default get the following popup: 

Here I’ve created a file “AssetClass.java”. Note that it is annotated with a blue square on the lower left side of the icon. That indicates that the file has not yet been added to source control (i.e. “view private”). This is standard for all view types. If there is a view private artifact visible in the UI it will be so annotated alerting you that it is not under source control and that it is visible ONLY to you in that IBM ClearCase view.

Creating A New Project Using An IBM ClearCase-Controlled Path

In the last example, the behavior of the CTE plugin when adding a new file to a controlled project leads me to the example of creating a project on a IBM ClearCase-controlled path directly in a view/VOB location. In this case we start directly with Eclipse’s “New Project” action. First, we’ll create a new activity simulating the case where we are now working on “something else”:

Once run you’ll see the following:

Here we simply fill out the headline to be something meaningful, click “OK” and the workbench will show our new activity as currently being set:

As you can see the “current activity” combo box is now populated with our new activity.  Now to we want to create a new project in our IBM​ ClearCase-controlled path. 

In the Package Explorer you merely right click in a blank area, select New, then select Java project:

In this case we do NOT want to use the default location.  The graphic shows the effect when the “Use default…” checkbox is de-selected.  The Location for the project is cleared.  You now click browse to find the location you want to use: 

Here we navigate to a new location.  In this case the path is a location where we’ve chosen to store our Web view copy area, which by default is C:\Users\<user-id>\.  In this case I added “web_views”.  The contents of the view(s) are shown.  The folder I want is the “pjct_in_place_fldr”.  At this point you click “OK” and get this: 

This is where you need to be careful.  Note the item circled.  I had to add that manually… Eclipse will only supply what you select and in most cases, it will likely not be the same as the project name.   As I said earlier, it does not have to be the same name, but if I need more projects in that folder then it becomes important.  To prevent a future problem, you just add one more segment to the path (by the way, you can see clearly where my view copy area lives relative to C:\... - you can set it to be anywhere you want on the filesystem of course.)  In the case of other view types (dynamic, automatic views) there are specific path locations that these view types have (typically under M:\ or R:\).  These view types can be accessed in a similar way via the drive letters assigned for these view types.  For example,  dynamic views can be accessed by navigating through the M:\ drive, but the basic technique here is the same. 

Now assuming you don’t want to do anything else, you simply click “Finish” with the Create Project wizard and you are immediately presented with the add to source dialog: 

Notice the selection here shows the same material as with the Team -> Share process however in this case there are no source files to be added.  You still have the same choices to make with the .settings and bin folders as to the need to add to source.  Click “OK” and you’re done: 

Conclusion 

We have examined two ways to get basic Eclipse Java projects into IBM ClearCase source control, using the Team->Share wizard and by creating a project directly on the IBM​ ClearCase-controlled filesystem using the ClearTeam Explorer plugin in Eclipse.  As you can see this is an easy and generally straightforward process.  Team -> Share of course can accommodate considerably bigger projects and so this is a convenient way of taking what may be an un-versioned set of projects that may have grown beyond expectation and getting things under control, so to speak!

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.