# VMware vSphere Web Services SDK: JAX-WS Samples Readme |
This document describes the vSphere Web Services SDK samples that use the JAX-WS bindings for the vSphere API. The examples have been developed to work with the JAX-WS bundled with the JDK 1.8. The following sections describe how to build and run the vSphere Web Services SDK JAX-WS samples. Sample Directories Sample Program Structure Building the Sample Programs Running the Sample Programs Sample Documentation ## Sample Directories The vSphere Web Services SDK samples are located in sub-directories in the following vSphere Management SDK directory: `.../SDK/vsphere-ws/java/JAXWS/samples/com/vmware/` The sample sub-directories are organized into the following capabilities:
Capability/Directory | Samples
--- | ---
general | Demonstrates basic capabilities of the vSphere API.
alarms | Demonstrates how to use alarms to monitor the vSphere environment.
connection | How to establish a connection with a vCenter Server.
cim | Demonstrates how to use Common Information Model (CIM) in the vSphere environment.
events | How to use the event history collector.
guest | How to use the vSphere API to perform guest operations.
host | Host system and network configuration.
httpfileaccess | File operations using the HTTP protocol.
performance | How to retrieve performance data.
scheduling | How to schedule tasks.
scsilun | How to retrieve SCSI LUN identification data.
security | Username and password credential storage for automated application execution.
simpleagent | Support for automated login using local credential store.
storage | Storage DRS.
vapp | Using OVF Manager for import and export of virtual applications and virtual machine disk files.
vm | Virtual machine operations.
## Sample Program Structure Every vCenter client application performs the following basic tasks: Authenticating and connecting to a vCenter Server to establish a session. Obtaining access to vSphere methods. Using the methods to perform vSphere operations. The samples use custom Java annotations to organize these tasks. These annotations are `@Before`, `@Action`, and `@After`. The SDK sample code includes a samples framework that runs the samples and executes the sample code. Each sample extends the class `ConnectedVimServiceBase` (`.../SDK/vsphere-ws/java/JAXWS/samples/com/vmware/connection/ConnectedVimServiceBase.java`). This class contains the `@Before` and `@After` declarations. The `@Before` code performs authentication, connects to the vCenter Server, and obtains access to the vSphere methods. The `@After` code disconnects from the Server. Authentication and connection are handled in the connection sample implementation. For example, `SsoConnection.java` contains the SSO connection implementation. It obtains an SSO token for vCenter login, and it obtains access to the vSphere API methods. The SSO connection implementation uses the VMware Single Sign On sample code that is contained in the vSphere Management SDK (`.../SDK/ssoclient/`). See the VMware Single Sign On Programming Guide. Each sample file contains the `@Action` declaration, which contains the code that performs the capability of the particular sample. For example, the `GetCurrentTime` sample contains the `@Action` code - a call to the `CurrentTime` method. `GetCurrentTime.java` is located in the `general` directory (`.../SDK/vsphere-ws/java/JAXWS/samples/com/vmware/general/`). `public class GetCurrentTime extends ConnectedVimServiceBase { @Action public void getCurrentTime() throws RuntimeFaultFaultMsg { XMLGregorianCalendar ct = vimPort.currentTime(this.getServiceInstanceReference()); SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd 'T' HH:mm:ss.SSSZ"); System.out.println("Server current time: " + sdf.format(ct.toGregorianCalendar().getTime())); } }` The `GetCurrentTime` class extends the `ConnectedVimServiceBase` class and inherits its connection capability. When the `GetCurrentTime` sample executes, the sample framework performs the following: Executes the `ConnectedVimServiceBase @Before` code to establish the connection. This code also retrieves the `vimPort` object for access to vSphere API methods. Executes the `GetCurrentTime @Action` code to retrieve and display the current time. Executes the `ConnectedVimServiceBase @After` code to close the connection. ## Building the Sample Programs To build the sample programs, you must define the `JAVA_HOME environment variable and execute one of the build scripts to generate client stubs and compile the samples.` ### JAVA_HOME Environment Variable You must set the JAVA_HOME environment variable to the base directory of a JDK. ### Build Scripts The following table shows the build files located in the `SDK/vsphere-ws/java/JAX-WS/` directory.
Build Task | Files
--- | ---
Generate JAX-WS client stubs and compile samples. | build.sh build.bat
Delete generated files. | clean.sh clean.bat
Specify input for sample execution. | sample.properties
Specify connection parameters for sample execution. | connection.properties
Run a sample. | run.bat run.sh
#### Converting Shell Scripts for Linux The shell scripts (build.sh, clean.sh and run.sh) have DOS-style line endings. These do not work when running these scripts on Linux. Use the Linux command `dos2unix` to convert these files before you use them. To run these scripts, set the Execute permission on the files: `chmod a+x *.sh` ## Building Sample Programs The build scripts (build.sh and build.bat) generate vSphere API Java stubs from the vSphere API WSDL, compile the generated stubs, and compile the sample programs. You can specify the following command line options to control stub generation and compilation. `build -w` - Compiles sample programs but does not generate or compile stubs. `build -c` - Compiles stubs and sample programs; does not generate stubs. #### WSDL File Dependency JAX-WS requires a WSDL file for stub generation and compilation. To manage this dependency, the build script performs the following operations: Uses the JDK tool `wsimport` to generate the vSphere Web services Java stubs from the vSphere API WSDL file (`vimService.wsdl`). Specifies the `-wsdlLocation` command line option to `wsimport` to identify the WSDL file location. Copies the WSDL file and related schema files into the `vim25.jar` file. To compile Java code that imports the generated stubs and uses the `vim25.jar` built by the build script, the WSDL file must be in the same location that was specified in the `-wsdlLocation` command line option. To establish this location, the build script modifies the VimService class to reference the WSDL location inside the JAR file. You only need to add the `vim25.jar` file to your class path. ## Running a Sample The samples framework is designed to execute any of the samples provided in the kit. To run a sample, you must specify authentication parameters and server URLs. Username and password for authentication with the VMware SSO Server. URLs for the VMware SSO Server and vCenter Server. You can specify these in the sample properties file: .../SDK/vsphere-ws/java/JAXWS/samples.properties You can specify the vCenter Server URL, 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 and implementation in the following files: `/SDK/vsphere-ws/java/JAXWS/samples/com/vmware/connection/Connection.java /SDK/vsphere-ws/java/JAXWS/samples/com/vmware/connection/SsoConnection.java` When you execute a sample, the samples framework will resolve the input values from the appropriate source. ## Samples Documentation To print help about a sample, specify --help on the command line. You can also find information about the samples in the JAX-WS Samples Reference Documentation. Each package has a class summary that describes one or more samples.
Copyright © 2012-2016 VMware, Inc. All rights not expressly granted herein are reserved. | Last updated: 15 Nov 2016 | VMware vSphere Web Services SDK