Learning To Fly: Getting Started with the RTC Java API’s


I intend this to become the beginners guide for the RTC java API’s. The reason is, I spend far too much time on the forums trying to answer beginner questions on how to get started over and over again. I intend this post to be my link to answer these questions without having to repeat everything all over.

Where to Start?

You first have to understand what API’s are available and what you can extend. If you don’t understand these basics, you can’t decide on how to proceed. It is also a good idea to understand RTC Process Customization and what you can and cannot do.

Setting up Your Development Environment

If you determined you are interested in one of the Java API’s, you need to set up your environment for Java API development. It is extremely important to perform the steps in that post to have an environment, that has the RTC SDK installed as well as the Plain Java Client Libraries. Do the whole workshop even if you just want to use the Plain Java Client Libraries to code up some automation. This familiarizes you with the concepts of plug-ins and give you some first glimpse on the API.

Even if you intent to develop only Plain Java Client Libraries, you should use a plug-in project to develop your code, because that allows to trick the Eclipse Plugin Development Environment (PDE) into showing you the whole source code of the RTC SDK. It requires to set up your environment as explained in Setting up Rational Team Concert for API Development.

This allows you to

  • See the comments on interfaces, classes and on methods
  • Search interfaces, classes and methods even with using an asterisk if you are not sure about the names and packages
  • Search for references to interfaces, classes, methods, extension points to go looking for inspiration and example code

Search The APIGetting started with the RTC Plain Java Client Libraries

To understand how that works read the post Understanding and Using the RTC Java Client API. Especially read the sections

  • Getting Started With Developing for the Plain Java Client Libraries
  • Debugging Client Code and Finding Information about the API
  • Prepare Your Project to Allow Debugging
  • Finding Information About the API

You should carefully read the whole post Understanding and Using the RTC Java Client API, as it explains how the basic mechanisms in the API work. This is also interesting if you intent to write server extensions.

Getting started with Eclipse Client and Server Extensions

If you are not (yet) interested in this section skip to the next sections and go to “Where can I find Examples and Example Code?“.

The best place to start is following the Rational Team Concert Extensions Workshop. This provides you with a fully set up environment for debugging and guides you through all the important steps that are necessary to develop client and server extensions. You might also want to look at Bartosz Chrabskis post How to create Rational Team Concert – Advisor & Participant Extension (step by step) and the related video for creating a participant and the video for creating an advisor.

RTC provides a lot of ways to extend the Eclipse based clients and the server. The most important in general are

  • Pre-conditions which are also referred to as Advisors, because they drive the process advisor behavior of operations
  • Follow-up action which are also referred to as participants, because they participate in the process behavior of operations
  • Attribute Customization which are also referred to as providers, because most of them provide values for work item attributes; please  find examples here
  • Components which are used to group extensions

The wiki topic Team Process Developer Guide provides a great overview about what you can do and what the rules are.

On the RTC Server side it is also possible to create asynchronous tasks, that can perform operations such as event generation and mail notification. An example with code and explanation can be found in the post Due Date Notifier – an Asynchronous Task Example.

There are additional extension points available on the client and on the server that can be used. Some examples are

  • Eclipse Client UI Extension points
  • RTC Web UI Extension points

There are still more, that I haven’t even looked at yet.

The most important part is to be able to develop and debug your server extensions using Jetty as explained in the Setting up Rational Team Concert for API Development. If you can’t do that, it is just a waste of time and I would consider not trying it out at all. You also always want to have a dedicated server for extensions development, deployment testing and functional testing.

The code used in advisors and participants is very similar except that the interface used is different and the result that is returned is also different.

Advisors and participants always run in the context of the user that calls the operation. This means they can only access data the user is able to access and perform operations the user is permitted to.

In advisors it is not permitted to modify the element for which the advisor is triggered. In participants this is allowed.

Participants that modify or create elements have to perform an additional save for the objects modified. Please note that this can trigger the same or another participant to be executed. This can result in a server crash, if it causes a recursive descent for a recursion that does not stop. To prevent that, it is possible to pass additional arguments in the save that the sub-sequentially called  participant can use to prevent running into a recursion. See for example this post for how that can be used.

