ClearCase LT and WebSphere Studio integration

Document options Document options requiring JavaScript are not displayed Rate this page Help us improve this content

Level: Introductory

IBM Rational (dwinfo@us.ibm.com), Staff, IBM Rational

13 Sep 2004

This tutorial contains step-by-step guides and samples to set up an environment where WebSphere Studio workspaces can be put under source control in ClearCase.

Introduction

This paper is the first part of a two-part tutorial focusing on integrating IBM® WebSphere® Studio with IBM® Rational® ClearCase® LT using either the Unified Change Management (UCM) or Base ClearCase method. This part will focus on UCM.

The tutorial contains step-by-step guides and samples to set up an environment where WebSphere Studio workspaces can be put under source control in ClearCase. This tutorial uses quite simple example scenarios to demonstrate typical tasks.

The tutorial does not cover all the aspects of a software development lifecycle, but it covers enough ground to get you started.

Back to top

Who should read this tutorial

This document is intended for both project managers and developers. Although these different roles are responsible for different tasks, there are commonalities that make it beneficial for both parties to know about the process as a whole.

Small development teams, where the same person may take on more than one of the above roles, will also find this information useful.

This tutorial assumes that the reader is familiar with source code management and configuration management concepts, and also has basic knowledge of how to use WebSphere Studio.

Back to top

Assumptions before starting this tutorial

Before starting this tutorial, make sure that you have already completed the following tasks:

• Install ClearCase LT server.
• Run the Getting Started wizard (using all default options).
• Install WebSphere Studio Application Developer, selecting IBM Rational ClearCase SCM (software configuration management) Team Adapter during installation. Of course all the other editions of the WebSphere Studio should also work, because they are based on the Eclipse platform.

To find more information regarding the above tasks, please refer to resources to the appendix.

All the examples and screen shots were created using the following versions of the products

• ClearCase LT version 2003.06.00
• WebSphere Studio Application Developer V5.1

Back to top

UCM and Base ClearCase

There are two distinct approaches to using ClearCase as a SCM system, Unified Change Management (UCM) and Base ClearCase. The following sections serve as an overview to make the user aware of the basic concepts found in these approaches. A complete discussion of this topic is identified in the appendix. Regardless of the approach selected, the following terminologies should be familiar:

• File element: any file that contains artifacts, like source code, configuration files, HTML, and XML that can be stored on a file system and are under source control.
• Directory element: as in any file system, directories are used to group files. They can also contain other directories. In ClearCase, directories can also be under source control, which is both a very powerful feature and sometimes a source of confusion for new users.
• Version: a specific revision of an element. Different versions of an element help us keep track of the changes an artifact has undergone.
• Versioned Object Base (VOB): a repository (managed by ClearCase) that contains versions of elements.
• View: represented as a directory that, based on its configuration, provides access to certain versions of elements.
• Check out: a process that places an editable copy of an element into the current view, where it can be used for updates
• Check in: the process of making updates to a checked-out element permanent by creating a new version of it in the VOB.

The UCM approach

The UCM approach provides an out-of-the-box process for SCM that raises the level of abstraction for developers and project managers. Instead of requiring the team to manage individual changes to source code manually, UCM allows them to manage their development efforts at the Activity level (the tools keep track of which changes belong with which Activity). The process used in this approach references some concepts that are used to categorize and streamline the development process. The benefit of using this approach is that the prescribed process is automated through the tools. Some of these concepts are listed below. Please refer to the appendix to find more information about the following terms.

• Project: an entity that contains the configuration information (components, activities, policies, and so on) necessary to manage and keep track of work on a project. A project typically consists of a shared workspace and a number of private work areas for each developer.
• Work area: a view and a stream.
• Stream: a list of activities and baselines that determines which versions of the elements should appear in the view.
• Component: a group of elements that serve a well-defined purpose and can be shared between projects.
• Activity: a change set that helps to identify what artifacts were created or modified to fulfill a certain task, like fixing a bug or adding a feature.
• Baseline: a logical grouping of certain versions of elements in a component that reflects the integrated or merged work of a development team. In other words, it can be considered a version of the component in a particular stage (like a first build or a beta release).

Base ClearCase approach

This approach is mainly used in circumstances where the company already has a well-defined and established process for their software development life cycle. The project teams, therefore, only use the source code control aspect of ClearCase, and they establish their rules and policies through the facilities that are provided by ClearCase.

