New Version and Now What? Experiences With SDK and Plain Java API across Tool Versions


There is a new version of RTC – what does that mean in the context of my automation Plain Java Client Libraries tools and my Extensions based on the SDK? This very valid question was recently asked on Jazz.net at least partially in this question.

I looked into it as far as I was able to and answered it briefly in the forum. I think it is worth adding a blog post as well.

Please be aware, as always, this is my personal experience and not a statement of IBM. Please also remember, as stated in the disclaimer, that this comes with the usual lack of promise or guarantee.

Just Starting With Extending RTC?

If you just get started with extending Rational Team Concert, or create API based automation, start with the post Learning To Fly: Getting Started with the RTC Java API’s and follow the linked resources.

You should be able to use the following code in this environment and get your own automation or extension working.

Java APIs

As described in this post, RTC has at least the following Java APIs:

  1. Plain Java Client Libraries – for stand alone Java client applications
  2. The RTC client side SDK – for Eclipse client and other eclipse based extensions
  3. The RTC server side SDK – for server side extensions

It is somewhat important to distinguish between the different API’s because there are different dependencies on versions in extensions using the SDK and Plain Java Client Library based Java Tools.

Versions in Extension vs. in the Plain Java Client Libraries

A Plain Java Client Library tool just requires the classpath to include a version of the Plain Java Client Libraries. It just calls the classes available and does not check for any version information.

The Extensions plug-in manifest can specify dependencies to features, plug ins and other objects available in the SDK. These dependencies optionally can include a specification for the version number required by the extension. It is possible to specify no version, a minimal version, a range and a specific version of the dependent object to be required for an extension.

Plug In Version Dependencies

Plug In Version Dependencies

If you have a dependency specified this way and the dependency can not be satisfied by the available version, your plugin will not load.

Client vs. Server

It is also necessary to distinguish between client extensions and server extensions.

A client extension runs standalone or in a client and can potentially run in any version of the client. The libraries used – Plain Java Client Libraries or client SDK installed that come with the client – have a version.When the client connects to the server the first thing the server checks is, if the clients version is compatible.

The RTC Development Team attempts to provide N-1 compatibility from client to server. This means, the RTC Server should be compatible with clients with lower minor version numbers and 1 Major version number. This is handled in the server as mentioned above. Looking at RTC 4.x it should be possible to access the 4.x server with clients of smaller 4.x versions down to a 3.x client (N-1).

The server checks the clients version and rejects a connection if the versions are known to be incompatible. N+1 is not tested and rated as incompatible. So it is not possible to connect a RTC 4.0.3 Eclipse client with a RTC 4.0.1 server. The server won’t accept the connection as displayed below. Please note, this is also true for a Plain Java Client Library client.

4.0.3 Client Incompatible to 4.0.1 Server

4.0.3 Client Incompatible to 4.0.1 Server

Client/Server Compatibility Summary

Please see the Infocenter for the most current client/server compatibility data. The information is also provided in this TechNote.

Running Plain Java applications inherits the N-1 compatibility that is attempted, if it was achievable.

I ran a work item creation Plain Java Client Libraries app from within 3.0.1.1 against a RTC 4.0.3 server with no problem. Same with 4.0.3 clients against 5.0.x servers and 5.0.x clients against 6.0.x servers.

If the server version is more than 2 major versions ahead of the used Plain Java Client Libraries, the client will fail with a version incompatibility error. The same happens if the server version is smaller than the plain java client libraries. Provide a correct and compatible version of the Plain Java Client Libraries.

An RTC client SDK Extension based on the SDK  deployed in a client inherit the N-1 compatibility, if it was achieved.

If you have an extension in the client deployed (for example the RTC 3.0 Eclipse client), the client should be able to connect to servers with higher version numbers  as explained above. So the client extension should run – provided it does not depend on a server side extension that is not deployed in that server.

Extensions, Version Compatibility and Upgrade

What is missing is what happens to my extensions that have been created with earlier versions of the client or server SDK.

I have upgraded my extensions from 3.x to 4.x over the years. My experience so far is that it always was a smooth transition. I have seen very little changes in the API, some few deprecated classes. The only major changes I have seen are new API’s and in RTC 3.x permission aware read access. It is necessary to think about unavailable read access in RTC 3.x or higher. In RTC 2.0 there was no read access restrictions and you could always read any data. Make sure your RTC extension does not run in an environment that violates the assumptions made when it was created.

To upgrade, I usually set up a new development workspace (I am now working with 4.0.1 and looking into going to 4.0.3 see https://rsjazz.wordpress.com/2013/02/28/setting-up-rational-team-concert-for-api-development/ ). I usually load or import my extensions created with older SDK versions and make sure they do compile, debug or test them quickly. I would create the update site from this version and deploy it.

Avoiding Version Dependencies in Extensions

However, it is not always necessary to do this. If you make sure there is no version conflict in the required plug-in dependencies, a plug in created in an earlier version should run in a newer version, unless there are breaking API changes such as classes or packages renamed or made unavailable.

I just built the Build On State Change Participant from the RTC Extensions Workshop with 3.0.1.1 and deployed it in 4.0.3 client and server. It worked as expected in both the client as well as the server without rebuild. The dependencies in the Example don’t specify a version number they require and therefore the deployment is not rejected.

However, since there can be API changes in newer versions, it is a good practice to test your extensions with a newer SDK anyway.

Summary

RTC supports N-1 compatibility between clients and servers, but not N+1 compatibility. If you have client extension or Plain Java Client Libraries based automation, the versions used should be equal or less than the server versions used.

Eclipse Extensions based on the SDK can be made somewhat version independent as long as there are no API changes that break the interface contracts.

As always I hope this information is useful to others and helps them with deploying their RTC or CLM solution.

Advertisements

About rsjazz

Hi, my name is Ralph. I work for IBM and help colleagues and customers with adopting the Jazz technologies.
This entry was posted in CLM, Jazz, RTC, RTC Extensibility and tagged , , , , . Bookmark the permalink.

2 Responses to New Version and Now What? Experiences With SDK and Plain Java API across Tool Versions

  1. Angel Corona says:

    Hello rsjazz:
    I have just tried and install RTC Client 4.0.3 in my work laptop (included in the same package along with RDz); this was to connect to an RTC Server 4.0.2.
    When trying to establish the connection I received a message like the one you posted, but with the corresponding versions I just mentioned, that is:
    “Your client is version 4.0.3, and the server is version 4.0.2. These versions are not compatible”.
    I thought this was normal behavior until I saw this article of yours.
    If I understood well, this shouldn’t happen since “RTC supports N-1 compatibility between clients and servers”.
    Could you please explain a bit?
    Thank you

    • rsjazz says:

      As described in the article, your client can have a lower version number than the server (N-1) but not the other way around. This is done, so that the server can be upgraded while the clients can stay on the lower version. What you describe above is N+1 compatibility from client (4.0.3) to server (4.0.2) which is not supported. N stands for the server version.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s