VMware VCLOUD SDK FOR JAVA 1.0 - DEVELOPER S GUIDE User manual

vCloud SDK for Java Developer’s Guide
vCloud SDK for Java 1.0
This document supports the version of each product listed and
supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.
EN-000362-00

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, Inc.
vCloud SDK for Java Developer’s Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
[e-mail]
Copyright © 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3
Contents
AboutThisBook 5
1AboutthevCloudSDKforJava 7
vCloudSDKforJavaDesign 7
vCloudObjectTaxonomy 7
vCloudOrganizations 8
vCloudUsersandGroups 8
vCloudNetworks 8
vCloudVirtualDatacenters 8
vCloudCatalogs 9
vCloudTasks 9
VirtualSystemsandMediaImagesinavCloud 9
2SettingUpforJavaDevelopment 11
Prerequisites 11
DownloadthevCloudSDKforJavaPackage 11
ImporttheSDKIntoYourJavaIDE 12
AboutSSLAccess 12
3HellovCloud:AStructuredJavaWorkflowExample 13
RunningtheHellovCloudSample 13
LoggingInandGettinganOrganizationList 14
GettingReferencestothevDCandCatalog 14
UploadanOVFPackagetoCreateavAppTemplate 15
AddthevAppTemplatetoaCatalog 16
InstantiatethevAppTemplate 16
OperatethevApp 17
4OverviewofPackagesandSamples 19
Packages 19
Samples 19
Index 21

vCloud SDK for Java Developer’s Guide
4VMware, Inc.

VMware, Inc. 5
Thisbook,thevCloudSDKforJavaDeveloper’sGuide,providesinformationaboutusingtheVMware®vCloud
SDKforJava.
VMwareprovidesseveraldifferentAPIsandSDKsforvariousapplicationsandgoals.Thisbookprovides
informationaboutusingthevCloudSDKforJavafordevelopersthatareinterestedincreatingclient
applicationsformanagingVMwarevCloudcomponentsavailableonVMwareESX,VMwareESXi,and
VMwarevCenterServersystems.
ToviewthecurrentversionofthisbookaswellasallVMwareAPIandSDKdocumentation,goto
http://www.vmware.com/support/pubs/sdk_pubs.html.
Revision History
Thisguideisrevisedwitheachreleaseoftheproductorwhennecessary.Arevisedversioncancontainminor
ormajorchanges.Table 1summarizesthesignificantchangesineachversionofthisguide.
Intended Audience
ThisguideisintendedforsoftwaredeveloperswhoarebuildingvCloudAPIapplications,including
interactiveclientsofVMwareCloudDirector.ThisguideassumesyouarefamiliarwiththeJavaprogramming
language,RepresentationalStateTransfer(REST)andRESTfulprogrammingconventions,theOpen
VirtualizationFormatSpecification,andVMwareVirtualmachinetechnology.Familiaritywithother
widely‐deployedtechnologiessuchasXML,HTTP,andtheWindowsorLinuxoperatingsystemsisalso
assumed.
VMware Technical Publications Glossary
VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions
oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.
Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Sendyourfeedbackto
[email protected].
Technical Support and Education Resources
Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversions
ofotherVMwarebooks,gotohttp://www.vmware.com/support/pubs.
About This Book
Table 1. Revision History
Revision Description
30AUG10 Version1.0

vCloud SDK for Java Developer’s Guide
6VMware, Inc.
Online and Telephone Support
Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and
registeryourproducts,gotohttp://communities.vmware.com/community/developer.
Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto
http://www.vmware.com/support/services.
VMware Professional Services
VMwareEducationServicescoursesofferextensivehands‐onlabs,casestudyexamples,andcoursematerials
designedtobeusedason‐the‐jobreferencetools.Coursesareavailableonsite,intheclassroom,andlive
online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides
offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout
educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

VMware, Inc. 7
1
TheVMwarevCloudAPIprovidessupportfordeveloperswhoarebuildinginteractiveclientsofVMware
CloudDirectorusingaRESTfulapplicationdevelopmentstyle.vCloudAPIclientsandserverscommunicate
overHTTP,exchangingrepresentationsofvCloudobjects.TheserepresentationstaketheformofXML
elements.HTTPGETrequestsareusedtoretrievethecurrentrepresentationofanobject,HTTPPOSTand
PUTrequestsareusedtocreateormodifyanobject,andHTTPDELETErequestsaretypicallyusedtodelete
anobject.
ThevCloudSDKforJavaisaJavalanguagebindingforthevCloudAPI.ItusestheJAXBframeworktocreate
JavaclassesfortheresourcesdefinedinthevCloudAPIXMLschemas.ThevCloudSDKforJavaprovides
classesandmethodsthatencapsulatetheinterfaces,objects,andoperationssupportedbythevCloudAPI
whilepreservingitsRESTfulprogrammingstyleandcompatibilitywiththeHTTPprotocolfamily.
ThisvCloudSDKforJavaDeveloper’sGuideprovidesinformationaboutsettinguptheSDKinadevelopment
environment,andinformationaboutrunningthesampleapplicationsincludedintheSDK.
Thischapterincludesthesetopics:
“vCloudSDKforJavaDesign”onpage 7
“vCloudObjectTaxonomy”onpage 7
vCloud SDK for Java Design
ThevCloudSDKforJavaprovidesobject‐specificmethodsforcreating,updating,retrieving,anddeleting
objectsdefinedbythevCloudAPI.Italsoincludeswrapperclassesthatprovide:
HelpersforRESTcommunicationandJavaobjectrepresentationoftheXMLresourcesdefinedbythe
vCloudAPI.
Helpermethodsthatcanassistinclientdevelopment
EverywrapperclasshasmethodsthataccessvCloudAPIresourcesusingareference.Areferenceobject
containsthehref,resourcetype,andnameproperties.Staticmethodsgetresourcesdirectlybypassingthe
reference,andactasconstructorsorfactoriesforSDKwrapperobjects.
vCloud Object Taxonomy
ThevCloudSDKforJavadefinesasetofobjectscommontocloudcomputingenvironments.Figure 1‐1
illustratestheprincipalobjecttypes.
About the vCloud SDK for Java 1
NOTEThevCloudSDKforJavadoesnotprovideobjectlifecyclemanagement.Everywrapperobject
representstheresourceatthetimeoftheGEToperation.IfaclientmakesmultipleGETrequestsforthesame
resource,theclientreceivesmultiplerepresentationsoftheresourcewrappedinthehelperobject.Thereisno
automaticrefreshoftheclient‐siderepresentation.Itistheclient’sresponsibilitytomakenewrequeststoget
thelatestvalues.Toavoidmemoryleaks,theclientmustdisposeofobjectsthatarenotinuse.

