What API’s are Available for RTC and What Can You Extend?

This post is about what is available as API for RTC. I will try to provide you with some information about the available API’s. It was confusing to me in the beginning, so I assume others face the same problem.

This post assumes you already read the post about Setting up Rational Team Concert for API Development. Learning to Fly contains references to the most important posts for beginners. Please also consider to look into the Interesting Links page for more examples and downloads.You should understand the RTC Process Fundamentals if you want to do any extension or automation.

The post RTC Process Customization – What you can and cannot do is also a great resource to understand the basics.

The first API’s are only mentioned for completeness. They are not covered in this series of posts, but might be in the future.

REST and OSLC APIs

RTC provides some REST API’s that can be used to access and manipulate data. It also provides OSLC based APIs to access some of its data. See Consuming Rational Team Concert’s OSLC Change Management V2 Services to get started. See the Open Services for Lifecycle Collaboration Workshop and Using Perl to access the JAZZ REST API as an entry point. See Lyo OSLC 4J as a potential framework to access OSLC and REST APIs. This blog post provides you with a different browser extension to use for creating REST and OSLC URL’s.

JavaScript API

RTC provides a limited JavaScript API that can be used for Attribute Customization. The JavaScript API is very limited and allows only to access attribute data in the context of the work item the attribute customization runs. See this blog post or go directly to the Process Enactment Workshop for the Rational solution for Collaborative Lifecycle Management 2012 for some examples.

Relevant links

Available Java APIs

There are really two Java API’s available in RTC, and although they have much in common, there are differences that are important to understand if you want to use them. The following API’s are available

• The Server API that is used in the server part of RTC (and JTS)
• The Client API that is used by the Eclipse Client and the Plain Java Client Libraries

The server API is used by server extensions. Server extensions must extend com.ibm.team.repository.service.AbstractService. To get other services use com.ibm.team.repository.service.AbstractService.getService(Class) providing a server service class. Note, the server services used must be entered as prerequisite in the server extensions plugin.xml.

The client API is typically retrieved by using com.ibm.team.repository.client.ITeamRepository.getClientLibrary(Class) providing a client service class.

Please see the relevant examples for details.

RTC Server API

The RTC Server API is used in extensions to RTC that are deployed on the server. Examples for these kind of extensions are Operation Advisors, Operation Participants, Server Tasks and other extensions that are run on the server. The RTC Server API is shipped with the RTC SDK that you set up to have an environment for development. This API is typically found in packages called com.ibm.team.*.service and the interfaces are usually named *Service or *Server for example IWorkItemServer.

This blog has several examples for how to extend RTC using the server API. For example

RTC Common API

Parts of the API are available on the client and on the server. The way you get the API depends on if you have a client or a server extension, however, the services are available as client libraries as well as as services. This API is typically found in packages called com.ibm.team.*.common and the interfaces are usually named *Common for example IWorkItemCommon. In some cases the required services are provided by the extension mechanism. This allows to write some extensions that run on the server, as well as on the client. A good example are Attribute Customization providers. You can find examples in these posts

RTC Client API

The RTC Client API is used in Extensions to any of the Eclipse based RTC clients as well as in the RTC Plain Java Client Libraries. This API is typically found in packages called com.ibm.team.*.client and the interfaces are usually named *Client for example IWorkItemClient. The RTC Client API is shipped with the RTC SDK and partially shipped with the Plain Java Client Libraries.

What? The Client API is shipped twice? Why would anyone do that?

RTC Client SDK

The reason for shipping the client API in the RTC SDK and the Plain Java Client Libraries is really simple. You need it in the SDK to develop extensions for the Eclipse based RTC clients. The SDK provides you with the source code and allows to search the code in the Eclipse Plugin Development Environment PDE. Strictly speaking, you would not need the source code to develop the extensions, because the Eclipse client has the relevant parts of the API already installed as plug in’s and that is enough to be able to write extensions. However, it makes development so much easier. The RTC (client) SDK also ships some internal classes and tests that you can use to find examples for the API usage.

Plain Java Client Libraries

If you just want to run a small Java application to do some automation outside of the Eclipse client, you would need only the JAR files for the API, and some JAR files that it depends upon. It would be quite some effort to identify the JAR files in the Eclipse client you need. So the Plain Java Client Libraries  has the required JAR files bundled for you to use. This makes setting up a Plain Java Client application you developed much easier.

The Plain Java Client Libraries ship only the documented and public API. They are missing a lot of RTC Eclipse client specific code.

The post A RTC WorkItem Command Line Version 2 provides an extensive example for using the API to create and modify work items.

Extending Eclipse based Clients

When mentioning you can develop Extensions to the Eclipse based RTC Clients, that was no typo. The Jazz SCM Command Line as well as the Jazz Build Engine and Toolkit are also Eclipse based clients that can be extended. You can find an example for extending the Jazz Build  Toolkit in this post from Robin. The Eclipse Extension mechanism works for all Eclipse based clients.

There are several posts on this blog that talk about the client API. For Example

What is the Difference Between Client And Server API

Although you can often reuse the client API some things are different in the client and the server API so you need to be careful. The Services and Client Libraries have differences in how they are called and what they provide. Creating, getting and manipulating elements is sometimes slightly different in both API’s and you might need data on the server that you don’t have on the client and the other way round.

What can you Extend and Access?

The Server API allows to extend

• The RTC Server with operational behavior, event handling, jobs and the like.

The Client API allows to extend

• The Jazz  Build Engine and the Build System Toolkit
• The SCM Command Line
• The RTC Eclipse client
• Potentially any other Eclipse based client

The Client API allows you to access

• The RTC server and the data in its repository
• Parts of the JTS server, for example the User and License management

What can’t you extend?

As far as I know you can not extend the Visual Studio Client, nor the Windows Shell, because both are not Eclipse based.

The available Extension Points and Operation ID’s are explained here.

Why is the API Designed the Way it is?

If you start working against the API, you will realize that, from a human perspective, sometimes things appear overly complicated. For example if you work with enumerations, you need to look up all the literals to find one that has the same Label value as your string you want to use to set it.

My personal view on this is, the API is a byproduct of what needed to be developed to design clients and servers. In the client for example, you will typically have views, that need to show more than one element. Or you have drop down boxes to select enumeration values. This just requires to get at all the data such as literals, project areas etc. needed to be displayed in that context. There is just no need to be able to provide a method that takes some string and looks up an item that has a display value that matches that string.

If you want it to be easier, you can always wrap pieces of code up to better fulfill your requirements and reuse that code.

Don’t Mix Client and Server API

You need to be really careful, to understand what client API is and what server API. Client API usually has client in the package name and you get the services with getClientLibrary() calls. Server code usually has server in the package name and you get services using gerService() from the AbstractService type you extend.

There are some packages with common in the package name, and contain common code that can be used on client and server. Still, you would get the common classes using getService() on the Server and the analogous Client Library with getClientLibrary() on the client.

If you mix the Client and the Server API in a server extension, you might find it works in Jetty – because that potentially has the client and the server part available in the SDK. But once you deploy the  extension on the server it will not load because it can’t find the required bundles. The same applies for client extensions.

The next post will go into the details of the client API.