Supplemental Archive for IBM Rational CM API, Release 7.1.1

(C) Copyright IBM Corporation 1992, 2009.  All rights reserved.

This document provides a road map to the Supplemental Archive for the IBM Rational CM API, Release 7.1.1, which contains documentation and sample applications for developers wishing to use the CM API interface.

If you are reading the HTML version of this readme file from the archive, you can follow the embedded links to quickly view various parts of the archive.

1 Getting Started

Expand this archive into a directory of your choosing and then follow the instructions in the Programmer's Guide and accompanying tutorials to setup and explore the features of the IBM Rational CM API.

If you are going to be using the sample Eclipse projects included in the archive, DO NOT expand the archive directly into your Eclipse workspace. Follow these steps to examine all the sample material in Eclipse

o Start Eclipse in the workspace where you wish to do the evaluation.

o Expand this archive into some convenient directory not contained in the Eclipse workspace.

o Copy the product JAR files that you have installed on your machine into the "plugins/com.ibm.rational.stp.teamapi" subdirectory of the expanded archive. See the Programmer's Guide for the names of the JAR files to be copied and where they are installed.

o Define the classpath variable "RATIONAL_ARCHIVE" to point to the root directory of the expanded archive. (Click through [Window - Preferences... - Java - Build Path - Classpath Variables] to define a classpath variable.)

o Import the sample projects in the archive into Eclipse:

1 Click through [File - Import... - Existing Projects into Workspace] to bring up the Import dialog.

2 In the "Select root directory:" box, type in the root directory of the expanded archive (same as RATIONAL_ARCHIVE).

3 Click "Browse"

4 Three projects should now be displayed in the "Projects:" box, already selected: com.ibm.rational.stp.teamapi, samples, and scout.

5 Click "Finish" and these projects will be imported into your Eclipse workspace.

o [Optional] Associate the CM API Javadoc with the stpwvcm.jar file.

1 Expand the "com.ibm.rational.stp.teamapi" project in the Eclipse workspace and select the entry labeled "stpwvcm.jar"

2 Right click and select "Properties" at the bottom of the menu.

3 Select "Javadoc Location" in the left panel of the Properties dialog for the stpwvcm.jar file.

4 Replace the entry in the box labeled "Javadoc location path" with the path to the "api/doc" subdirectory of the archive--i.e. the equivalent of "/RATIONAL_ARCHIVE/api/doc". (If Eclipse cannot find the source using this setting, try using "/RATIONAL_ARCHIVE/plugins/com.ibm.rational.stp.teamapi/doc.zip".)

5 Close the dialog.

o [Optional] Associate the CM API source with the stpwvcm.jar file.

1 Expand the "com.ibm.rational.stp.teamapi" project in the Eclipse workspace and select the entry labeled "stpwvcm.jar"

2 Right click and select "Properties" at the bottom of the menu.

3 Select "Java Source Attachment" in the left panel of the Properties dialog for the stpwvcm.jar file.

4 Replace the entry in the box labeled "Location variable path" with "/RATIONAL_ARCHIVE/api/src". (If Eclipse cannot find the source using this setting, try using "/RATIONAL_ARCHIVE/plugins/com.ibm.rational.stp.teamapi/stpwvcmsrc.zip".)

5 Close the dialog.

Now, you're all set to examine, execute, and modify the samples provided in this archive.

2 Contents

Readme.html, readme.txt

This document, which gives an overview of the content of the IBM Rational CM API Supplemental Archive. See the first page of the Javadoc for additional information on changes made to the API since the 7.0.0 release.

2.1 The "api" Directory

The "api" subdirectory of the archive contains the source and Javadoc for the IBM Rational CM API.

The Javadoc provides the detailed technical documentation for the API. Read the Programmer's Guide to obtain a general overview of the API and a better understanding of its pervasive concepts.

To make the source and documentation available to Eclipse, open the properties dialog for the "stpwvcm.jar" item of your Eclipse project and establish the "api/doc" directory as its "Javadoc Location" and the "api/src" directory as its "Java Source Attachment."

2.2 The "projects" Directory

projects/samples

An Eclipse project containing a number of stand-alone sample IBM Rational CM API applications. This is the source project for most of the JAR files in the "apps" subdirectory of this archive. Documentation for these sample applications can be found in the Javadoc for this project.

This project is configured to reference the com.ibm.rational.stp.teamapi project. Before the project will compile, you will need to need to import that project into your workspace.

projects/scout

An Eclipse plugin project that uses the CM API to implement a browser for ClearQuest databases and ClearCase Remote Client servers. This is the source directory for the Eclipse plugin found in the "plugins/com.ibm.rational.teamapi.scout_0.1.1" subdirectory of this archive. Documentation for these sample applications can be found in the Javadoc for this project.

This project depends on the com.ibm.rational.teamapi plugin, so that plugin must be installed in Eclipse before this project will compile.

