CollabNet TeamForge Web Services Examples

What's in this bundle?

The downloadable CTF API sample bundle contains a set of six sample programs
designed to illustrate some of the more common methods for interacting with CTF
via the CTF SOAP API. As a teaching tool, these programs are both simple and
heavily commented. They interact with most of the CTF data objects including
Users, Projects, Trackers and Artifacts, Source code checkins and Tasks. For
those artifact types that are not explicitly covered, methods of retrieval,
modification and update are very similar. 

______________________________________________________________

Pre-Requisites

These samples programs are as self-contained as they can be. However, you
will need to obtain a java JDK and a copy of the ant build tool for building
the examples. The java JDK should be 1.7 or better and can be downloaded
from http://java.sun.com. The Apache Ant bundle should be version 1.7.0 or
better. Ant can be downloaded from http://ant.apache.org/

______________________________________________________________

Setup

Once you have the JDK and Ant downloaded, you must expand them into a
filesystem location at which you will later refer to them. Assuming you
expanded ant and java into /usr/local, you have to instruct your shell where
they may be found. 

This example is bash shell syntax:

export JAVA_HOME=/usr/local/jdk1.5_10
export ANT_HOME=/usr/local/apache-ant-1.7.0

And lastly put both java and ant in your path

export PATH=$PATH:$ANT_HOME/bin:$JAVA_HOME/bin

______________________________________________________________

Building and Running the Sample Programs

In order to build all the sample programs, use the ant build.xml that is 
located in the same directory as this file. It contains  convenience targets 
for each of the example programs, 1 through 7. 

The target "example1" runs the first example, "example2" the second, and so on.

The arguments passed to these examples include such settings as the URL for
your TeamForge installation, login credentials and project IDs. You must
edit these values in build.xml or the examples may not work as intended. Individual 
documentation on each example program can be found embedded in the java code. 

If, during the course of running these examples, you find a defect or have
a suggestion for improvement, please post a message in the discussion forum. 

Enjoy the CollabNet TeamForge API!

______________________________________________________________

Description of the samples

Example 1: Hello World

Let's start with "hello world" for the CTF SDK to test your environment setup
and basic configuration settings. This program simply attempts a login to
your CTF URL and prints a corresponding message.

Example 2: List of Projects 

Example 2 obtains and displays the list of projects of which the user
account passed in is an argument. When you use TeamForge through the web user
interface, much of your work is tightly bound within a project. The SDK is
no exception, and example two is a simple illustration of a common CTF coding
technique -- traversing lists of projects accumulating or looking for data.

Example 3: Bulk Change 

Nearly every CTF SDK program will do some form of data manipulation. Example
3 illustrates a very simple approach to implementing a "bulk change"
capability.In this case, we're merely setting the priority of all tracker
artifacts to 5, but many other more complex and useful SDK worflows will be
variants of this basic recipe.

Example 4: Document Manager 

Many of the tools within CTF operate on file-based data. The document manager
enables you to file away development related documents. The file release
manager gives you a place to store your software deliverables, which are
just files, after all. And every artifact in CTF can have one or more file
attachments associated with it.

Example 4 illustrates how to write a program which manipulates file-based
data. This short example uploads a local file into your document manager,
showing how simple it can be to work with files within CTF.

Example 5: Overloaded Members 

Ever feel like you're the most overloaded member of your development team? If
you use CTF with example 5, you'll know for sure! Example 5 shows a simple
approach to finding your project member with the most hours of incompleted
tasks allocated to him/her. This basic approach can be made more complex to
provide a wide variety of task based statistics.

Example 6: Coding Guru

In the previous sample we used the SDK to find the user with the most assigned
tasks. In this example we take it a step further -- what team member is a
"coding guru without parallel"? Who on your team submits the most code? Using
the CTF SDK it's easy to find out since code submissions and their associated
meta-data are modeled within the CTF database.