The Extension Points and Operation ID’s to assign advisors and participants to the specific operation to work for can be found here.

In general it is the best approach to extend the RTC Server if at all possible. The reason is that this makes deployment easier. Deployment basically has to only happen on the server and deploying on all the clients can be avoided.

Deploying Extensions

If, and only if, your extension works in the Jetty based development and debug environment, you can deploy it on a real server. If you have not successfully tried your extension on Jetty as explained in the Rational Team Concert Extensions Workshop, it does not make any sense to try deploying it on a test server, let alone on a production server.

The Rational Team Concert Extensions Workshop handles deploying extensions very manual. The post A Custom Condition to Make Attributes Required or Read-Only by Role explains how this can be made more automatic in the section Deploying the Extension.

If the extension works on Jetty, the worst that can go wrong deploying it on a real server is that the dependencies in the extension include libraries that are not available on the server.

Other issues could be missing or not satisfiable dependencies, version issues, missing provision profiles or typos in the profile or corrupt files. This would show in the log file during server start up. Check the RTC Server log (i.e. server/logs/ccm.log).

Please note, a deployment error, a typo in the provision profile or missing or corrupted files in the sites folder can lead to the server crashing / not successfully starting up. The server start up can be interrupted and the server may not be reachable. See the server log for hints what might be the problem.

Please refer to the post Is The Extension Deployed? How Can I Redeploy? for checking if the deployment actually worked and for maintaining and upgrading server extensions.

Client extensions are required if the data that it works with is only available on the client, or if the extension is needed on client and server anyway e.g. for Java based attribute customization provider.

Where can I find Examples and Example Code?

There are countless examples out there, here on Jazz.net, on Stackoverflow and on many other blogs and sites. But apparently this is not enough or too hard to find. So I will try to put guidance on how to get started here.

The SDK

As already explained you can search for code that ships with the RTC SDK. This requires a working development environment as described above and here.

This Blog

You can find examples and example code in this blog. The easiest way to do so is to search the blog. This is really easy. Type the interface, method or any other clue you search for in the search window on the top right section underneath the banner and then use the “Search” button.

Search the BlogThen go through the list of posts that appear.

Most posts have working code attached for download as well.

There is also a page with Interesting Links that I maintain and add stuff that I come across. There are many links to examples for API and other interesting sources.

The Internet

We live in the times of search engines. In the past, like 25 years ago, you had to go to a public library and try to find relevant information or books that most likely were not there. Today you can use your preferred search engine and, with very few effort, find all you can ask for.  It is of course always easier to ask someone else to “Google that for me”, but it is way better to skill up to do it yourself in these Darwin times.

A good approach in this case is to just come up with some keywords, interface or class name and run the search engine on it. In my experience some words what you are looking for and RTC usually is enough. I find the interesting information usually on the first two pages. If not, I try to change and refine my query. Examples for typical search paattern are

  • “create work item java API RTC”
  • “access work item attribute java API RTC”
  • “RTC API IIteration”

If the results on page one are just too many and not promising it is possible – for Google at least – to limit the scope of the search to specific sites.

Using Search EnginesAn example for this pattern would be

  • “create work item java API RTC site:jazz.net”

This is most useful if you know that there has to be something there or recall something was there and you can’t remember where. I find this even more effective than using the search engine available on Jazz.net, because it usually shows the information I am looking for higher in the ranking.

Good sites are

Summary

If you want to get started with the RTC Java API’s, work through this blog post and the resources linked to it. I will try to extend this post with more detailed links for specific topics in the future.

As always I hope that helps users out there.

Advertisements

Getting started with BlueMix


Recently everyone has their heads in the clouds (no pun intended) and I decided to have a peek to find out what it is all about.

This post is a summary of my first experiences with the IBM BlueMix Cloud Computing offering and how I got started with developing my first applications for it.

Note: this is not an RTC API post. However, RTC is involved.

There are several posts of my peers. Look into Dan Toczala’s and Tekehiko Amano-san’s blog and see these posts about BlueMix:

There are more posts available.