The benefit of this approach is that the company (or any specific team in the company) can reuse their familiar rules and processes. On the other hand, if they adopt a unified way of doing their work (UCM) then it would probably be much easier to move people in the teams, and to make use of common processes that are well-tested and established.

The second part of this tutorial will focus on this approach.

Back to top

Setting up a UCM project

The remainder of the article will demonstrate how to create a UCM project, configure it, and join it and, finally, how to add a WebSphere Studio-based application to source control. It will also show you how some of these tasks can be done either from ClearCase Explorer or from within WebSphere Studio Workbench.

Generally this task is performed by the project manager (or sometimes by the technical lead). This involves creating various artifacts that we will examine in detail in the following sections.

Create a new component to store the project baseline

We recommend that you use a single component to store baselines. This will facilitate the task of maintaining baselines in multiple components. In our example, however, there is only one component. Therefore we will not need to use a "baseline storage" component, which in this case would require the use of composite baselines, and the discussion of which is outside the scope of this tutorial. As a result, we will simply show you how to create a component that will store only baselines (rather than elements). For an extensive discussion of composite baselines and how they can be used, please refer to resource the appendix.

We will create this component without a VOB root directory, which will prevent the component from storing any elements:

• Start the project explorer (either from the ClearCase Explorer or the start menu of Windows®).
• Open the projects folder (or the name that you chose at the time the wizard was run; we will refer to this folder as projects).
• Right-click the Components folder and select New > Component without a VOB.

• Enter a name for this component and select OK.

Create a new component to store the elements

Components are stored in a VOB, so we'll need to create a VOB. You can create a VOB as a single VOB-level component, or one that can contain multiple components. In our example we will use the former approach:

• Start the Create VOB wizard

• Provide a name and description (comment) for the new VOB, then click Next

• Select the second option, Create VOB as a single VOB-level component, and click Finish

Create a new UCM project

At this point we will create a new project, which will contain our sample:

• Open the projects folder.
• Right-click the projects folder and select New>Project.

• Depending on the need, choose the parallel or single stream development option. The parallel option is used in circumstances where the team needs to make simultaneous modifications to an artifact under source control, whereas the single stream option allows only one modification to happen at a given time. We will choose the parallel option and click Next.
• Since we are creating a project from scratch, we will not select any of the existing projects to seed this one as the baseline. Make sure that No is selected, then click Next.

• In this page of the wizard we will add the two components that we created earlier: the component that will store the baseline and the component the will contain the elements (which happens to be the same name as the VOB). Follow the steps below and, when finished, click the Next button.
• Click Add.

• From the components drop-down, select the VOB component that you created earlier.
• Click Change, and then select All Streams from the menu.
• Also, select the only baseline that appears in the list below.

• Repeat the above steps, and this time, select the component that is supposed to store the baselines.

• In this step of the wizard, we will determine the modifiable components and the policies that we would like to enforce. By default all the components are read-only. Select the component that contains the elements to be modified.

• Click Policies and view the available options in the Project Policies dialog box. For this tutorial we will use the most common rules, which are the first two on the Deliver tab of the dialog. The first option, when enabled, ensures that there are no elements left checked out when the developer tries to deliver the current stream. This helps reduce the number of abandoned elements. It will enforce the idea that if there is an element checked out, either it contains useful code (so we should check it in) or the changes should be undone (which will return the element to its original version). The second option ensures that the developers will always have the latest stable code in their private work areas. Click OK to apply these options and close the dialog, and then click Next.

• Since we are not doing any IBM® Rational® ClearQuest® integration, select No in Step 5 and click Finish. (Briefly, ClearQuest is a related product that complements ClearCase by providing features for defect tracking, change request management, and notification.)

• Review the information in the New Project — Confirmation dialog box, and click OK.

Back to top

Create an integration view

After you create a UCM project, ClearCase automatically creates an integration stream. This is the stream that will store all of the shared artifacts, and all the developers will deliver to this stream to make their changes available to the whole team. The integration view is a workspace containing the versions of elements specified by the project's baseline(s). To create the integration view:

• Start the project explorer.
• Navigate to your project folder and select the integration stream within it.
• Right-click the stream and select Create View.

• Confirm the name and location of the view you are creating.

