• CollabNet TeamForge Web Services Samples

    Product:
    CollabNet TeamForge

    Component:
    Web Services

    Summary:
    Samples for the CollabNet TeamForge Web Services


     

    What's in a bundle?

    The downloadable CollabNet SourceForge Enterprise API sample bundle contains a set of seven sample programs designed to illustrate some of the more common methods for interacting with CollabNet TeamForge via the CollabNet TeamForge SOAP API. As a teaching tool, these programs are both simple and heavily commented. They interact with most of the TeamForge 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.

    Note that, by default, these samples are tailored to the most recent TeamForge release. However, if you are still using the legacy SourceForge Enterprise 4.4, you can run those examples via a command-line switch, ie. "ant example1-44", as opposed to the default "ant example1".

    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.5 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, you need only issue the command and build. During the build you should see some informational messages flash past the console, but any errors indicate a situation that must be fixed. If, during the build process you realize that any build settings must be changed, the file ./properties/build.properties holds all the variables and settings used by the ant buildfile. It is likely that if you need to tweak the build process, only build.properties should be edited, not the ant file itself.

    There are convenience targets for each of the example programs, 1 through 6, that supply command line arguments and then invoke the sample programs. 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 sourceforge installation, login credentials and project IDs. You must edit these values in ./properties/build.properties or your examples will not work. 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 SourceForge Enterprise API!

    Download the Samples

    All samples are contained in one zip file.

    Example 1: Hello World

    Let's start with "hello world" for the CollabNet SourceForge Enterprise SDK to test your environment setup and basic configuration settings. This program simply attempts a login to your CollabNet SourceForge Enterprise 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 SourceForge 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 CollabNet SourceForge Enterprise coding technique -- traversing lists of projects accumulating or looking for data.

    Example 3: Bulk Change

    Nearly every CollabNet SourceForge Enterprise 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 CollabNet SourceForge Enterprise 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 CollabNet SourceForge Enterprise 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 CollabNet SourceForge Enterprise.

    Example 5: Overloaded Members

    Ever feel like you're the most overloaded member of your development team? If you use CollabNet SourceForge Enterprise 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 CollabNet SourceForge Enterprise SDK it's easy to find out since code submissions and their associated meta-data are modeled within the CollabNet SourceForge Enterprise database.

    Example 7: Users, Groups and Roles

    This example will print out the groups a user belongs to, as well as the roles they have in the given project.