BlueMix has been around for some time now here at IBM and I wanted to understand what it is providing. I have seen some high level presentations and demos already. Unfortunately I am not the kind of person that can learn to fly by reading books and looking at slides. I have to get things into my hands, use and experiment with it to understand how they work. This usually also involves accidents, painful crashes and recovery from them. This is however the best way for me to understand how it works and is most beneficial from my point of view.

As you can read in the BlueMix documentation about what BlueMix provides.

Citing the web site, IBM® Bluemix is an open-standards, cloud-based platform for building, managing, and running apps of all types, such as web, mobile, big data, and smart devices. It can be used to develop and run server applications.

You can use your own development environment as well as IBM Dev Ops Services to develop the applications and manage the source code.

You should familiarize yourself with the architecture of BlueMix to understand the details. I will try to use the concepts described there in the post with only a short summary what they represent.

BlueMix provides several ways to start with developing applications.

  • Runtimes are a preconfigutred set of resources used to run applications
  • Boilerplates are preconfigured containers used to run applications that usually also contain services
  • Services hosted by BlueMix provide capabilities such as session caches, persistance and other capabilities

Looking at the Runtimes there is support for Node.js applications Liberty for Java (a lean profile for WebSphere Application server), Ruby on Rails and others available.

Since I am not a Web developer but have some few JavaScript experience, I decided I wanted to go for Node.js. I got myself some material to learn about it first. After understanding the basic concepts by reading, I started to set up a local development environment.

Setup a local Node.js Development Environment

I followed http://www.nodeclipse.org/updates/ to install the local Node.js environment. I downloaded Node.js from http://www.nodejs.org/download/ and installed it as suggested in the previous link. I skipped CoffeeScript and I had a JDK 7 already on m machine.

Setup Eclipse for Node.js Development

I needed a local environment to be able to play with it and have a quick turn-around time. I downloaded Eclipse Juno, because I heard that would be the best option, and followed http://www.nodeclipse.org/updates/ to install what is needed into Eclipse.

Having done this, I was good to go and I was able to create Node.js projects in Eclipse and run and debug them locally.

I ran some examples until I felt reasonably familiar with how the language works and decided to pursue my quest to BlueMix.

Setup Eclipse with RTC

Since I intended to use Eclipse with RTC embedded to be able to use RTC against IBM Dev Ops Services, and not using Git for SCM (sorry guys, but I can’t do that), I downloaded the RTC 5.0 p2 install package from the RTC All downloads Page. After the download succeeded, I installed RTC into Eclipse. I logged into IBM Dev Ops Services from RTC using my Jazz.net ID and my IBM ID password. Weird.

However, now my local environment works with RTC and I can use any RTC repository, including IBM Dev Ops Services, to manage my work and source code.

Logging into BlueMix

I logged into BlueMix. Please note, you can use or create an IBM ID. This basically provides you with an evaluation period of some months.This should be easy to follow and work like a charm.

If you are an IBM’er you can use your Intranet ID. I would suggest to do that. I unfortunately used my IBM ID and had to follow the explanation text and links to the right of the user and password fields to link both up. There seem to be still problems with this, because I happened to end up on a staging version of BlueMix that did not work for me.

Note: After logging into BlueMix, make sure your URL is https://ace.ng.bluemix.net.

Creating a Sample Project on BlueMix

To get started, I created a sample project on BlueMix.  I went into my dashboard and clicked the tile Create An App. I picked the Runtime SDK for Node.js, provided a unique host name for example rsjazz01 and accepted all the default settings.

Note: The host name needs to be unique which basically means, anyone following this will have to pick a different name and replace it in the images and text below.

The project gets opened, but won’t run, since there is nothing in there yet. In the top section to the left, underneath the application icon and name is a link named View Guide. This link provides more information about how to get started. The following is what it shows if you chose a project name RsJazzTest03. The project name will be reflected in the downloaded sample files at some places.

BlueMix Sample

Install The CloudFoundry Commandline

BlueMix uses CloudFoundry to upload and deploy applications. Follow the link and desription in the guide to download and install the CloudFoundry command-line.

Also download the example code for the application. Store the compressed code somewhere and extract the file into a Folder, for example c:\temp. Assuming the application name is rsjazz01 there would be a folder C:\temp\rsjazz01 that contains the source code of the project.

You can follow the instructions to push the example to BlueMix and run it. However, lets get it into Eclipse so that we can look at it in a more convenient way.

Create an Eclipse Project

Create an Eclipse Node.js project. It can have any name as far as I can tell, but in the context of Eclipse choose the name of the application as the project name, e.g. rsjazz01.

From the folder C:\temp\rsjazz01 that contains the uncompressed example, select all files and folders. Copy the files and folders using CTRL+c and paste them into your Eclipse project. You can do this in the Eclipse project explorer or in the filesystem. If you did it in the Filesystem, refresh the Eclipse project to see the files. The Project content should look like this:

Examlple ProjectThe main application file is represented by the file app.js. The folders public and views and their contained files are used by the framework used to create web pages.

Run the Application on the Local Development Environment

Before trying to run the application in the cloud, let’s try to run it on the development environment. In order to do so lets examine the application first. The file app.js looks as follows:

Example AppThe application prepares itself first, then gets some data, such as the host name and the port it is using from the environment, or used some defaults if not. Then it starts to listen as a server on that port and host.

The description of the sample mentions some other pieces it is using. Lets look what it is.

The files

  • manifest.yml
  • package.json

marked in the project screen shot above, are used by BlueMix to deploy and run the application. Any application that runs on BlueMix needs this kind of information to be able to deploy and run.

Lets look at the manifest.yml file first. This is the content for our sample.

ManifestThis describes some of the properties of the application, such as the host, the application name, the command to start it as Node.js application, domain, number of instances and required memory and disk. When creating an application from scratch, this is important information to look at.

The package.json file looks like this:

PackageThis file describes the application and, more importantly it describes the packages that the application requires to be able to run. It needs the Express web application framework, version 3.4.7 and the Jade Template Engine, version 1.1.4 to run on a node engine.

Install Express and Jade 

To install these packages, on your local machine, in order to be able to run the application, open a shell and use the package manager. Type each line below and hit enter. The versions needed are from the dependencies. Note, the newest version of express won’t work. There have been changes to it that will break the application.

npm install express@3.4.7
npm install jade@1.1.4

Wait for Node.js to download and install the packages.

Now right click on app.js and select to run it as a Node application. Open http://localhost:3000/ and see the web page displayed.

It is now possible to develop the application further on the local development environment. It is possible to use RTC to put it under version control, to share it and to plan the work. Any other source control providers that Eclipse supports can be used as well.

Deploy the application on BlueMix

Lets try to deploy the application on BlueMix. How this works is described in the guide above. Open a shell. The first three commands can be run anywhere.

First set the API URL for Cloud Foundry:

cf api https://api.ng.bluemix.net

Log into the server (use your own ID):

cf login -u 

This prompts for a password. Provide your password and finish the login.

Set the target space for the application. By default the space is called dev.

cf target -o  -s dev

Now change the directory to the folder that represents the project on disk, named rsjazz01 in this example. this folder is directly in the workspace folder you chose to use with Eclipse when you started it.

Now push the application to the BlueMix server:

cf push rsjazz01

The data gets uploaded, deployed and started. In the BlueMix Dashboard on the application tile you should be able to see that there are activities happening in BlueMix, while they show up in the shell. Once the process finishes the application is deployed and you can open the URL and see the same result you had from the local run.

Create a Simple Custom Sample Application

Running a sample application that is supposed to be running is – relatively – easy. But what about running a custom application? What is needed to do that?

Create a new Node.Js project and give it a name. In the example we will use rsjazz02. Pick a name that suits you if you want to perform this as well.

The new project is empty. Create a new JavaScript file and call it app.js. The file should have the following content:

/*jshint node:true*/

/**
 * New node file
 */
var http = require("http");

function onRequest(request, response){
	response.writeHead(200, {"Content-Type": "text/plain"});
	response.write("Hello World - this is rsjazz's first BlueMmix application!");
	response.end();
}

//There are many useful environment variables available in process.env.
//VCAP_APPLICATION contains useful information about a deployed application.
var appInfo = JSON.parse(process.env.VCAP_APPLICATION || "{}");
//TODO: Get application information and use it in your app.