• Click Advanced Options and make sure that the Use interop (insert_cr) text mode option is selected, and then click OK.

• Click Finish, and then click OK in the Confirm dialog box.

• In the Choose Elements to Load dialog box, select the corresponding VOB, click Add, and click OK.

• Press OK in the View Creation Status dialog box.
• You can verify that you have created the view by starting ClearCase Explorer.

(click here to enlarge)

Back to top

Create and add the initial artifacts to source control

For our example, we will create a directory that will store our source files. WebSphere Studio projects (which we will create later) will use this directory as a workspace directory. For now we will call it wsad_workspace and we will add it to source control:

• Start ClearCase Explorer.
• Select the integration view.
• Expand the directory structure for the view until you can see where you want to create the directory.
• Create a new folder (right-click, and click New>Folder).

(click here to enlarge)

• Right-click the new folder you just created, and select Add to Source Control.

(click here to enlarge)

• You will then be prompted to create an Activity (everything in ClearCase is done with an activity associated with it). Activities represent independent units of work, which contain a set of related changes that help to support sophisticated builds, fix defects, implement new features, and so on. Add a proper name for the activity. Make sure the names that you select for activities are meaningful, and that each activity represents a unit of work. Click OK on this dialog. If appropriate, you can use the previously described steps to add additional artifacts (such as folders or source files) that represent the starting point for your development project.

Define an integration baseline

This integration baseline will contain the new artifacts, and developers will use it to join the project.

• Start the project explorer.
• Right-click the integration stream and select the Make Baseline menu option.

(click here to enlarge)

• Optionally, modify the new baseline name in the Make Baseline dialog box to reflect the purpose for the baseline, and click OK.

• Click OK when prompted, and then click Close.
• If the initial artifacts added to the project are adequate for the developers to start working, then the project manager recommends the new baseline so that all the new members joining the project would automatically see these artifacts. To recommend the baseline, follow the above steps and select the Recommend Baselines option instead of Make Baselines.
• By viewing the recently created folder using Version Tree Browser, you can see that this folder is on the integration stream along with the baseline just created. To display the version tree, right-click the element and choose Version Tree from the context menu.

So far you have completed the following tasks:

• Set up the project
• Added the initial artifacts
• Created a baseline
• Optionally, created activities and possibly assigned them to developers

Back to top

Joining a UCM project

The previous steps represent the initial setup of the UCM project. Now that we have a project and a baseline, the developers can start joining the project:

• Start ClearCase Explorer.
• Select the Join Project shortcut from the UCM tab.

(click here to enlarge)

• From the list of projects, select the project you would like to join and click Next.

• On this page of the wizard, you will create the development stream and choose the corresponding integration stream.

• In the Create a Development Stream step of the Join Project wizard, click Advanced Options and select the baseline that contains the latest artifacts added to the integration stream. You will need to select the component and change its baseline. The following three screen shots of the Advanced Options dialog demonstrate that process (click Next when you are finished).

• The Review Types of Views step of the Join Project wizard shows the creation of a new view for the development. Make sure that Reuse existing integration view is selected, and then click Next.

• In the Choose a Snapshot View step of the wizard, you will see the location where the view will be created. Keep in mind that this will also be the location were all the source files and resources created by WebSphere Studio will reside. Therefore, keeping this directory structure simple will make it easier to work with. As before, enable the Use Interop (insert_cr) text mode option on the view through the Advanced Options button, and click Next.
• In the Choose Components step of the wizard, make sure you have selected the component that contains the elements that need to be modifiable (the box is checked), and then click Finish.

• Click OK in the Confirm dialog that you want to create the item.

• When you are informed that the item was successfully created, click OK.

Back to top

Adding a WebSphere Studio workspace to source control

In this scenario, we will create a very small project that will be added to source control and changed by two independent developers. This example will illustrate the steps involved in adding a WebSphere Studio workspace to source control, and show how a developer can work in his private workspace and later rebase, and ultimately deliver, his work.

Before starting this section, make sure that you know how to set up a UCM project and make a baseline. You created a UCM project (acting as the project lead), and you created both your integration view and your development view (acting as a developer).

Usually the technical lead who initiates the project performs the following tasks:

• Create an initial WebSphere Studio workspace.
• Set the workspace with preferences that reflect the company's development policies, like header comments for the source code file, type (class or interface) comments, source code formatting, JavaDoc preferences, and so on.
• Create the relevant projects in the workspace and configure them
• Optionally, add initial packages and classes.

After creating a preliminary workspace (with initial projects in it as a starting point), the project manager or the technical lead will be responsible for adding it to source control.

In our example scenario, we will create a workspace directory with only one basic Java project that contains a simple Java class, and then add it to source control.

Note: we assume that the user is already familiar with WebSphere Studio, so the steps to create the workspace and the project will not be shown in detail; they are presented only as a guide to create the appropriate artifacts.

We can create the workspace in two ways. The first option would be to create the workspace somewhere on the file system and then move it to the appropriate location to put it under source control. The second option would be to create the necessary directories under the directory where the view is located, and add them to source control. We will choose the first option, because this will show how you can take existing projects from the file system and put them under source control.

To create a WebSphere Studio workspace and a project:

• Create a directory called C:\SampleProjectWorkspace, or another appropriate drive and directory
• Start WebSphere Studio and specify the above directory as the workspace directory
• Create a Java project and call it SampleProject
• Create a package called com.tutorial.sample
• Create a class that has a main method and is called SampleMain
• Add the following simple code in the main method of the above class System.out.println("Called from version 1")
• Assuming that you have made particular changes to the preferences, we will export the preferences in a file called SampleProjectPref.ecf

(click here to enlarge)

Note: while the selected project may seem overly simplistic, this exercise focuses on demonstrating how a project is added to source control, and what artifacts need to be added. We will try as much as possible to simulate real life cases.

Now that we have created our sample project, it can be added to source control. To accomplish this we will do the following:

• Select a project, right-click and click Team>Share to point to your integration view location
• As a rule of thumb, consider adding artifacts that are:
• Common to everyone in the team
• Shareable, that is, they can be changed by anyone, and the changes will be reflected in everyone's workspace
• Related to the projects, and necessary to build the product
• Some example of artifacts that should not be added to source control are
• Server projects
• Any .class files
• The .metadata directory and everything in it

WebSphere Studio permits customization in its preferences, allowing you to specify the resources that should not be added to source code management. You can access this option by performing these steps:

