Java APIs in Build
In this article we will provide examples of some of the tasks you can perform via a plain-java client. The following interfaces in the com.ibm.team.build.client and com.ibm.team.build.common plugins are available for Java clients. Note that for the Team Concert 1.0, 2.0 and 3.0 releases there is no API guarantee, however we try to avoid making changes that are not backwards-compatible unless unavoidable. There were some backwards-incompatible changes between 1.0 and 2.0 where ITeamArea arguments were generalized to IProcessArea (these are binary-incompatible, but not source-incompatible). Code developed against the 2.0 client API should work unchanged against 3.0.
See the javadoc in the above interfaces for more information.
In the sections below, we highlight the code necessary to perform each of the following examples. To view the complete example code and information on how to run them, see the Running the Examples section at the bottom of the page.
First things First - Connecting to the Repository
In any interaction with the repository, you first have to be connected. The following snippet shows how:
Requesting a Build
The example below shows how to request a build for a given build definition. Note that the build definition and an active build engine supporting that definition must already exist for the build request to succeed.
Setting the Build Label
The next example shows how to programatically set the label on a build. As in the example above, the build definition and an active build engine supporting that definition must already exist.
We then set the label attribute and save the build result object. Note that in order to modify the build result we must first get a working copy, otherwise the build result is not mutable. The working copy is the object we modify and then save.
Querying for Builds with a Given Tag
This example shows how to create and run a query for build results in the repository - in this case querying for all build results with a given tag.
In the example above, once we've completed the query, we fetch the list of build results and iterate through them printing out the build label.
Querying for Build Engines that support a given Build Definition
This example shows how to create and run a query for build engines in the repository with a given build engine ID.
In this example above, once we've completed the query, we fetch pages of build definitions and print them out per page.
Running the Examples
The following list contains links to the complete code for each of the examples described in this article:
To run these examples, you'll need a running server and the client libraries included in the JazzPlainJavaClient-*.zip (available as a separate download). See theRtcSdk wiki page for details on setting up a Java project in Eclipse from the plain java download. Following those instructions will result in a new Java project linked to the correct Java libraries and containing a java package named snippets. Copy each of the examples above into the snippets package in the new project.
Create a new user on the server with user id test and password test (the password defaults to 'test' so you should not need to explicity set it). Assign the JazzAdmin permission to the new user and grant them the developer and build licenses.
The examples require a build definition with id BuildSnippetsExampleBuild. We will also need to run some instances of that build so that we can tag them for the QueryBuildsWithTag example. See the CommandLineBuild page for instructions on creating the build definition and running some builds. Remember to usetest/test as the username/password and to specify BuildSnippetsExampleBuild as the build definition id.
Once you have some completed builds, open some of them in the build result editor and tag them with BuildSnippetTag, then save them. The builds with this tag should be found when we run the QueryBuildsWithTag example.
- Specifying Parameters
You can run each example by right-clicking the file and selecting Run As -> Java Application. The first time you run each example, you should see a usage message in your console since you haven't yet provided the correct parameters. Once you've run the example once, you can open your launches dialog and edit the launch for that example and provide the correct parameters as shown in the table below.