ClearTeam Explorer – Joining ClearCase UCM Projects

The ClearTeam Explorer (CTE) plugin for Eclipse allows developers to work in a ClearCase (CC) controlled environment.  ClearCase affords an activity-based way of tracking changes in a code base that allows the user to keep track of their work via activity-managed change sets.  The ClearTeam Explorer, when installed as a plugin to the Eclipse workbench, allows you to keep your activities organized when you are using ClearCase UCM. 

We will assume that the ClearCase environment is one that has been set up with ClearCase UCM project and components by your CC admin.  Also under assumption is that the development tool is Eclipse with the ClearTeam Explorer IDE plugins installed. 

The scope of this discussion is to describe one or two ways you can join projects so that you can start contributing! 

The ClearTeam Explorer 

The CTE standalone (or "the standalone") is equivalent to the “ClearCase Perspective” when using the CTE plugin in Eclipse.  CTE supports all four view types, dynamic, automatic, snapshot, and Web views.  This blog entry focuses on using CTE in Web views but most actions will apply to other view types as well.  When I refer to “CTE” I will be meaning either the CTE standalone or the ClearCase Perspective in Eclipse.  If you are running Eclipse with the CTE plugins or are running the standalone, the operations for joining projects are provided via the toolbar in Eclipse or in the CTE standalone.  Most operations in the toolbar (the operations that depend upon view context) are available as context menu actions that can be run after right-clicking on a specific view in the views list of the CTE. 

With a new Eclipse workbench/workspace or starting the standalone for the first time, the first thing you’ll be doing is logging into the ClearCase CCRC WAN Server which will allow you to start using ClearCase.   The CCRC WAN Server brokers all CC operations for the web view and automatic view types and is required to work remotely.   It is installed along with full ClearCase on a dedicated system and it brokers all interaction between remote view types (web, automatic views) and the client (the standalone and CTE plugins for Eclipse).  You will use the buttons on the toolbar, or the context menu from a view if you want to connect a server for a specific view.  These are shown below, circled in red:

The graphic shows the CC perspective in eclipse.  If you had fired up the CTE standalone, it would look the same except for some of the eclipse specific items in the dropdown menus and the perspective selector icons (i.e. only ONE perspective in the standalone!).  If this is a first time start, post installation, then you’d use the connect button on the toolbar for the quickest login.  The ClearCase pulldown menu also has a connect action that is an analog to the connect button.  Run the login action and you get the login dialog: 

The server URL shows the form of the typical CCRC WAN Server connection.  The form of the user name is specific to windows login so this tips you off that the server in this case is a Windows system.  Each view you’ll create will associate with the server in the current login.  You can have many views associated with many servers.  Each server will appear in a list in the CC Perspective at the bottom of the navigation panel (right hand side of the figure 1).  You can connect from the context menu on any server entry in the navigation panel as well.

Join Project Wizard.

One way to join a project might be to use the join project button.  The key buttons on the toolbar for UCM actions are shown here:

"Rebase" is for pulling in changes that have been delivered to the integration stream, "deliver" is for pushing your changes to the repository.  The "current activity" dropdown is for setting your stream’s activity from the list of activities you will have created during your work.  "New activity" is obviously for creating a new activity.  At this point you click on the "join project" button to run the join project wizard.  The first page of the wizard then comes up:

Note the item marked "Project VOBs".  A VOB is an acronym for "Versioned Object Base" and is the repository for all artifacts under CC control.  You can have separate Project and Component VOBS, the Project VOB containing all the meta-data UCM requires in order to function properly.  The Component VOBs then may be thought of as your source repository.  They need not be separate, however in our usage at HCL, they usually are. 

The dialog comes up with the list of known servers (CC Local is beyond the current scope).  Note that I have expanded the server I logged into and navigated through the project VOB to a specific project that I want to join.  There may be several project VOBs and each may have many projects.  You’ll need to know which one you want.  I then select “PROJ1” and click "Next":

This dialog shows the development stream that will be created (testernt_PROJ1).  You can create several views off this stream if you wish but you’ll then need to keep them synchronized, especially in the case of a web view.  I’m creating both a development view for my new stream, and an integration view which is on the integration stream.  The integration stream is shared by all and this is where everyone’s deliveries will go.  Advanced users will often create sub-streams for long term or exploratory work and use their development stream like an integration stream for themselves.  Generally there will be no need to worry about stream options.  If you don’t want any specific names for your view tags (at this point they’ll be testernt_PROJ1 and testernt_PROJ1_int) then you can click "Finish."  I like to identify my dev view with the word “dev” so I generally click "Next" here: 

Notice for web views there is a copy area path.  I’ve added “web_views” here… the default is to put it right in your home directory.  You’ll get prompted to create this subdirectory at this point if it does not already exist.  This path is persisted for future web view creation in the current eclipse workspace.  

Once you click "Finish", the views are created and you will be asked to load VOB artifacts.  In this case the VOB was new so I added the entire VOB since it was empty.  You may not have this situation so you would probably rather not load an entire VOB which may have thousands upon thousands of artifacts!  The load selection dialog is shown below:

For this you would expand the desired VOB root (for UCM you are interested in the project components which show by VOB here…) and navigate down to the material you want to load.  Even if there are hundreds of folders in the VOB root, nothing you do not select here will load.  So, you navigate down, select each subfolder you want (the dialog allows multi-select) and click “Add”.  The load rule will appear in the bottom “Load Rules” panel.  Note the annotation of an “open box” on the VOB folder etc.  This denotes unloaded state.  Anything that is loaded into the current view will show a filled box annotation instead. 

As mentioned this is one way to join the UCM project. The other way (once you’ve logged into a server at least once) is to navigate through the server node to the project.  This is effectively the same as when you got the first dialog after the join project button: 

As you can see in this graphic, the server we’ve logged into is shown in the right hand side navigation panel of the CC perspective (or CTE standalone).  As with the first panel of the join project wizard, I’ve navigated down to the project of interest and now I can use the context menu to join the same project.  Once this action is initiated you will see the same set of pages from the join project wizard that were subsequently shown in the prior example. 

Conclusion 

I’ve shown two of the most common ways to launch the join project wizard for users to join in the fun of developing in a CC UCM environment.  Once you’ve joined a project and loaded the artifacts you need/want you can get right to work.  For Eclipse projects, the CC perspective in Eclipse affords a few ways to import existing work right into Eclipse, not to mention robust ways to add non-controlled projects you may have started in the default workspace to the CC repository.  These will be discussed in the next entries.  

John Petrakis
​Solutions Architect at HCL

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