The IBM® Cloud parameters are passed from an image to an instance using an XML file called parameters.xml. That file is located in the RAM content for the image and then copied under the directory /etc/cloud (for Linux®) in your instance with the actual parameters.

Define custom parameters to create your instance in the parameters.xml. For example, you can have a custom image that sets up Virtual Network Computing (VNC) at the instance creation time. The image requests the parameters: user id, password, and VNC password (see Figure 1).

Now if, for example, you want to create a Java™ program that extracts the parameters from your XML file either from the image or instance, you need to read this parameter file from your Java program. For example, if you want to create your own portal that provides the ability to request instances from images. You need to know which parameters are requested by the image to dynamically build your screen request. And, you need to get that information dynamically, not as a static result; by doing that, you avoid creating specific screens from each type of image and then posting the values in the parameters file again.

You can retrieve parameters.xml using the IBM Cloud Java API and the Image.getManifest() method. This article provides a set of APIs that delivers all necessary methods to access parameters.xml. Multiple methods exist to parse XML files, but in this article, the example uses JAXB that lets you marshal and unmarshal XML files.

But first, some concepts

JAXB can create a Java package based on an XSD file. Find the parameters.xsd file in the "Creating and customizing images" document (see Resources).

From this XSD file, use the tool xjc provided by Java to generate the Java package that will contain the classes that represent the parameters model plus a factory class. These generated classes are used to access parameters.xml.

That's all the concept you need. Let's create the Java package.

Back to top

Create the Java package

As mentioned, use the xjc tool provided by Java, but first you need the parameters.xsd file. For the time being, the best way to create the parameters.xsd file is to copy and paste it from the "Creating and customizing images" document available from the IBM Cloud support tab (see Resources).

Once you have the parameters.xsd file, just enter the following command to generate your package:

xjc -p <packageName> parameters.xsd

A package is created in your current directory similar to the following:

C:\Documents and Settings\Dominique\workspaceCloud\com.ibm.cloud.parameters\src>xjc 
   -p com.ibm.cloud.parameters ../resource/parameters.xsd
parsing a schema...
compiling a schema...
com\ibm\cloud\parameters\DataType.java
com\ibm\cloud\parameters\Field.java
com\ibm\cloud\parameters\ObjectFactory.java
com\ibm\cloud\parameters\OptionType.java
com\ibm\cloud\parameters\Options.java
com\ibm\cloud\parameters\Parameters.java
com\ibm\cloud\parameters\Values.java

Import this package in your Java project (Figure 2):

In this package, you can see Plain Old Java Objects (POJOs) representing each object defined in the XSD file and a factory class.

Back to top

Testing the parameters package

Run a small program to test your Java parameters package:

String cloudPasswordFile = args[0];
cloudUserId = args[1];
String cloudPassPhrase = args[2];

// Retrieve cloud access information.
cloudPassword = PasswordFileProcessor.getRealPassword(
        cloudPassPhrase, cloudPasswordFile, cloudUserId);
Properties props = new Properties();
props.load(new FileInputStream("cloud.properties"));
address = props.getProperty("address",
        "https://www-147.ibm.com/cloud/enterprise/");

// Set Credential and address.
client.setRemoteCredentials(cloudUserId, cloudPassword);
client.setEndpointAddress(address);

//Search for an image description
Image image = client.describeImage("20004761");

Security.setProperty("ssl.SocketFactory.provider", 
  "com.ibm.jsse2.SSLSocketFactoryImpl");
Security.setProperty("ssl.ServerSocketFactory.provider", 
  "com.ibm.jsse2.SSLServerSocketFactoryImpl");

//Create an http client
HttpClient httpclient = new HttpClient();
Credentials defaultcreds = 
   new UsernamePasswordCredentials(cloudUserId, cloudPassword);
httpclient.getState().setCredentials(AuthScope.ANY, defaultcreds);

//Create the method, it is important to use the escape 
//because the url contains '{' and '}'.
GetMethod httpget = new GetMethod(new HttpsURL(image.getManifest()).getEscapedURI());

//Execute the request
httpclient.executeMethod(httpget);

//Get the result
String result = httpget.getResponseBodyAsString();