The "apps" subdirectory of the archive contains pre-compiled versions of the stand-alone sample applications defined in the "samples" project. Each application has its own JAR file, in which the appropriate main entry point has been specified. To execute one of these pre-compiled applications, execute the CLASS supplying a classpath that includes the required IBM Rational CM API jars and the application jar. For example, to run the HelloWorld application, type

java.exe -cp <classpath> com.ibm.rational.stp.client.samples.HelloWorld

All of these sample applications require the CM API jars and the application jar to be on the specified <classpath>.  You can also add these jars to your system CLASSPATH environment variable.

On a Windows machine, use the following command to run the HelloWorld sample application

java.exe -cp "HelloWorld.jar;c:\Program Files\IBM\RationalSDLC\common\stpwvcm.jar;c:\Program Files\IBM\RationalSDLC\common\stpcmmn.jar;c:\Program Files\IBM\RationalSDLC\ClearQuest\stpcq.jar;c:\Program Files\IBM\RationalSDLC\ClearQuest\cqjni.jar;c:\Program Files\IBM\RationalSDLC\ClearCase\web\teamapi\stpcc.jar;c:\Program Files\IBM\RationalSDLC\ClearCase\web\teamapi\remote_core.jar;c:\Program Files\IBM\RationalSDLC\ClearCase\web\teamapi\commons-httpclient-3.0.jar" com.ibm.rational.stp.client.samples.HelloWorld

apps/Browser.jar

The pre-compiled Browser application found in the "samples" project. Consult the Browser class Javadoc page for a description of what it does.

apps/CcBrowser.jar

The pre-compiled CcBrowser application found in the "samples" project. Consult the CcBrowser class Javadoc page for a description of what it does.

apps/CreateActivity.jar

The pre-compiled CreateActivity application found in the "samples" project. Consult the CreateActivity class Javadoc page for a description of what it does.

apps/CreateRecord.jar

The pre-compiled CreateRecord application (from the ClearQuest tutorial) found in the "samples" project. Consult the CreateRecord class Javadoc page for a description of what it does.

apps/CreateRecordCommand.jar

The pre-compiled CreateRecordCommand application found in the "samples" project. Consult the CreateRecordCommand class Javadoc page for a description of what it does.

apps/EditRecord.jar

The pre-compiled EditRecord application (from the ClearQuest tutorial) found in the "samples" project. Consult the EditRecord class Javadoc page for a description of what it does.

apps/Example.jar

The pre-compiled ClearCase Example application (from the ClearCase tutorial) found in the "samples" project. Consult the Example class Javadoc page for a description of what it does.

apps/ExecuteQuery.jar

The pre-compiled ExecuteQuery application (from the ClearQuest tutorial) found in the "samples" project. Consult ExecuteQuery class Javadoc page for a description of what it does.

apps/FindDatabases.jar

The pre-compiled FindDatabases application (from the ClearQuest tutorial) found in the "samples" project. Consult the FindDatabases class Javadoc page for a description of what it does.

apps/HelloWorld.jar

The pre-compiled HelloWorld application found in the "samples" project. Consult the HelloWorld class Javadoc page for a description of what it does.

apps/InstallCheck.jar

The pre-compiled InstallCheck application found in the "samples" project. Consult the InstallCheck class Javadoc page for a description of what it does.

apps/QueryCommand.jar

The pre-compiled QueryCommand application found in the "samples" project. Consult the QueryCommand class Javadoc page for a description of what it does.

apps/stptool.jar

A rudimentary command line interface to ClearCase, and ClearQuest implemented via the CM API. With the CM API product jars on your classpath, execute

java.exe -cp "stptool.jar;<classpath>" com.ibm.rational.stp.client.tools.ApiTool help

to get started. This will list a brief synopsis of all the commands available in this command-line interface.

Note: The source for this sample application is not available in this release.

apps/ViewRecord.jar

The pre-compiled ViewRecord application (from the ClearQuest tutorial) found in the "samples" project. Consult the ViewRecord class Javadoc page for a description of what it does.

plugins/com.ibm.rational.stp.teamapi

This plugin directory contains all of the non-product files needed to define the IBM CM API as an Eclipse plugin. To make this a complete plugin, you must copy all of the IBM Rational CM API product JAR files to this plugin directory (or a copy of it, if you prefer). These JAR files are installed with the IBM Rational Team products that are supported by the IBM Rational CM API and their location is specified in the IBM Rational CM API Programmer's Guide that is included in this archive.

Once you have copied the JAR files to this directory, you can either import it as a binary plugin project into your Eclipse workspace or, by copying it to the plugins directory of your Eclipse installation, you can add it as a permanent plugin to your Eclipse installation.

plugins/com.ibm.rational.teamapi.scout_0.1.1

This plugin directory contains the scout project compiled as an Eclipse plugin. To install this plugin into Eclipse, copy this directory and the plugins/com.ibm.rational.stp.teamapi directory directly to the plugins directory of your Eclipse installation and restart Eclipse.

Consult the scout project Javadoc for help on using and understanding this sample plugin.