Revisiting use of the Java API for IBM SmartCloud Enterprise

Share this post:

By Andrew Low


If your google-fu is strong, you’ll likely have found the previously posted “Introduction to the Java API” article. In my case, I started with an earlier article that gave a brief overview of the Java API and later found the introduction article. With much credit to Dominique Vernier and his previous postings, I revisit the use of the Java API for IBM SmartCloud Enterprise and attempt to provide additional insights for people looking to get started. The ability to automate your use of cloud resources is the key to realizing the full benefits of cloud computing; failing to do so simply shifts work from physical machines to virtual ones.

It is worth mentioning that I did also look into using the command line APIs on both Windows and Linux. This approach still makes use of Java under the covers but provides shell-friendly commands. Of course there is also the base RESTful API if you want to create-your-own solution in another scripting language such as Perl.

Of course you’ll need an IBM SmartCloud Enterprise account to try out any of this. [Note: if you’re interested in information on navigating cloud implementation successfully, there’s a webcast coming up this Monday, July 23, that may interest you: It’s being led by IBM execs and industry expert Mike Vizard.] I like to use Eclipse as my development environment, but you can use any method or tools you want to develop your Java code. You’ll need the Java REST API Client, and having the Javadoc for REST API is handy – after you log in, you can find these two items by clicking the Support tab and then looking in the Documentation library.

The Java REST API Client download contains a .zip file copy of the Javadoc, and it also has example code ( that is worth looking through. To get setup to do some development, you’ll need the following five .jar files:


  • commons-codec-1.3.jar
  • commons-httpclient-3.1.jar
  • commons-lang-2.3.jar
  • commons-logging-1.1.1.jar
  • DeveloperCloud_API_Client_2.0.jar

The first four are from the Apache Commons project, you’ll notice they are somewhat outdated, which might cause a bit of “head-scratching” for someone using more current Apache tutorials or documentation. This issue isn’t huge because we care most about the API in the DeveloperCloud_API_Client_2.0.jar file, which of course works fine with the provided Apache Commons components.

For this example, we’ll launch an instance of an image from the catalog of public images. We’ll wait for it to become active and provide output regarding the states it passes through while we wait.

1. First we start the session.

DeveloperCloudClient client = DeveloperCloud.getClient();
client.setRemoteCredentials("", "Pa55w0rd");

For simplicity we’re embedding the password into the source, I wouldn’t recommend that for production code both for security reasons as well as maintenance.

2. Next, we create a public/private key pair. Although creating one through the web UI is an option, it is possible to do it with Java. What we’ll do is check to see if the key we’re going to create exists and if it doesn’t, we’ll create one.

String keyName = "MyNewKey";
try {
	client.describeKey(keyName );
} catch ( UnknownKeyException e ) {
	client.generateKeyPair(keyName );

3. Now we can launch a new instance.

List<Instance> instances = client.createInstance(
	"Instance launched via Java API", // Name of instance
	"41”, // Data Center ID
	“20025200”, // Image ID
	“COP32.1/2048/60”, // Image type
	null); // Configuration

That’s it, the new instance launch request is done, we just need to wait for it to be ready to use. Before we do that, let’s talk a bit about the magic values in the code for Data Center ID, Image ID, and Image type.

The Data Center ID can be determined using another API call:

List<Location> locations = client.describeLocations();
for (int i = 0; i < locations.size(); i++) {
		+ " id=" + locations.get(i).getId());

Similarly the Image ID and Image type can be retrieved using others:

List<Image> images = client.describeImages();
for (int i = 0; i < images.size(); i++) {
	Image image = images.get(i);
	System.out.println(image.getName() + " id="
		+ image.getID());
	List<InstanceType> types = image.getSupportedInstanceTypes();
	for( int j =0; j<types.size(); j++) {
		System.out.println("\t "
			+ types.get(j).getDetail()
			+ " type=" + types.get(j).getId());

We need to perform this set of queries only when developing the code; this helps reduce the complexity of the runtime code and the time to run because there are many public images and enumerating them is slow.

You might have noticed that all of the parameters used are string values. The reason is because the Java REST API is built on top of the RESTful API and it uses strings. Also worth noting is that all of the TCP/IP traffic is done through an SSL connection, so our communications with the IBM SmartCloud are secure.

Our last trick is to write a polling loop that looks in on the status of the instance we launched, waiting until it becomes active.

String instanceID = instances.get(0).getID();
Instance myInstance = client.describeInstance( instanceID );
while(Instance.Status.ACTIVE != myInstance.getStatus())
	System.out.println( myInstance.getStatus() );
	Thread.sleep(1000*10); // sleep 10 seconds
	// refetch the instance state
	myInstance = client.describeInstance( instanceID );

There is an assumption that the instance we just launched is the only (and first) one in the list of instances. The instanceID is a unique identifier for the newly launched instance. We pass the instanceID to the describeInstance() method to grab the current state of the instance. Notice that we need to repeat this as time passes in order to know the current state (it’s a copy of the state, not a live handle).

Because this example doesn’t delete the instance, you’ll need to log in to the web UI and delete it manually. I found a helpful approach was to be logged in on the web UI while running the code so I could see what was happening on that side.

There are a few details I’ve skimmed over in this article. I haven’t bothered to show the exception-catching required for unexpected conditions, nor have I done any error-checking or validation. A complete functional example is provided: LaunchExample.


More stories

Why we added new map tools to Netcool

I had the opportunity to visit a number of telecommunications clients using IBM Netcool over the last year. We frequently discussed the benefits of have a geographically mapped view of topology. Not just because it was nice “eye candy” in the Network Operations Center (NOC), but because it gives an important geographically-based view of network […]

Continue reading

How to streamline continuous delivery through better auditing

IT managers, does this sound familiar? Just when everything is running smoothly, you encounter the release management process in place for upgrading business applications in the production environment. You get an error notification in one of the workflows running the release management process. It can be especially frustrating when the error is coming from the […]

Continue reading

Want to see the latest from WebSphere Liberty? Join our webcast

We just released the latest release of WebSphere Liberty, It includes many new enhancements to its security, database management and overall performance. Interested in what’s new? Join our webcast on January 11, 2017. Why? Read on. I used to take time to reflect on the year behind me as the calendar year closed out, […]

Continue reading