Set Up for Java Development

Specific setup instructions depend on whether your development workstation already meets some or all of the requirements, which client-side Web service library you plan to use, and whether you plan to use the provided samples. Specific setup instructions also depend on whether your target server uses the HTTPS protocol or HTTP.

Software Downloads

You can obtain the software you need for Java client development from the following Web sites:

■	The J2SE is available from http://www.oracle.com. For best results, use JDK 1.7 or later.

■	Obtain the VMware vSphere Web Services SDK from https://developercenter.vmware.com. It is included in the vSphere Management SDK package.

Set Up for Development Using JAX-WS

The samples generated using JAX-WS libraries and compiled using Java JDK 1.7 include vim25.jar and samples.jar. You can use these libraries without generating new stubs and recompiling if you are using the same version of the JDK.

The following instructions assume that the target server uses HTTPS, which is the default server configuration.

To set up a development workstation to use Java and JAX-WS

1	If the JDK is not installed, create directories for the JDK and for the vSphere Web Services SDK package.

Do not use spaces in the directory names, to avoid issues with some of the included SDK batch and script files.

2	Install the Java 2 Platform, Standard Edition (J2SE) 6.0.

3	Unpack the components into subdirectories created in Step 1, using the provided installer if appropriate.

The J2SE uses an installation wizard. The SDK ZIP file unpacks into the directory you specify.

■	Unpack with Use folder names selected, to maintain the organizational structure.

■	On UNIX development systems, use the unzip command with the -a modifier, to ensure proper line-endings in the shell scripts. For example:

unzip -a VMware-vSphere-SDK-4.1.0-251329.zip

4	(optional) Import server-certificates and use the Java keytool utility to create a vmware.keystore. See Import Server Certificates into the Java Keystore for details.

As an alternative, pass the --ignorecert argument at runtime to ignore server-certificate verification for any of the sample Java applications.

5	Create the JAVAHOME environment variable.

The JAVAHOME environment variable must be set to the root path of the Java Runtime Environment (JRE), such as C:\Program Files\Java\jdk1.7.0_21. The root directory of your Java installation contains bin\javac and other binary files needed to build the stubs and the samples.

6	If you are unable to use the run.bat script to run Java samples, add the precompiled sample files, vim25.jar and samples.jar, to your system CLASSPATH environment variable.

To test your setup, run the Java version of SimpleClient, as described in Running the SimpleClient Sample Application to Validate Setup.

Batch Files and Shell Scripts for Building and Running Samples

The vSphere Web Services SDK includes several batch files for Windows and shell scripts for Linux that facilitate building and running the sample applications.

Note If you are using the JAX-WS 2.1 libraries with JDK 1.7, you do not need to rebuild the samples.

Some of the batch files are used by other batch files. For example, build.bat calls the lcp.bat and clean.bat scripts. If you modify the batch files for any reason, be aware of the dependencies among them.

Batch Files and Shell Scripts for Java

Filename	Description	Usage note
build.bat build.sh	Checks for environment variable JAVAHOME and sets PATH, using the JAVAHOME variable. Cleans up existing Java files (by calling clean.bat or clean.sh). build.bat sets the local classpath (by calling lcp.bat). Creates the vim25.jar, and samples.jar files.	Use this script to generate client stubs and rebuild all sample applications. Use the -w flag to recompile without regenerating stubs.
lcp.bat	Sets the local classpath on the workstation. Called by build.bat and by run.bat.	Optional. Use to set local classpath.
run.bat run.sh	Batch file that enables running any of the sample applications. Sets the Java trustStore property to the local trust store and invokes the Java runtime with the name of the application passed as a parameter.	Use this script to run any Java sample applications.
clean.bat	Removes any existing artifacts before building the samples, deleting Java class files in the samples packages and samples.jar file. Called by build script.	Optional. Deletes all generated source code files.

Import Server Certificates into the Java Keystore

Import server certificates if you plan to use the HTTPS protocol and if you do not plan to use the --ignorecert command-line argument.

To use HTTP, rather than HTTPS, and avoid the use of certificates entirely, follow the procedure detailed in Modifying Server Configurations to Support HTTP. However, using HTTPS provides better security for production environments.

The JAVAHOME environment variable must be set and added to the PATH environment variable. The certificate for each target server must be located in the C:\VMware-Certs subdirectory. See Obtaining Server Certificates.

To import certificates into a local Java keystore

1	Open the Windows command prompt or Linux shell command.

2	Create the directory for the Java certificate store.

Create the directory only. The actual keystore file, vmware.keystore, is created during the process of importing the certificates.

Operating System	Path
Windows	C:\VMware-Certs\vmware.keystore
Linux	~/vmware-certs/vmware.keystore

3	Navigate to the directory.

For example, on Windows use the following directory:

cd vmware-certs\vmware

4	Use the Java keytool utility to import a certificate.

The syntax is as follows:

keytool -import -trustcacerts -alias server-name -file certificate-filename -keystore keystore-name

For example:

C:\VMware-Certs>keytool -import -trustcacerts -alias root -file root.cer -keystore keystore.jks

A prompt requesting a password for the keystore appears:

Enter keystore password:

5	Create a password for the keystore by entering it at the prompt.

The keystore utility displays the certificate information at the console. For example:

Owner: OID.1.2.840.113549.1.9.2="1183400896,564d7761726520496e632e", CN=sdkpubslab-01.vmware.com, [email protected], OU=VMware ESX Server Certificate, O="VMware, Inc.", L=Palo Alto, ST=California, C=US Issuer: OID.1.2.840.113549.1.9.2="1183400896,564d7761726520496e632e", CN=sdkpubslab-01.vmware.com, [email protected], OU=VMware ESX Server Certificate, O="VMware, Inc.", L=Palo Alto, ST=California, C=US Serial number: 0 Valid from: Mon Jul 02 11:28:17 PDT 2007 until: Mon Aug 31 11:28:17 PDT 2026

Certificate fingerprints:

MD5: . . .61:35:C0:C4

SHA1: 4C:...78:B2

At the end of the certificate information, a prompt displays a request for confirmation that the certificate is trusted:

Trust this certificate? [no]:

6	Type yes and press Enter to respond to the prompt and import the certificate into the vmware.keystore keystore.

The console displays this message:

Certificate was added to keystore

7	Repeat Step 4 through Step 6 for each target server.