VMware vCloud Suite SDK Java: samples README

  vCloud Suite Client SDK Java README

This document describes the vCloud Suite SDK Java samples that use the vCloud Suite Java client library (vcloudsuite-client-sdk-6.0.0.jar) and vAPI runtime library (vapi-runtime-1.0.0.jar). Additionally, some of the samples demonstrate the combined use of the Lookup Service, Tagging and Content Library and the vSphere API. To support this combined use, the vCloud Suite SDK Java includes the vSphere Management SDK jars (vim25.jar, pbm.jar). The examples have been developed to work with the JDK 1.7.

• Sample Packaging
• Sample Program Structure
• Running the Samples
• Importing the samples project in Eclipse

Sample Directories

The sample sub-directories show the organization of the samples Java packages. The samples are organized into the following capabilities:

Sample Program Structure

The vCloud Suite SDK Java samples use a framework to facilitate different aspects of using the samples. Some of the framework capabilities are:

• Command line argument parsing.
• Specifying mandatory and optional arguments for a sample.
• Sample setup, execution and post-execution cleanup.
• Information about samples.

To work with the VMWare-supported deployment configurations of Platform Services Controllers (Single Sign-On) and vCenter Servers, applications need to dynamically discover service URLs to make service requests. Before making service requests, applications need to authenticate with the Single Sign-On service.
Most of the vCloud Suite client application performs the following basic tasks to connect to the vAPI and vim service endpoint (on a management node) and accomplish Platform Services initialization.

• Step 1: Connect to the Lookup Service endpoint on the Platform Service Controller.
• Step 2: Discover the Single Sign-On service URL from lookup service endpoint.
• Step 3: Connect to the Single Sing-On URL and retrieve the SAML token.
• Step 4: Discover the vim, vim pbm, vAPI service URL's of the respective Management Node.
• Step 5: Use the SAML token to login to vAPI service endpoint.
• Step 6: Discover other services through the Lookup Service..
• Step 7: Perform certain tasks using the vAPI services.

The list of operations shown above are implemented in the LookupServiceHelper, PlatformServiceController and ServiceManager classes which are part of the vCloud Suite SDK for Java samples framework. These classes are located under samples/com/vmware/vcloud/suite/samples/common/. Every sample that connects to the vAPI endpoint and vim endpoint leverage these classes. Each sample extends the class SamplesAbstractBase. This class uses the LookupServiceHelper, PlatformServiceController and ServiceManager classes to discover and manage connections to the vAPI and vim service endpoints. Every sample implements the following SamplesAbstractBase methods:

• setup() - Called by SamplesAbstractBase during @Before phase. This occurs after authentication and vAPI and vSphere service initialization
• run() - Called by SamplesAbstractBase during @Action phase. At this point all the connections and services are initialized.
• cleanup() - Called by SamplesAbstractBase during @After phase. This occurs before disconnecting the services.

The following is the code snippet from samples/com/vmware/vcloud/suite/samples/common/SamplesAbstractBase.java which illustrates the order in which setup(), run() and cleanup() methods are called in the samples:

    public abstract void setup() throws Exception;
    public abstract void run() throws Exception;
    public abstract void cleanup() throws Exception;

    @Before
    public void init() throws Exception {
        platformServiceController = new PlatformServiceController(lookupServiceUrl);
        SSOConnection ssoConnection = platformServiceController.getSsoConnection(ssoUsername, ssoPassword);
        managementNode = platformServiceController.getManagementNode(mgmtInstanceName);
        managementNode.connect(ssoConnection);

        setup();
    }

    @Action
    public void execute() throws Exception {
        run();
    }

    @After
    public void after() throws Exception {
        try {
            if (clearData) {
                cleanup();
            }
        } finally {
            managementNode.disconnect();
        }
    }

Running the samples

The samples framework is designed to execute any of the samples provided in the kit. To run a sample, you must at least specify authentication parameters and lookup service endpoint url.

• ssousername and ssopassword for authentication with the VMware Single Sign-On Server.
• lookupserviceurl lookup service endpoint URL on the Platform Service Controller's.
• Optional - You can set the cleardata flag to true if you want the framework to delete the sample data after the sample finishes.

You can specify the lookup service API endpoint url, Single Sign-On username and password in the sample.properties file, or you can specify them on the command line when you execute a sample program. These properties are declared as input options, using the @Option declarations. When you execute a sample, the samples framework will resolve the input values from the appropriate source. To print help about a sample, specify --help on the command line.

Running the samples from command line

You can run the samples from the command line. The SDK provides the command line scripts run.sh (Linux) and run.bat (Windows). These files are located in the VMware-vCloudSuite-Java-SDK/client directory. You must set the JAVA_HOME environment variable to the base directory for the JDK that you are using, either JDK 1.6 or JDK 1.7

$run.sh com.vmware.samples.packagename.SampleClassName --lookupserviceurl lsurl --ssousername username --ssopassword password

$run.sh TaggingWorkflow --lookupserviceurl https://endpoint.domain/lookupservice/sdk --ssousername [email protected] --ssopassword password --clustername vAPISDKCluster --cleardata true
Script parameters:
TaggingWorkflow (M) - sample class name.
lookupserviceurl(M) - lookup service SDK Url.
ssousername     (M) - Single Sign-On user name.
ssopassword     (M) - Single Sign-On user password.
clustername     (M) - The name of the cluster to be tagged.
cleardata       (O) - True, if if you want the framework to delete the sample data after the sample finishes.

./run.sh TaggingWorkflow --help
-- VMware samples in Java --

TaggingWorkflow

  Demonstrates tagging CRUD operations. Step 1: Create a
  Tag category called �Asset�. Step 2: Create a Tag called
  �Server� under the category �Asset�. Step 3: Retrieve
  an existing Cluster using VIM APIs. Step 4: Translates
  the Cluster's MoRef into vAPI ID. Step 5: Assign �Server�
  tag to the Cluster using the ID. Additional steps when
  clearData flag is set to TRUE: Step 6: Detach the tag
  from the Cluster. Step 7: Delete the tag �Server�. Step
  8: Delete the tag category �Asset�. Note: the sample needs
  an existing Cluster

  --lookupserviceurl  <lookupserviceurl>  [required]     lookup service SDK Url
  --mgmtinstancename  <mgmtinstancename>   [optional]
				management node's instance name.
				Ex: IP/FQDN of the node
  --multiplemgmtnode  &multiplemgmtnode>   [optional]
				set to true while running a
				sample against multiple management
				nodes.
  --ssousername  <ssousername>  [required]     Single Sign-On user name
  --ssopassword  <ssopassword>  [required]     Single Sign-On user password
  --cleardata    <cleardata>     optional
				set to true to clear up all
				the sample data after the run.
  --clustername  <clustername>  [required]
				The name of the Cluster to be
				tagged.

Importing the samples project in Eclipse

The samples directory contains .project and .classpath Eclipse project files. You can use these for code browsing or for development. To import the samples into Eclipse, use VMware-vCloudSuite-Java-SDK/client/samples as the root directory for an existing project.