VMware vCloud Suite SDK Java: samples README

VMware logo

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.

The following sections provide information about using the samples..

Sample Directories

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

PackageDescription
com.vmware.vcloud.suite.samples.cis.taggingFeature samples for cis Tagging
com.vmware.vcloud.suite.samples.commonSamples common classes and abstractions; This package does NOT contain any sample
com.vmware.vcloud.suite.samples.interopTagging/Content Library interop with vSphere API's samples
com.vmware.vcloud.suite.samples.vapi.endpointvAPI service endpoint abstractions; This package does NOT contain any sample
com.vmware.vcloud.suite.samples.vapi.helpersHelper classes for vAPI; This package does NOT contain any sample
com.vmware.vcloud.suite.samples.vim.helpersHelper and util classes for vSphere APIs.; This package does NOT contain any sample
com.vmware.vcloud.suite.samples.workflowVarious vAPI work flow samples

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.

The samples framework uses Java custom annotations to implement some of these capabilities. These annotations are @Before, @Action, and @After. The framework imposes a unified structure on the samples so that it is easier to find specific code fragments. The samples annotations and framework are already integrated into the vCloud Suite Java samples project.

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

Use the following syntax to invoke run.sh:
$run.sh com.vmware.samples.packagename.SampleClassName --lookupserviceurl lsurl --ssousername username --ssopassword password
Example:
$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.

Use the --help option to print information about a sample. The following example shows the help for the Tagging work flow sample.
./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.


Copyright © 2015 VMware, Inc. All rights not expressly granted herein are reserved.

Last updated: 26th Jan 2015 |  VMware vCloud Suite SDK Java