• Open the Preferences window (select Window>Preferences
• In the Preferences dialog, select Team>Ignored Resources from the left tree
• Specify the resources that need to be ignored

The default list contains some of the most frequently used resources. After taking the above steps, the directory selected in the integration view will contain a new directory with the same name as the project, and it will contain everything that was shared using the Team>Share menu option.

Note: Since you will be creating a new WebSphere Studio workspace, you can import the preferences file (exported earlier) to let the whole team use a consistent set of preferences. Naturally, however, the perspective customizations will be lost, and each developer should customize it again.

We will need to validate our work by testing the contents in the integration stream:

• Start WebSphere Studio and select the directory of the integration view where the project was shared.
• Select the Import>Import an existing project option from the menu list, and import SampleProject.
• The default settings in the preferences enable decorations, which are a way of showing what items in the workspace are under source control. They are reflected by changing the background color of the items. At this point you will notice that, since the project is under source control, the icons related to packages and classes have a blue background.
• Refresh and rebuild the project and make sure that you can still run the application.

Note: This will create the WebSphere Studio workspace (and its .metadata directory) in the same directory in the view where the WebSphere Studio project is located. As an alternative approach, you could start WebSphere Studio in another directory (not in the view) on your file system and then import the project. If the view directory is on a network drive, this might help improve WebSphere Studio startup time, because the workspace files are located locally on the file system. It will also be beneficial if there are multiple WebSphere Studio projects in the VOB, with different combinations of them creating different WebSphere Studio workspaces. In this case you could create multiple workspace directories on the local file system, and in each of them simply import the projects that are related to each other.

At this point the workspace is under source control and tested. Now the project manager will create a baseline of all these artifacts and recommend it. We covered the steps to do this in the previous sections.

Going forward, we will use the views that we created earlier when joining the project. Do a rebase from each of those views using the new recommended baseline.

To test the development view, start another instance of WebSphere Studio (not necessarily simultaneously), follow the steps provided earlier for testing the integration view (to mimic a different developer), but instead of the integration view select the development view that you created earlier.

Now we will try to change the only class in our application and observe the effects from each of the views. Start WebSphere Studio from the first view and import the project. Then, with the steps provided below, check out SampleMain class from within WebSphere Studio and change the text for the output statement to reflect the following.

System.out.println("Modified by the first view")

The steps to accomplish this are:

• Start WebSphere Studio in the workspace directory of the first view.
• Import the project as an existing WebSphere Studio project (like you did earlier in the integration view).
• You will notice that the project is displayed as being under source control.
• Right click the SampleMain class and select Team>Check out. Alternatively, you can highlight the class name and select the "check out" icon from the toolbar.
• In the Check out dialog box, enter an optional comment and click OK.
• From the Activity dialog box, select the activity to which the project manager assigned you to make these changes. In our case (since there is not an Activity already created to represent our work) we will create a new activity to make these changes and call it ModifyForMergeTest.
• Make the code change by changing the output string as follows:

  System.out.println("Modified by the first view")

• Check in the file by selecting Check in from the Team menu.

Looking at the Version Tree of this class, you will notice that this element is now in our stream. In order for others to be able to view our changes, we will need to deliver them to the integration stream.

Before delivering this change to the integration stream, take a look at the same element from the second WebSphere Studio workspace that you created earlier with a separate development stream. If you open the SampleMain.java file, you will notice that you are still looking at the previous version of the file. Furthermore, if you open the Version Tree for this file, you will see why, the highlighted version node and the horrifically realistic-looking eye tell you that you are looking at the (old) version of the file on the integration stream.

Now, using WebSphere Studio and not the ClearCase client, we will deliver these changes and then notice how they are reflected in the second stream. Of course, in a real-life development scenario you should make sure that you have rebased your private work area and tested the code before delivery. You can also enforce this practice through defined policies. This means that if anyone else made changes to the same element while you were working, you have to take those changes into your stream, merge them with your work, test the effects, and then (after successful testing) deliver the changes.

To deliver the changes:

• In WebSphere Studio, select the ClearCase>Deliver Stream menu item.
• Select OK on the resulting dialog, which has automatically selected the new activity that we created to make the modification.

Now the changes are applied to the integration stream. You can verify this by looking at the element in the Version Tree.

In addition, looking at the same element from the second development stream will show the new element version in the tree, but we will not see the latest changes because our view is set to look at the recommended base line. To see the delivered changes, we will need to wait for a new baseline to be created, and then rebase from that.

Back to top

Summary

To begin development using the newly created UCM project, we took the following steps:

• The technical lead created the initial WebSphere Studio workspace, and perhaps added some artifacts in it.
• The project manager or the technical lead added the WebSphere Studio workspace to source control.
• The project manger created the project baseline, and then created and assigned activities to developers.
• Developers joined the project, rebased with the recommended baseline, and started working on their activities.
• Every so often, the project manager, with the help of the technical leads from all the teams (development, Test, QA, and so on), decides on the stability of the builds, creates a baseline, and recommends it.

Back to top

Appendix

Resources

Some of the resources discussed here can be found in the following directory of the ClearCase installation:
<ClearCase_install_dir>\doc\books\
The same documents (and many more) can also be found on the IBM web site. Visit the following page and find the link titled IBM Rational ClearCase Family. Selecting that link will open to an FTP page from which you can download all the ClearCase documentation you need.
http://www.ibm.com/software/rational/support/documentation

ClearCase Installation

Please find the installation guide from either location provided above.

WebSphere Studio Installation

WebSphere studio zone is the best place to start looking for resources on WebSphere Studio (all the editions).
http://www.ibm.com/developerworks/websphere/zones/studio

The installation guide can also be found in the root directory of the CD in both HTML and PDF formats.

Back to top

Essential Reading

Introduction to ClearCase

In the online documentation provided by ClearCase, the introduction document is incredibly useful. It contains a definition of all the terms used in this tutorial. The PDF version of the file can be found in either of the locations provided above. The local version (found in the installation path) is the following:
<ClearCase_install_dir>\doc\books\cc_intro.pdf

Getting started with ClearCase

This page contains a roadmap for getting started with ClearCase.
Getting started guide for the Rational ClearCase product family

Composite baselines

This paper discusses composite baselines, and also explains some of the entities involved (such as components, baselines, and projects).
http://www-106.ibm.com/developerworks/rational/library/5134.html

About the author

		This article brought to you by IBM Rational

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top