< Previous | Next >

Setting up and installing CM API

Before you can use the CM API, you must add files to your class path and have a licensed version of the Rational® product installed.
The CM API is a common component for performing operations on Rational products. To use this API with a Rational product, you must have that product installed on your system. You must also copy the CM API files that are installed on your system when you install the Rational product to your class path.
The CM API files required for working with Rational ClearQuest® resources include files that are required for all CM API resource types and files that are required for Rational ClearQuest resources. These Java™ packages are required to perform Rational ClearQuest operations using the Rational CM API.
  • javax.wvcm: The workspace versioning and configuration management package (WVCM).
  • com.ibm.rational.wvcm.stp: The Rational software team package is an extension of the WVCM package. This package contains the interfaces of the Rational CM API and provides the common object model for Rational product resources. This package is independent of product-specific repository or implementation boundaries.
  • com.ibm.rational.wvcm.stp.cq: A product-specific extension that provides access to the Rational ClearQuest databases. This package contains functions that provide fuller (product-specific) access to the functionality of a ClearQuest database and its underlying resources.

Although you should be able to cut and paste the code in this document into compilable Java, it has not been compiled and may contain typographical errors that prevent it from being compiled. Complete, compilable versions of these examples can be found in the Eclipse project named samples found in the supplemental archive file distributed with the documentation for the Rational CM API.

The Rational CM API JAR file and other required JAR files are installed by default in the following locations. install-dir represents the directory into which the Rational product files have been installed. By default, this directory is /opt/rational on the UNIX® system and Linux®, and C:\Program Files\IBM Rational on Windows® systems.
  • On Windows systems:
    • <install-dir>/Common/stpwvcm.jar: The Rational CM API interface JAR file.
    • <install-dir>/Common/stpcmmn.jar: A common implementation JAR file.
    • <install-dir>/ClearQuest/stpcq.jar: Extension for the ClearQuest product.
    • <install-dir>/ClearQuest/cqjni.jar: A Rational ClearQuest JAR file.
  • On UNIX and Linux systems:
    • <install-dir>/common/stpwvcm.jar
    • <install-dir>/common/stpcmmn.jar
    • <install-dir>/clearquest/cqweb/lib/stpcq.jar
    • <install-dir>/clearquest/cqweb/lib/cqjni.jar

To use the Rational CM API JAR files you must add all their locations to your class path.

To access the Rational CM API from an Eclipse plugin you can import the file com.ibm.rational.stp.cmapi.zip and samples projects into Eclipse, or you can follow these steps:

  1. Create an Eclipse plugin using the files packaged in the com.ibm.rational.stp.cmapi.zip file.
  2. To add the Rational CM API plugin to your runtime configuration, copy the plugin into your Eclipse instance or create a new extension install site. This creates a new directory for the Rational CM API (for example, C:\eclipse\plugins\com.ibm.rational.stp.cmapi). This new plugin is a simple self-contained Eclipse plugin consisting of the Rational CM API JAR files plus the product-specific JAR files. Note that the .zip file does not contain the actual product JAR files.
  3. After creating the plugin directory, each installed JAR file must be copied from its installed location into the new plugin directory. Each JAR file requires the Rational CM API JAR file. The plugin is available for use the next time you start Eclipse.
  4. To use the Rational CM API from your plugin, identify com.ibm.rational.stp.cmapi as a dependency.
You are now ready to begin writing Java programs with Rational CM API.
You must have a licensed and installed version of Rational ClearQuest in order to use the Rational CM API with ClearQuest resources. If you install and configure the JAR files but do not have the corresponding product installed, calls to that Java package fail.

Lesson checkpoint

Now that you have set up your system for programming with CM API, you are ready to begin learning the CM API object model and programming model.
In this lesson, you learned the following:
  • The relationship between CM API and Rational ClearQuest
  • How to set up your system for programming with CM API
  • Which files in CM API are required for your system
< Previous | Next >

Feedback