[ RTC Client Lib ] Build-related Java programming examples

Source From Here 
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. 

* ITeamBuildClient - provides access to Build objects in the repository
* ITeamBuildRequestClient - api for creating, retrieving and manipulating build requests
* IBuildResultQueryModel - provides model information for querying build results
* IBuildEngineQueryModel - provides model information for querying build engines

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. 

* Request a build
* Set the build label
* Query for builds with a given tag
* Query build engines that support a given build definition, given a build definition ID

First things First - Connecting to the Repository 
In any interaction with the repository, you first have to be connected. The following snippet shows how: 

view plaincopy to clipboardprint?

1. private static class LoginHandler implements ILoginHandler, ILoginInfo {  
2.   
3.     private String fUserId;  
4.     private String fPassword;  
5.   
6.     private LoginHandler(String userId, String password) {  
7.         fUserId = userId;  
8.         fPassword = password;  
9.     }  
10.   
11.     public String getUserId() {  
12.         return fUserId;  
13.     }  
14.   
15.     public String getPassword() {  
16.         return fPassword;  
17.     }  
18.   
19.     public ILoginInfo challenge(ITeamRepository repository) {  
20.         return this;  
21.     }  
22. }  
23.   
24. public static ITeamRepository login(String repositoryURI, String userId, String password, IProgressMonitor monitor)  
25.         throws TeamRepositoryException {  
26.     ITeamRepository teamRepository = TeamPlatform.getTeamRepositoryService().getTeamRepository(repositoryURI);  
27.     teamRepository.registerLoginHandler(new LoginHandler(userId, password));  
28.     teamRepository.login(monitor);  
29.     return teamRepository;  
30. }  
31.   
32. public static void main(String[] args) {  
33.     String repositoryURI = args[0];  
34.     String userId = args[1];  
35.     String password = args[2];  
36.   
37.     TeamPlatform.startup();  
38.     try {  
39.         IProgressMonitor monitor = new NullProgressMonitor();  
40.         ITeamRepository teamRepository = login(repositoryURI, userId, password, monitor);  
41.     ...  
42.     } catch(Exception e){}  
43. }  

The call to TeamPlatform.startup() initializes the platform. You must then register a login handler to provide the username and password, then callITeamRepository.login to connect. 

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. 

view plaincopy to clipboardprint?

1. ITeamBuildClient buildClient = (ITeamBuildClient) teamRepository.getClientLibrary(ITeamBuildClient.class);  
2. IBuildDefinition buildDefinition = buildClient.getBuildDefinition(buildDefinitionId, monitor);  
3.   
4. ITeamBuildRequestClient requestClient = (ITeamBuildRequestClient) teamRepository.getClientLibrary(ITeamBuildRequestClient.class);  
5. IBuildRequest buildRequest = requestClient.requestBuild(buildDefinition, true, monitor);  

The build definition object is first retrieved from the server using the ITeamBuildClient interface. The build is then requested using theITeamBuildRequestClient interface. Note that objects implementing both interfaces are retrieved using the ITeamRepository.getClientLibrary method. 

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. 

view plaincopy to clipboardprint?

1. ITeamBuildClient buildClient = (ITeamBuildClient) teamRepository.getClientLibrary(ITeamBuildClient.class);  
2. IBuildDefinition buildDefinition = buildClient.getBuildDefinition(buildDefinitionId, monitor);  
3.   
4. ITeamBuildRequestClient requestClient = (ITeamBuildRequestClient) teamRepository.getClientLibrary(ITeamBuildRequestClient.class);  
5. IBuildRequest buildRequest = requestClient.requestBuild(buildDefinition, true, monitor);  
6.   
7. String[] properties = new String[] { IBuildResult.PROPERTY_LABEL };  
8.   
9. IBuildResult buildResult = (IBuildResult) teamRepository.itemManager().fetchPartialItem(  
10.     buildRequest.getBuildResult(), IItemManager.REFRESH, Arrays.asList(properties), monitor);  
11.   
12. String label = "Set Build Label Snippet build";  
13. buildResult = (IBuildResult) buildResult.getWorkingCopy();  
14. buildResult.setLabel(label);  
15.   
16. buildClient.save(buildResult, monitor);  

