This document provides a road map to the Supplemental Archive for the IBM Rational CM API, Release 7.1 Beta 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.
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.
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."
The "projects" subdirectory of the archive contains sample code that demonstrates the use of the IBM Rational CM API. These samples are presented as Eclipse project folders that can be imported directly into an Eclipse workspace. If you're using another IDE, you will find the source in the "src" subdirectory of each project directory.
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.
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 specfied. To execute one of these pre-compiled applications, execute the JAR file supplying a classpath that includes the required IBM Rational CM API jars. For example, to run the HelloWorld application, type
java.exe -cp <classplath> HelloWorld.jar
All of these sample applications require that the CM API jars to be on the specified <classpath>.
If the product jars are in their normally installed positions, then only the stpwvcm.jar file needs to be on the given <classpath>. So, on a Windows machine, the following command should be sufficient to run the HelloWorld sample application
java.exe -cp "c:\Program Files\Rational\common\stpwvcm.jar" HelloWorld.jar
java.exe -cp <classpath> stptool.jar 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.
The "plugins" subdirectory contains sample Eclipse plugins demonstrating the use of the IBM Rational CM API in an Eclipse plugin.
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.
Consult the scout project Javadoc for help on using and understanding this sample plugin.