UrbanCode Deploy

10 Minute Tips: Leveraging the UCD REST Client Libraries Part 2


Last time we looked at how we can easily discover and utilise the UCD REST client libraries to write your own scripts without having to write all the code for an http exchange.  But as we said, these libraries don’t provide 100% coverage of all the available API’s.

Wouldn’t it be nice if we could still leverage all the code that does the heavy lifting and just add the API’s we want to use?

In this article we’ll do exactly that.

The UCDRestClient libraries are all built as extensions to an underlying base class that does all the heavy lifting.  So we can create our own equivalent to the REST clients and build into that any API’s that we want to make use of where the built-in clients don’t provide access to the API’s we want or perhaps where they only return a subset of the information available through a given API.

Extending this UCDRestClient class is very straight forward and you could build up this class overtime adding new features to it as you find the need and reuse it in more projects later.

When we extend this class, we need to define at least one constructor which just calls the corresponding constructor in the super class.  This is what will give us access to the code that does the heavy lifting for talking to UCD.  We then only need to add new methods to this class for the API’s we want to make use of.  We call upon methods from the super class to do the hard work.

So this is the code we would write to create a new client which I’ve called extensionsClient but you could call it whatever you like

import java.io.IOException;
import com.urbancode.ud.client.UDRestClient;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.impl.client.DefaultHttpClient;

import org.codehaus.jettison.json.JSONObject;
import org.codehaus.jettison.json.JSONException;
import java.net.URI;

public class extensionsClient extends UDRestClient
    public extensionsClient(final URI url, final String clientUser, final String clientPassword) {
        super(url, clientUser, clientPassword);

    public extensionsClient(final URI url, final String clientUser, final String clientPassword, final boolean trustAllCerts)

        super(url, clientUser, clientPassword, trustAllCerts);
    public extensionsClient(final URI url, final DefaultHttpClient client) {
        super(url, client);

// Extension methods go here

The three constructors give you 3 ways to create an instance of the UCDRestClient:

  1. The first one just takes the URL of your UCD server, user ID and password
  2. The second adds the ability to say whether or not the client should trust UCD certificates implicitly.  This can be useful when your UCD server is configured with a self-signed certificate.
  3. The third one allows us to reuse an existing http connection client that we might have for the server.

To use this class in our code we would just instantiate it rather like we did in part 1 of this article:

String url=https://localhost:8443
String userName = "admin"
String password = "admin"
myClient = new extensionsClient( new URI(url), userName , password, true);

Here we create some variables to hold the URL, username, and password and then we create an instance of the extensionsClient class called, in this case, myClient.

So now to make this useful, I need to add some methods to my extensionsClient class to call the API’s I want.

We’ll start with a simple API that takes no parameters.

public JSONObject getSystemConfiguration() throws JSONException, IOException {
        final String uri = this.url.toString() +  "/cli/systemConfiguration";
        final HttpGet method = new HttpGet(uri);
        final CloseableHttpResponse response = this.invokeMethod(method);
        JSONObject result;
        try {
            result = new JSONObject(this.getBody(response));
        finally {
        return result;

We’d put this into the class definition in the first example where is says Extension Methods go here.

This new method will allow us to get the UCD server system configuration.  This is available in the SystemClient class, but it’s a nice simple example.

First, we create the uri which consists of the url we gave to the extensionsClient constructor and then appended with the path to the api, in this case, “/cli/systemConfiguration”;

Next we create the method object for the action we need to perform in this case its an HttpGet request.

The third line actually invokes the API and we get back a response object that is then processed to extract the data returned by the server.  We can perhaps just return a few selected items of the full result or the full object as we wish.

We can now call this new method by adding the following code after the instantiation of our extensionsClient class

JSONObject sysConfig = myClient.getSystemConfiguration()
println sysConfig

Running this would give us a print of the JSON response from the server.

Now if we will look at a slightly more complex example where we need to provide data to the server to say what specific information we want.  So in this case we’ll ask for the property of an agent.

public String getAgentProperty(final String agentName, final String name) throws IOException
        String result = null;
        final String uri = this.url.toString() + "/cli/agentCLI/getProperty?agent=" + this.encodePath(agentName) + "&name=" + this.encodePath(name);
        final HttpGet method = new HttpGet(uri);
        final CloseableHttpResponse response = this.invokeMethod(method);
        result = this.getBody(response);
        return result;

This is very similar to the first example except in this case we have to provide two values to the API; the name of the agent and the name of the property we want the value of.  Notice that we call the method encodePath on each of the parameter values.  This is part of the superclass and makes sure that any special characters in the values are encoded properly to that they will form a valid URI.  Otherwise it’s very similar.  In this case, we just return the value as a simple string.

We can invoke this method in a similar way

String agentProp = myClient.getAgentProperty("agent-orange","JAVA_HOME")
        println "Agent property: ${agentProp}"

When we run our complete script we will see something like this

"historyCleanupMinute":0,"historyCleanupDaysToKeep":120, ….. }

Agent property: /opt/ibm-java-x86_64-80/jre

These are fairly simple examples but should be enough to give you the idea of how you can extend the UCDRestClient libraries to add your own functionality.

Alan Murphy is a services consultant with IBM who has worked with clients to help them adopt new tools and processes for the last 20 years. UrbanCode Deploy and DevOps has been his focus for the last 5 years. He also develops tools to assist clients in tool adoption and blogs on an occasional basis.