In this example a build is requested as in the previous example. The build result handle is then retrieved from the resulting build request and is used to fetch the build result object. Note that we use the IItemManager.fetchPartialItem method and specify only the label property to be retrieved. We could also have used theIItemManager.fetchCompleteItem method to fetch the entire build result object. 

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. 

view plaincopy to clipboardprint?

1. IBuildResultQueryModel buildResultQueryModel = IBuildResultQueryModel.ROOT;  
2. IItemQuery query = IItemQuery.FACTORY.newInstance(buildResultQueryModel);  
3. query.filter(buildResultQueryModel.tags()._like(query.newStringArg()));  
4. query.orderByDsc(buildResultQueryModel.buildStartTime());  
5.   
6. ITeamBuildClient buildClient = (ITeamBuildClient) teamRepository.getClientLibrary(ITeamBuildClient.class);  
7. String[] parameters = new String[] { tag };  
8. IProgressMonitor monitor = new NullProgressMonitor();  
9. IItemQueryPage queryPage = buildClient.queryItems(query, parameters, IQueryService.ITEM_QUERY_MAX_PAGE_SIZE,  
10.     monitor);  
11.   
12. // print out the labels of the retrieved builds  
13. String[] properties = new String[] { IBuildResult.PROPERTY_LABEL };  
14. List buildResults = teamRepository.itemManager().fetchPartialItems(queryPage.getItemHandles(),  
15.     IItemManager.DEFAULT, Arrays.asList(properties), monitor);  
16.   
17. for (Object result : buildResults) {  
18.     IBuildResult buildResult = (IBuildResult) result;  
19.     System.out.println(buildResult.getLabel());  
20. }  

To peform a query of build result objects, you need to create an instance of IItemQuery and pass in the IBuildResultQueryModel.ROOT object as the input. You can then use the IItemQuery interface methods (such as IItemQuery.filter) along with the IBuildResultQueryModel methods to fine-tune the query. See the javadoc for more information. 

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. 

view plaincopy to clipboardprint?

1. IBuildEngineQueryModel queryModel = IBuildEngineQueryModel.ROOT;  
2. IItemQuery query = IItemQuery.FACTORY.newInstance(queryModel);  
3. IPredicate supportsDef = queryModel.supportedBuildDefinitions().itemId()._eq(query.newUUIDArg());  
4. query.filter(supportsDef);  
5.   
6. IItemQueryPage queryPage = buildClient.queryItems(query, new Object[] { buildDefinition.getItemId() }, IQueryService.ITEM_QUERY_MAX_PAGE_SIZE, monitor);  
7.   
8. if (queryPage.getResultSize() == 0) {  
9.     System.out.println("Zero build engines found for build definition '" + buildDefinitionId + "'");  
10. } else {  
11.   
12.     System.out.println("Found " + queryPage.getResultSize() + " build engine(s) for build definition '" + buildDefinitionId + "':");  
13.   
14.     int pageNum = 1;  
15.     while (queryPage != null) {  
16.   
17.         System.out.println("Page:" + pageNum++);  
18.   
19.         // print out a page of IDs of the retrieved build engines  
20.         String[] properties = new String[] { IBuildEngine.PROPERTY_ID };  
21.         IFetchResult fetchResult = teamRepository.itemManager().fetchPartialItemsPermissionAware(queryPage.getItemHandles(), IItemManager.DEFAULT,  
22.                 Arrays.asList(properties), monitor);  
23.   
24.         List buildEngines = fetchResult.getRetrievedItems();  
25.         for (IBuildEngine buildEngine : buildEngines) {  
26.             System.out.println(buildEngine.getId());  
27.         }  
28.         if (queryPage.hasNext()) {  
29.             queryPage = (IItemQueryPage) buildClient.fetchPage(queryPage.getToken(), queryPage.getNextStartPosition(), queryPage.getSize(), monitor);  
30.         } else {  
31.             queryPage = null;  
32.         }  
33.   
34.     }  
35. }  

This example is similar to the previous example, except it uses IBuildEngineQueryModel to query only supported build definitions. It also fetches partial items using a call that is permissions aware so it could distinguish between retrieved, not found and permission denied items. 

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: 

* RequestBuildExample.java
* SetBuildLabelExample.java
* QueryBuildsWithTagExample.java
* QuerySupportingBuildEngines.java

- Prerequisites 
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.