vCloud SDK for Java Developer’s Guide
8VMware, Inc.
Figure 1-1. vCloud Object Taxonomy
vCloud Organizations
AvCloudcontainsoneormoreorganizations.AvCloudorganizationisaunitofadministrationfora
collectionofusers,groups,andcomputingresources.Usersauthenticateattheorganizationlevel,supplying
credentialsestablishedbyanorganizationadministratorwhentheuserwascreatedorimported.
vCloud Users and Groups
Anorganizationcancontainanarbitrarynumberofusersandgroups.Userscanbecreatedbythe
organizationadministratororimportedfromadirectoryservicesuchasLDAP.Groupsmustbeimported
fromthedirectoryservice.Permissionswithinanorganizationarecontrolledthroughtheassignmentofrights
androlestousersandgroups.
vCloud Networks
Anorganizationcanbeprovisionedwithoneormorenetworks.Theseorganizationnetworkscanbe
configuredtoprovideservicessuchasDHCP,NAT,andfirewalls.
vCloud Virtual Datacenters
AvCloudvirtualdatacenter(vDC)isanallocationmechanismforresourcessuchasnetworks,storage,CPU,
andmemory.InavDC,computingresourcesarefullyvirtualized,andcanbeallocatedbasedondemand,
servicelevelrequirements,oracombinationofthetwo.
TherearetwokindsofvDCs:
ProvidervDCs.ThesevDCscontainalltheresourcesavailablefromthevCloudserviceprovider.
ProvidervDCsarecreatedandmanagedbyvCloudsystemadministrators.
OrganizationvDCs.ThesevDCsprovideanenvironmentwherevirtualsystemscanbestored,deployed,
andoperated.Theyalsoprovidestorageforvirtualmedia,suchasfloppydisksandCDROMs.
AnorganizationadministratorspecifieshowresourcesfromaprovidervDCaredistributedtothevDCsinan
organization.
Catalog 2
Catalogitem
em
em
em
Catalog 1
Catalog 3
vDC2 Catalogitem
Catalogitem
Catalogitem
Catalogitem
users
Media
vApp
template
Media
vApp
TasksList
Organization
vDC1
Media
vApp
template
Media
vApp
Network
Network
Catalogitem
em
em
em
groups

VMware, Inc. 9
Chapter 1 About the vCloud SDK for Java
vCloud Catalogs
Catalogscontainreferencestovirtualsystemsandmediaimages.Acatalogcanbesharedtomakeitvisibleto
othermembersofanorganization,andcanbepublishedtomakeitvisibletootherorganizations.AvCloud
systemadministratorspecifieswhichorganizationscanpublishcatalogs,andanorganizationadministrator
controlsaccesstocatalogsbyorganizationmembers.
vCloud Tasks
Long‐runningoperationsinitiatedbymembersofanorganizationcreatetasks,whicharekeptonthe
organization’staskslist.
Virtual Systems and Media Images in a vCloud
VirtualsystemsandmediaimagesarestoredinavDCandcanbeincludedinacatalog.Mediaimagesare
storedintheirnativerepresentation(ISOorfloppy).Virtualsystemsarestoredastemplates,usinganopen
standardformat(OVF1.0).Thesetemplatescanberetrievedfromcatalogsandtransformedintovirtual
systems,calledvApps,throughaprocesscalledinstantiation,whichbindsatemplate’sabstractresource
requirementstoresourcesavailableinavDC.AvAppcontainsoneormoreindividualvirtualmachines(Vm
elements),alongwithparametersthatdefineoperationaldetailssuchas:
Howthecontainedvirtualmachinesareconnectedtoeachotherandtoexternalnetworks.
Theorderinwhichindividualvirtualmachinesarepoweredonoroff.
End‐userlicenseagreementtermsforeachvirtualmachine.
Deploymentleaseterms(typicallyinheritedfromthecontainingorganization)thatconstrainthevApp’s
consumptionofvDCresources
Accesscontrolinformationspecifyingwhichusersandgroupscanperformoperationssuchasdeploy,
poweron,modify,andsuspendonthevAppandthevirtualmachinesitcontains.

vCloud SDK for Java Developer’s Guide
10 VMware, Inc.