The RTC SDK is about to change in 6.0.3

Since some time now, the RTC and Jazz Development teams are in discussion how to cope with the version compatibility requirements driven by Eclipse clients and the server API. In RTC 6.0.3 the SDK is about to be split into separate SDK’s for the Eclipse client and the Server. This will impact how the development environment needs to be set up and how extensions are developed. I will try to share a summary of what to expect here. I have so far only been able to experiment with development builds, there has not been an official release of the SDK for 6.0.3 yet.

Download the new workshop

Update * the new Extensions Workshop is finished for a while now. it can be found at the original Rational Team Concert Extensions Workshop location.

Why splitting the SDK?

The RTC Clients have been based on Eclipse 3.6 for a considerable amount of time now. This has been the case for the Jazz Servers as well. However, there is pressure on the server infrastructure for the need to support Eclipse 4.4.x and higher. On the other hand there are client applications that RTC needs to integrate with, that are lagging behind in adoption of new Eclipse versions.

As described in What API’s are Available for RTC and What Can You Extend? the RTC SDK currently contains the RTC Server API, the RTC Common API and the RTC Client API in one delivery. The RTC Common API is part of the RTC Server API as well as the RTC Client API. This is a potential problem when shipping the SDK and trying to keep the Server compatible to Eclipse 4.4.2 and above and being compatible with Eclipse 3.6 clients. As it looks, the RTC SDK will be split into two parts.

1. A RTC Server SDK bundling the RTC Server API and the RTC Common API compatible with Eclipse 4.4.x and higher
2. A RTC Client SDK bundling the RTC Client API and the RTC Common API compatible with Eclipse 3.6.x and higher

Impact of splitting the SDK

The split has various impacts on how extension development will now work. Please find below a short summary of changes that I have found necessary to perform the workshop.

Changes to section: 1.1 Download and Unzip the Required Files from jazz.net

The Server SDK Target Platform now requires an Eclipse 4.4.2 or higher. You can download the base Eclipse 4.4.2 client here. For example download the version Eclipse IDE for Java EE Developers. Install the client similar to described in the workshop. Then download the RTC Eclipse Client p2 install package and install this into your Eclipse 4.4.2.

In the Feature Based Launches download the new launcher442.zip. Unzip the zip file, browse to the enclosed JAR file and copy that into the dropins folder in the Eclipse client.

You might want to consider to do the following changes to the eclipse.ini file.

• Add a section -vm with an additional line for the java virtual machine to use. If you run Eclipse with a different JVM, e.g. from Oracle, consider to specify a JRE or JDK that is compatible with the one that ships with RTC. This vm would also be used in the workspace setup section.
• Add -showLocation in the org.eclipse.platform section; this shows the Eclipse workspace path in the upper border of the Eclipse client as below

  

  This makes it possible to actually work with multiple workspaces and knowing which an Eclipse instance is responsible for.

• A vmargs argument -Duser.language=en to make sure you get a consistent language in the menus if you want.

The image below shows the changes in my case

Changes to section: 1.2 Setup for Development

Once the SDK is split into two parts the Rational Team Concert Extensions Workshop can no longer be performed using just one Eclipse Workspace. An SDK is set up as a Target Platform in the Plug-in Development section. Since the SDK’s are now split, it is necessary to have two target platforms. Since it is not possible to have more than one Target platform active in one Eclipse workspace it is not possible to launch a server for debugging while running an Eclipse client from the same workspace.

The RTC Extensions workshop will have to be changed to set up two separate workspaces.

• One workspace will have to be set up with the RTC Server SDK as active Target Platform, for example using the path: C:\RTC603Dev\Workspaces\Dev1\Server
• The other  workspace will have to be set up with the RTC Client SDK as active Target Platform, for example using the path: C:\RTC603Dev\Workspaces\Dev1\Client

Both workspaces will require to be set up as described in the RTC Extensions workshop document in section 1.2 Setup for Development.However, you will set up different target platforms in this step. Using the Server SDK for the server development workshop and the Client SDK for the Client development workspace.

Please note, it is a good idea to configure Eclipse to use an external browser as well in this step.

Changes to section: 1.3 Setup the RTC Tomcat Server

I am modifying the WorkshopSetup tool and data to setup the RTC project named RTC Extension Workshop to support an easier setup for the two workspaces. Basically two separate RTC Repository workspaces will be available. One will provide the launch, the configurations and the components needed to develop the RTC Eclipse server extension part of the workshop. The other one will provide the launch and the components needed to develop the RTC Eclipse client extension part of the workshop.

As long as this is not yet available it is possible to start with the existing setup tool and the related repository workspace and to load that into the two Eclipse workspaces. One workspace has to be set up with the RTC Client SDK will be used for development of the client part. The other with the RTC Server SDK set up is used to develop the server parts. When performing the workshop it will be necessary to work with the two workspaces and use one for all the server related tasks and the other one with the client related tasks. When Accepting changes into these workspaces it is necessary to understand what is part of the client and what is part of the server or what is shared. The image below shows what belongs to what.

• The parts colored in blue are only related to server development
• The parts colored in yellow are only related to client development
• The uncolored parts are related to client and server development

Make sure to keep in mind which parts of the code are relevant for what. As an example, the project net.jazz.rtcext.workitem.extensions.ide.ui will not compile in the server development workspace. Similarly the net.jazz.rtcext.workitem.extensions.service project will not compile in the client development workspace.

Changes to section: 1.4 Complete Setup of Your RTC Eclipse Client

After Loading the repository workspace you have the choice to split the information into a sever part and a client part. For example you can duplicate RTC Extension Workshop Configuration and create one that only contains the client launches. Or you keep everything as it is and basically close the project areas you don’t need and ignore launches not needed. This is the easiest approach until a new Extension Workshop is available.

The initial step of copying the files services.xml and scr.xml is only needed in the server workspace. So when copying and importing, copy the files services.xml and scr.xml from your server’s ccm application in the installs\JazzTeamServer\server\conf\ccm folder into the RTC Extension Workshop Configuration project into the folder conf/jazz in the server development workspace.

When importing the plugins and features import the following into the server workspace:

• com.ibm.team.common.tests.utils
• com.ibm.team.jazz.foundation.server.licenses.enterprise-ea (or com.ibm.team.licensing.product.clm)
• com.ibm.team.licensing.product.rtc-standalone

When importing the plugins and features import the following into the client workspace:

• com.ibm.team.rtc.client.feature

Other considerations

As already mentioned, make sure to keep track which workspace you are working in and keep in mind that the server development part will not work in the client development workspace and vice versa.

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.

Summary

We have major changes coming up in the RTC Extension development area. The RTC Extension workshop needs to be adjusted and parts of the workshop lab needs to be reorganized and rewritten. This post explains what to consider for experienced users. Once there is an update to the Extension workshop lab material this post will be updated.

As always, I hope this helps users out there and saves them some time.

Is The Extension Deployed? How Can I Redeploy?

This is a question that comes up every so often in the forums. Unfortunately there is no place, I am aware of, where this really gets explained and it seems to require the knowledge of mysterious URL’s. Is there an easy way?

I wanted to always blog this, but somehow I just never did. Let’s unveil it now.

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.

Differences between Tomcat and WebSphere Application Server

The deployment process on Tomcat and WebSphere Application Server (WAS) is basically the same. The folders where you deploy the extension are the same within server/conf/ccm . The mechanisms described below work the same for WAS, except the location of the file built-on.txt.

Internal Tools

The best way to check if a server extension is deployed on a server is to use some Internal Tools. These hidden Internal Tools are also the easiest way to enforce redeployment of the applications and added extensions.

The internal tools can be accessed by injecting the string ?internal=true into the server administration URL for a Jazz application. This makes it available on the Server Administration page. It is possible to append the string above behind the URL for the main administration pages and then open the server administration. If the server administration page is already open and it contains an action the string needs to be injected before the # (hash tag) separating the action from the base URL.

The image below shows the injected string in the server administration page before the action.

The image below shows the URL when just appending the string before opening a specific server administration page.

An URL like

 https://<server>:<port>/jazz/admin?internal=true#action=jazz.viewPage&id=com.ibm.team.repository.server

shows the internal tools menu that can then be used to look at data that is usually not revealed.

Use the Component Status menu action to check if an extension is deployed. It opens the Component Status page with all components that are deployed. You can then use the browsers find functionality to search for your extension, or rather the name of the component you chose. If you followed my advice and chose a unique and easy naming schema, you should be able to find it. The image below shows the example of the RTC Extensions Workshop at the end of the list. Searching for rtcext revealed this in no time.

If your component does not show up, fix your deployment and try again.

Use the Server Reset menu action to trigger a re-provisioning of all extensions. Reboot the server after pressing the button. If a new version of an extension is deployed, this makes sure that the cache gets deleted and all the features, including the new version, are re-read.

Server Patch Extension

** Update ** Eric suggests another way to be able to see your extension in the comments below. Use the Server Patch Extension – https://jazz.net/wiki/bin/view/Main/ServerPatchExtension so that your plugin is listed on the CCM Admin Page

“Undeploy” or Deploy a Fix or New Version

To get rid of custom extensions, it is necessary to remove the files that belong to the deployed extension and then you have to force a server reset and redeploy. The files that typically belong to a server extension are

1. The provision profile file. This is a file with extension *.ini  located in the  server\conf\ccm\provision_profiles folder, created for the extension that specifies the feature and its site location
2. The extension specific site folder usually located in the folder server\conf\ccm\sites  that contains the site.xml and the plug-ins and features in sub folders

To update or deploy a new version you can:

1. Deploy the new version (overwrite the existing files mentioned above)
2. Force a server reset and restart the server

This works if the file names and the structure does not change. If you are not sure and you don’t want to leave any remnants you can

1. Undeploy the old version by removing all deployed files and folders
2. Deploy the new version
3. Force a server reset and restart the server

This is the most secure approach.

Force Server Reset and Redeploying using Internal Tools

The runtime of the Jazz servers caches information about deployed applications. If a new version of an application is deployed, the server would not pick that up and would not redeploy it. To enforce redeploying, it is necessary to request a server reset. There are several ways to do that.

One way is to use the Internal Tools and click on the Server Reset menu action. On the page displayed, click the Request Server Reset button. Next time the server is started, all plugins are redeployed.

Force Server Reset and Redeploying – Alternative Approach

If your server is not up, another way to enforce a server reset is to search for the file built-on.txt in the work folder of your application server. If this file is deleted, a server reset is performed the next time the server starts. For Tomcat you can find the file in the work folder of the application.

For the traditional WebSphere Application Server you should find the file located somewhere underneath the profile folder.

For the WebSphere Liberty Profile application server, you should find the file located somewhere underneath the workarea folder. E.g. in [Install Dir]\JazzTeamServer\server\liberty\servers\clm\workarea\.

Please note that the built-on.txt file is also located in WEB-INF folder in the WAR file and in the WEB-INF folder of the deflated war file. Don’t delete these files.

Summary

The Internal Tools provide an easy way to find out if a custom component is deployed and to request a server reset.

As always I hope this helps practitioners out there to be more effective.