//VCAP_SERVICES contains all the credentials of services bound to
//this application. For details of its content, please refer to
//the document or sample of each service.
var services = JSON.parse(process.env.VCAP_SERVICES || "{}");
//TODO: Get service credentials and communicate with bluemix services.

//The IP address of the Cloud Foundry DEA (Droplet Execution Agent) that hosts this application:
var host = (process.env.VCAP_APP_HOST || 'localhost');
//The port on the DEA for communication with the application:
var port = (process.env.VCAP_APP_PORT || 3000);
console.log('Start my server on port ' + port);
//Start server
http.createServer(onRequest).listen(port,host);

console.log('App started on port ' + port);

This application basically waits for an HTTP request on a port on a host and responds with a simple text. It reuses the parsing of the environment variable we saw in the sample application to get the port and the host name.

Run the application on the local Node.js and connect to it using http://localhost:3000/. It should run and provide the expected output in the browser window.

It does not have any dependencies to any other packages. However, it would not yet run on BlueMix. It lacks the information required to deploy end run it there.

Copy the manifest.yml and the package.json files from the sample application over. You can also copy the readme files, but these are not required.

Open the manifest.yml file and edit it to use a new host name. To make sure the host name is unique you can create an empty project on BlueMix, but you don’t have to. BlueMix will tell you if the host name is already taken. In the code below I use rsjazz02 as name of the application and as host name.

applications:
- disk_quota: 1024M
  host: rsjazz02
  name: rsjazz02
  command: node app.js
  path: .
  domain: mybluemix.net
  instances: 1
  memory: 128M

The line

  command: node app.js

can stay as it is. If you chose to use a different name for the main JavaScript file, you would put the name in here.

Open the package.json file and edit it to match the new situation. You can change the name and the description. Remove the dependencies, as there are no dependencies to other packages needed. Keep the rest as it is.

{
	"name": "RSJazzSampleApp",
	"version": "0.0.1",
	"description": "A sample nodejs app for Bluemix - by rsjazz",
	"dependencies": {},
	"engines": {
		"node": "0.10.26"
	},
	"repository": {}
}

Save all the changes to these files.

The application is now ready to deploy on BlueMix. Change the directory of your shell to the new folder e.g. using cd ../rsjazz02.

Now push the application to the BlueMix server using the shell command:

cf push rsjazz02

The data gets uploaded, the application deployed and you can test it using http://rsjazz02.mybluemix.net/ once it is running and the health shows green (replace the name of the application in the URL with your application). The result should be the same as in the local run.

User RTC and IBM Dev Ops Services

You can use IBM Dev Ops Services to develop and deploy BlueMix Applications with RTC. You would basically create a DevOps Services project to manage your source code and use it to deploy your application. I will try to blog about this later.

You would still do all the above steps to set up your local development environment.

Enable Eclipse To Deploy Directly to BlueMix

So far a local shell and the cf command is used to push the application up to BlueMix. As mentioned above you could also use IBM Dev Ops Services to do this.

There is a third option available. You can configure your Eclipse client to connect to BlueMix and to deploy the application automatically if you did changes, if you desire.

You can install the IBM Eclipse Tools for Bluemix into your local Eclipse Client.

Once you have done that, you can open the Eclipse View Servers and add a new server to it.

The server view would look like below. The overview shows the configured BlueMix connection. The Applications and Services shows the applications and services you have configured. The server view shows the applications on the server as well as the locally connected ones.

BlueMix Eclipse ToolsTo be able to deploy you Node.js application, you have to change it a bit first. You have to convert it to a Faceted form, using Configure in the context menu of the project.

Configure Faceted FormIn the following dialog you have to select the application type, in this case Node.js Application. Once you have done it, you can see it in the Add and Remove dialog for the server.

Configure ServerYou can add applications and remove them. If configured to do so, any save will trigger a deployment.

Summary

This post shows how you can use RTC and Eclipse to start developing Node.js applications for BlueMix. It shows how to configure the environment and the first basic steps in a way to support getting over the first questions. After reading this you should be able to do some basic experiments in half a day or so.

As always I hope this helps someone out there to save some time and I appreciate feedback.