Introduction to the Java API of IBM SmartCloud Enterprise

In a previous blog, “What are the IBM SmartCloud Enterprise APIs?” I explained the types of APIs provided by the IBM SmartCloud Enterprise. Now, I explain in more detail the Java API that is provided by the IBM SmartCloud Enterprise platform. The Java APIs are downloadable from the Support tab of the IBM SmartCloud Enterprise portal. This blog also contains a video that demonstrates the IBM SmartCloud Enterprise Java API.

Java API description

The Java APIs are very simple; they are based on an interface DeveloperCloudClient, which holds a number of methods to manage the IBM SmartCloud Enterprise platform and a number of plain old Java objects (POJO), which represent each type of resource and object managed by the IBM SmartCloud Enterprise.

The Java API uses the RESTful API behind the scene. It is faster than the CLI API because there is no need to launch a new Java Virtual Machine for each method.

To access the IBM SmartCloud Enterprise, you have to create a client object, which is easy to do as follows:

DeveloperCloudClient client = DeveloperCloud.getClient();

client.setRemoteCredentials(“myuser”,”mypassword”);

That’s it. Now you are ready to call methods and take several actions on the IBM SmartCloud Enterprise, such as:

client.createInstance(…..);

Considerations for automation

The same remark as in my previous blog about CLI API can be done on the Java API. Some Java APIs are asynchronous. For example, if you call a method to create a new instance createInstance, the method returns a list of instance objects directly after the request has been posted to the IBM SmartCloud Enterprise platform and not after the instance has been completely created. You have to take this into account while writing your program and thus monitor the completion of the request before launching the next method, of course, if this method needs the resource created by the first one

To support you on this, I created a number of handy methods that can be useful while you are writing your own program. One of these methods is waitInstancesStatus, which waits until a given list of instances reaches a given status.

You may download these packages from:
https://www.ibm.com/cloud/enterprise/ram/assetDetail/generalDetails.faces?guid={4F0A71BF-74B7-C9A4-AD24-430331F9AC99}

The asset contains the java documentation.

You have two options to use these methods:

• Create a HandyDeveloperCloudClient instead of a DeveloperCloudClient object and use that object to call the method provided by the IBM SmartCloud Enterprise and the additional methods provided by the handy command-lines and Java Libraries.
• The handy command-lines and Java library contains managers such as InstanceManager and ImageManager. You can instantiate these manager and provide them a DeveloperCloudClient object to generate the connection and then use the method provided by each manager.

Read the developerWorks article that explains this asset:

http://www.ibm.com/developerworks/cloud/library/cl-clouddeployutility

Manage Instance Parameters with the Java API:

The createInstance method requires a Map<String,Object> object in which you will set all parameters defined in the parameters.xml image . Unfortunately, the IBM SmartCloud Enterprise Java API doesn’t provide an API to manage the image parameters. However, it is very easy to create a Java package to manipulate the parameters.xml file and read all available parameters to create our Map object, because we have the parameters.xsd, and using JAXB to create the Java package is straight forward. To find out how to create such a package, follow the developerWorks article: http://www.ibm.com/developerworks/cloud/library/cl-parameterizejaxb

You can download the parameters.xsd as follows:

1. On the Support page, click View asset catalog.
   
2. Clear the filter and enter parameters.xsdin the search field:
   
3. Open the asset and click Content and you will see:
   

Using Java API through proxy

You can access the command-line tool through a proxy by changing the environment.properties in the DeveloperCloud_API_Client_JAR.jar file:

# Proxy setting for API request through a proxy server. Set proxy.enabled as true to enable proxy setting

proxy.enabled=false

# Host name or IP address for proxy sever.

proxy.host=

# Port for proxy sever.

proxy.port=

# Optional, Username of Proxy Server

proxy.userName=

# Optional, Password of Proxy Server

proxy.password=

Download the Java API

To download the Java API, you must first have access to the IBM SmartCloud Enterprise. (If you don’t have access, go to http://www.ibm.com/cloud-computing or contact your local IBM representative.)

1. Log in on www.ibm.com/cloud/enterprise.
2. Select the Support tab and click Java REST API Client.
   
3. You land on the correct asset in the Rational Asset Catalog; select Content.
   
4. A list of JAR files is displayed that you have to download and put in your CLASSPATH. You may also download the Javadoc information.
   

Example of an Application that deeply use the Java API

You can download the deployment utility from the following location. You may use the deployment utility to deploy a complex infrastructure on the IBM SmartCloud Enterprise. This tool deeply uses the Java API provided by the IBM SmartCloud Enterprise. The asset contains also videos.

https://www.ibm.com/cloud/enterprise/ram/myAssets/_rlvid.jsp.faces?_rap=pc_Summary.getAssetDetailsActionString&_rvip=/myAssets/summary.jsp&guid={D4137D9A-3225-BBB7-8689-834235443353}

With this URL, after logging in, you will land on IBM SmartCloud Enterprise.

Click Content to download and view the documentation, video, tool.

For more information about the IBM SmartCloud Enterprise and other IBM cloud solutions, visit http://www.ibm.com/cloud-computing.

Share