//Prepare JAXB
JAXBContext jc;
jc = JAXBContext.newInstance("com.ibm.cloud.parameters");
Unmarshaller u = jc.createUnmarshaller();

//Unmarshal the result
Parameters parameters = (Parameters) u.unmarshal(new StringReader(result));

//Display the parameters
for (Field field : parameters.getField()) {
     System.out.println("Field Name=" + field.getName());
}

In the example, we used a customized image with imageID=20004761. You can find the image ID by browsing the Asset Catalog. (Control Panel > View Asset Catalog. Select an image either from My Dashboard or from Assets and the ID is specified in the image ID field.)

This parameters.xml file looks like:

<parameters xsi:noNamespaceSchemaLocation=
  "platform:/resource/com.ibm.ccl.devcloud.client/schema/parameters.xsd">
  <field name="userID" label="User ID" type="string"/>
  <field name="userPassword" label="User Password" type="password" 
               pattern="^\w*(?=\w*\d)(?=\w*[a-z])(?=\w*[A-Z])\w*$" 
               patternErrorMessage="Invalid Password. Must contain at least 1 number, 
               at least 1 lower case letter, and at least 1 upper case letter.">
  </field>
  <field name="vncPassword" label="VNC Password" type="password" 
               pattern="^\w*(?=\w*\d)(?=\w*[a-z])(?=\w*[A-Z])\w*$" 
               patternErrorMessage="Invalid Password. Must contain at least 1 number, 
               at least 1 lower case letter, and at least 1 upper case letter.">
  </field>
</parameters>

And the results are:

Field Name=userID
Field Name=userPassword
Field Name=vncPassword

Back to top

In conclusion

There are multiple techniques to convert XML into Java models using such technologies as XMLBeans and XStreams, but JAXB is one of the simplest. Hopefully this article has inspired you to enjoy using the Java IBM Cloud API to fulfill your requirements around the IBM Cloud and perhaps develop your own "create instance" method.

Resources

Learn

• For more on how to perform tasks in the IBM Cloud, visit these resources:
  • Up and download files from a Windows instance.
  • Install IIS web server on Windows 2008 R2.
  • Create an IBM Cloud instance with the Linux command line.
  • Create an IBM Cloud instance with the Windows command line.
  • Extend your corporate network with the IBM Cloud.
  • High availability apps in the IBM Cloud.
  • Parameterize cloud images for custom instances on the fly.
  • Windows-targeted approaches to IBM Cloud provisioning.
  
  
• The document mentioned in this article, Creating and customizing images, provides the XSD file and the xjc tool. It can also be found from the IBM Cloud dashboard Support tab (login to the IBM Cloud is required).
  
  
• In the developerWorks cloud developer resources, discover and share knowledge and experience of application and services developers building their projects for cloud deployment.
  
  
• The next steps: Find out how to access IBM Smart Business Development and Test on the IBM Cloud.
  
  

Get products and technologies

• See the product images available on the IBM Smart Business Development and Test on the IBM Cloud.
  
  

Discuss

• Join a cloud computing group on My developerWorks.
  
  
• Read all the great cloud blogs on My developerWorks.
  
  
• Join the developerWorks community, a professional network and unified set of community tools for connecting, sharing, and collaborating.
  
  

About the author

In recent years, Dominique Vernier focused on Java technologies and cloud architecture. He also has been working in Information Technology for quite a while where he earned a broad knowledge in such technologies and products as messaging, database, SOA, EAI, client/server, C/C++, and existing frameworks. Dominique also has extensive knowledge in industry areas such as telecom, CRM, logistics, and insurance. He is the author/co-author of four patents having to do with state engines and resource management. At present, Dominique is in charge of the Smart Business Development and Test on IBM Cloud solutions on the IBM GTS Global Team.

Rate this article

Comments

Back to top

Table of contents

• But first, some concepts
• Create the Java package
• Testing the parameters package
• In conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Learn more, join the cloud community, and get started with cloud computing tools from IBM

---

• Briefing: Attend a free briefing
• Community: Subscribe to the dW weekly edition newsletter and customize for cloud
• Buy: Try IBM software on IBM SmartCloud Enterprise

Dig deeper into Cloud computing on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers