Skip navigation

At JBoss Tools we created a java client that allows you to talk to the OpenShift PaaS: openshift-java-client. The library is already used in the OpenShift tooling in JBoss Tools, the Forge plugin and Appcelerators tooling for OpenShift.

This blog post will show you how to use okthis API in your very own java programs. We'll develop a command line tool that displays informations equivalent to what you get when running rhc domain show with the OpenShift command line tools: It displays basic informations about your user.


User Info
Namespace: andre

Application Info
    Framework: jbossas-7
     Creation: 2012-08-10T11:24:13-04:00
         UUID: 8ad0d94f39aa4295a0049de8b8b5ef55
      Git URL: ssh://<SOMEID>
   Public URL:

      jenkins-client-1.4 - Job URL:


You'll find the sourcecode for this example at github: All the code that is shown in this blog is contained within the Main class.


If you want to dig futher, you'll get a more complete example that includes jenkins in this wiki article.

Openshift-java-client 2.0

The openshift-java-client is a java library that allows java programs to talk to the OpenShift PaaS. It talks to the new OpenShift RESTful service and allows users to create, modify and destroy OpenShift resources: domains, applications, cartridges, etc.It is hosted on github at and is available under the Ecilpse Public License.



Openshift-java-client 1.x was talking to the legacy service in OpenShift. 2.0 switched to the new RESTful service.

The legacy service is not maintained any more and will fade away at some point. Users of the 1.x client should migrate to the 2.0 client.

The migration should be pretty much without hassles. Even though 2.0 is a complete rewrite, the API stayed pretty much the same/very close.


  • You need an account on OpenShift. (If you have no account yet, you'd have to signup first)
  • Make sure you have an OpenShift domain and some applications (to get some meaningful output)

Launch Parameters

To keep the implemenation simple, the program we're about to write, only accept 2 parameters on the command line:

  1. username
  2. password


Launching the program with maven would look like this:

mvn test -Dusername=<username> -Dpassword=<password>

Project Setup

We have to make sure that we have the openshift-java-client available on our classpath. The client library is available at You could clone the repo and build your own jar by telling maven to "mvn clean package". But even simpler is to add it as dependency to your pom, since the client library is available from central as maven artifact:



Connect to OpenShift

After we did some basic command line parameter parsing (that we skipped here on puropose) we'd have to get in touch with the OpenShift PaaS. Using the openshift-java-client you'd tell the OpenShiftConnectionFactory to create a connection for you. To create this connection you'll have to provide some parameters:

Server url

First of all you need to give it the url of the OpenShift PaaS. You may either hard code it or ask the OpenShift configuration for it:

new OpenShiftConfiguration().getLibraServer()

The OpenShiftConfiguration class parses the OpenShift configuration files you may have on your machine (~/.openshift/express.conf, C:/Documents and Settings/user/.openshift/express.conf etc.). Those usually get created once you installed the rhc command line tools. In case you dont have any configuration yet, OpenShiftConfiguration holds some meaningful defaults and points to On the other hand, our configuration class also allows you to override settings by putting them to the system configuration as you would do if you want to switch to the OpenShift liveCD temporarly. You would then simply add the following to the command line when launching the java virtual machine:


Client id

The connection factory also requires you to provide your very own client id. This client id is used when the openshift-java-client talks to the OpenShift REST service. It'll get included in the user-agent string that tells OpenShift what client it is talking to. We use the name of our example, "show-domain-info".

Username and Password

Last but not least, you also have to give it your OpenShift credentials, the ones we got from the command-line.


String openshiftServer = new OpenShiftConfiguration().getLibraServer();
IOpenShiftConnection connection = new OpenShiftConnectionFactory().getConnection("show-domain-info", "myuser", "mypassword", openshiftServer);


Once you have your connection you can get a IUser instance which will allow you to create your domain and applications:

IUser user = connection.getUser();


Print the User Infos

The first information block involves basic user informations. The username is available from your IUser instance:

System.out.println("RHLogin:\t" + user.getRhlogin());


The other value that we want to display, the domain namespace, is accessible from your OpenShift IDomain. We'll get it from the the user instance and print its id (namespace).

IDomain domain = user.getDefaultDomain();
System.out.println("Namespace:\t" + domain.getId());

Print the Application Infos

The second portion printed by "rhc domain show" is reporting your users applications. All OpenShift applications are held in a list within your domain. We simply get the list and iterate over it's entries:

for (IApplication application : domain.getApplications()) {


The required values - name, framework, creation time etc. - are now available within each IApplication instance:

System.out.println("\tFramework:\t" + application.getCartridge().getName());
System.out.println("\tCreation:\t" + application.getCreationTime());
System.out.println("\tUUID:\t\t" + application.getUUID());
System.out.println("\tGit URL:\t" + application.getGitUrl());
System.out.println("\tPublic URL:\t" + application.getApplicationUrl() + "\n");


An application may have several cartridges embedded (MySql, Postgres, Jenkins etc.). These cartridges are reported by by the application. We get the list of cartridges and inspect at each of them:

for(IEmbeddedCartridge cartridge : application.getEmbeddedCartridges()) {


We then want to know bout a cartridge's (IEmbeddedCartridge), name and url:

System.out.println("\t" + cartridge.getName() + " - URL:" + cartridge.getUrl());


That is it - you now have an app that can talk to OpenShift via its REST API. If you want to do more we also have this article that shows how to perform actual operations against your OpenShift applications. Hope you enjoy it and let us know what you build with it!

We released back in July a new version of JBoss Tools 3.3.1 and JBoss Developer Studio 5.0.1 which fixes the problem of installing on Eclipse 3.7.0 (Indigo) and makes it possible, but not recommended to install on Eclipse 4.x (Juno).

The SOA Tools are also now available from JBoss Central and we got news from the Fedora Java spin which includes parts of JBoss Tools. More below...


SOA Tools

The SOA Tools (jbpm, drools, modeshape, teiid, etc.) are available from JBoss Central in both JBoss Tools 3.3+ and Developer Studio 5+.



To get them open JBoss Central and go to the Software/Update tab and they should be listed, ready to be installed.


The plugins have been updated to work with the latest release of JBoss SOA Platform and its components.


Eclipse 3.7.0 - you still use that ?

JBoss Tools 3.3.0 came out requiring Eclipse 3.7.1 because there was some rather nasty bugs we wanted to avoid to expose to users and we naively belived most would be on 3.7.1+ by now - but oh boy we were wrong.


It turns out that when we released the final version of JBoss Tools 3.3.0 our success install rate went up significantly (Yay!) but we also saw a skyrocketing level of errored installs (Not good). Looking at those error logs showed us that majority of Eclipse 3.7 (Indigo) users are still on the very first version, i.e. 3.7.0.


In a perfect world Eclipse P2 update mechanisim would let you update to Eclipse 3.7.1+ at the same time as installing plugins that requires/suggest to use a bugfixed version, but unfortunately Eclipse mechanism does not allow for this.


Therefore in this update we allowed JBoss Tools to depend on Eclipse 3.7.0 to make it installable, but Eclipse 3.7.0 users will now get a warning dialog on startup suggesting they should update their Eclipse to have a better experience.


How about Eclipse 4.x/Juno ?

JBoss Tools 3.3.x and Developer Studio is tested and supported on Eclipse 3.7/Indigo - but what if I want to use Juno ?


There are two options:


A) You can *try* use JBoss Tools 3.3.x on Juno - but we do not recommend this.

B) You can use the JBoss Tools 3.4.x nightly builds updatesite - this have been updated/adjusted to work with Juno and is the basis for the next major update of tools and Developer Studio.


In both cases your mileage will vary, but if you are up for it please do try out the nightly builds and report any issues found while using Juno with JBoss Tools.


Fedora Java Spin

Gerard Ryan have been doing his Google Summer of Code project about creating a Fedora Spin that would be good for Java developers. In that progress he took on the task on trying to package JBoss Tools, or at least parts of it so it could be installed "the Fedora way".


He actually succeded in making this happen and you can see his final report about this at his GSOC blog.


You can try out the full Fedora Java spin by downloading the ISO images from Gerard or if you are already running Fedora 17 or newer, you can try it out by running:


yum install eclipse-jbosstools


This will actually be installed into Fedora's version of Eclipse Juno, so that is third way to try Juno out with parts of JBoss Tools.


Hope you like that and if you find issues report it in our jra, but please mention if you are using the Fedora package since there are some slight differences.


Have fun,



Filter Blog

By date:
By tag: