VMware vSphere HTML Client SDK

Eclipse Plugin Generator

1. Creating a new HTML plugin Eclipse project
2. HTML plugin project details
3. Java plugin project

This document will guide you through your first HTML plugin project in Eclipse. The wizard described here is also available as a command line script if you don't want ntp use Eclipse (see /tools/Plugin generation scripts/create-html-plugin.[sh,bat]). If you would like to re-use code from a web application see "Starting from a web application" in the main documentation.

1. Creating a new HTML plugin Eclipse project

If you haven't installed the SDK Tools plugin in Eclipse see Eclipse-setup.html first.

Go to File > New > Others... and select HTML Plug-in project under the vSphere Web Client category. This will generate two starter projects: a UI project for the HTML plugin and its associated Java project containing the service code.

Enter the UI project name at the top (the convention is to end the name with "-ui", the Java project name will be the same with "-service"). If it is just a test you can keep the default plugin bundle name and the default package name at the bottom of the form, otherwise you should change them now because it's harder to do later!

The plugin name is always lowercase by convention. It is the internal name to be used in the plugin web-context path, not a name to display to users.

After clicking Finish the wizard generates the project files and opens both projects in your workspace:

Having separate UI and Service projects is not a requirement. You could combine all the code into one project and generate only one .war bundle.

Before exploring the content of those projects in details let's build them and deploy them on your running server to check out the new plugin:

Java project myplugin-service should already be built if you keep the option Project > Build Automatically.
(Note: the build-java script is only useful for command line builds outside Eclipse)

HTML project myplugin-ui doesn't contain any code to compile, it's a static webapp.

The next step is to deploy both bundles to the Virgo Server.

• Open the Servers tab view at the bottom.
• If the Virgo server is not running already, right-click Start or Debug to start it and wait a couple minutes until you see all bundles deployed in the Console view.
• Right click on the Virgo Server instance and select Add and Remove.

• Select the resource myPlugin on the left and click Add to move it to the right list.

The service bundle must always be added first because the UI bundle depends on it).
The Console will show the two bundles being deployed:

[14:22:46] [INFO ] Installing bundle 'com.mycompany.mypluginui.myplugin-service' version '1.0.0'.
[14:22:46] [INFO ] Installed bundle 'com.mycompany.mypluginui.myplugin-service' version '1.0.0'.
[14:22:46] [INFO ] Starting bundle 'com.mycompany.mypluginui.myplugin-service' version '1.0.0'.
[14:22:46] [INFO ] Started bundle 'com.mycompany.mypluginui.myplugin-service' version '1.0.0'.
[14:22:46] [INFO ] Installing bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0'.
[14:22:46] [INFO ] Installed bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0'.
[14:22:46] [INFO ] Starting bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0'.
[14:22:46] [INFO ] Starting web bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0' with context path '/vsphere-ui/Mypluginui'.
[14:22:49] [INFO ] Started web bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0' with context path '/vsphere-ui/Mypluginui'.
[14:22:49] [INFO ] Started bundle 'com.mycompany.mypluginui.myplugin-ui' version '1.0.0'.

Check the following if you get a deployment error:

• The java service must be deployed properly before the UI bundle can be deployed because the UI depends on the service. You can add them together in the Add/Remove dialog as long as the service bundle is first on the list.
• If the service fails to deploy make sure the project has been built properly in Eclipse (no need to use the Ant build script there)
• Check that your the directory server/stage/myplugin-service/META-INF contain MANIFEST.MF

Login to the HTML client at https://localhost:9443/ui, or refresh the browser is you were already logged in.

You should see the plugin's shortcut button on the Home page under Monitoring. This opens a simple global view containing another button to test the EchoService on the server side:

The second view is a Host Monitor tab extension which displays some host information:

2. HTML plugin project details

The UI project generated by the wizard has the structure described below. It can be extended further for your own needs but be sure to keep the configuration files as they are unless you have a good reason to change them!

The webapp folder contains everything that needs to be deployed on the server for this UI plugin:

• When deploying within Eclipse or STS the Virgo tooling makes a copy of the webapp content in the server's stage directory. You can see that configuration in /myplugin-ui/.settings/org.eclipse.wst.common.component.
• If you want to deploy without Eclipse you can zip the webapp content into a .war bundle and copy it to vsphere-ui/server/pickup
• The same war bundle will be included in your plugin package once it is ready to be tested by others or be registered with vCenter.

MANIFEST.MF, bundle-context.xml and web.xml

MANIFEST.MF is generated for the HTML project as shown below:

• Bundle-SymbolicName must be unique.
• Web-ContextPath must start with vsphere-client/
• Import-Package list contains standard packages for a webapp as well as plugin specific packages that allow this UI bundle to reference classes on the Java side (com.mycompany.mypluginui.mvc, com.mycompany.mypluginui.services)

Be sure to add/change packages if your Java services are in other locations, or more libraries are needed.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: myplugin-ui
Bundle-SymbolicName: com.mycompany.mypluginui.myplugin-ui
Bundle-Version: 1.0.0
Bundle-Vendor: VMware
Web-ContextPath: vsphere-client/Mypluginui
Import-Package: com.mycompany.mypluginui.services,
 com.mycompany.mypluginui.mvc,
 com.vmware.vim.binding.vmodl,
 com.vmware.vise.core.model,
 com.vmware.vise.data.query,
 com.vmware.vise.messaging.remoting,
 com.vmware.vise.messaging.endpoints,
 com.vmware.vise.security,
 com.vmware.vise.vim.data,
 com.ctc.wstx.stax,
 javax.servlet,
 javax.servlet.http,
 net.sf.cglib.core,
 net.sf.cglib.proxy,
 net.sf.cglib.reflect,
 org.eclipse.gemini.blueprint.config,
 org.eclipse.osgi.framework.internal.core,
 org.eclipse.virgo.web.dm,
 org.osgi.framework,
 org.springframework.beans.factory.config,
 org.springframework.context.config,
 org.springframework.stereotype,
 org.springframework.web.bind.annotation,
 org.springframework.web.context,
 org.springframework.web.context.support,
 org.springframework.web.servlet.config,
 org.springframework.web.servlet,
 org.springframework.web.servlet.handler,
 org.springframework.web.servlet.view,
 org.springframework.web.servlet.view.json
 

WEB-INF/Spring/bundle-context.xml contains the Spring configuration, most of it should NOT be changed if you want conform to the Spring MVC patterns and keep things simple! The references to the java services will need to be updated as you define your own services:

   <!-- OSGI references to your services used by the controllers -->

   <osgi:reference id="echoService"
         interface="com.mycompany.mypluginui.services.EchoService" />

   <osgi:reference id="sampleActionService"
         interface="__packageName__.services.SampleActionService" />

WEB-INF/web.xml is the web-app metadata required for the sample plugin to run. In most cases you won't need to add anything for your own app.

3. Java plugin project

The Java project generated by the wizard has the following structure:

By convention the controllers and related utilities are grouped in a folder /mvc and the java services in a folder /services. Classes inside /mvc are very generic and can be reused in any project.

Here is a quick description of each file following the project order:

• ActionResult.java: Utility defining the result of an action called in an ActionsController.
• ActionsController.java: Controller for requests to endpoint /actions.html. It is a simple dispatcher to services that can be invoked through an action and uses ActionsResult to package the response..
• DataAccessController.java: Controller for requests to endpoint /data used to fetch object properties. It uses QueryUtil to generate DataService queries.
• QueryIdUtil.java: Utilities for encoding/decoding object ids which may contain "/".
• QueryUtil: Utility generating DataService queries.
• ServicesController: Controller for requests to endpoint /services. It acts as a simple dispatcher to plugin services.
• EchoService, EchoServiceImpl: Sample Echo service.
• SampleActionService, SampleActionServiceImpl: Sample service responding to user actions.

/META-INF contains the spring configuration files as well as MANIFEST.MF which looks like this by default:

Manifest-Version: 1.0
Bundle-Vendor: VMware
Bundle-Version: 1.0.0
Tool: Bundlor 1.1.0.RELEASE
Bundle-Name: myplugin-service
Bundle-ManifestVersion: 2
Bundle-SymbolicName: com.mycompany.mypluginui.myplugin-service
Export-Package: com.mycompany.mypluginui.services,
 com.mycompany.mypluginui.mvc
Import-Package: org.apache.commons.logging,
 com.vmware.vise.data,
 com.vmware.vise.data.query,
 com.vmware.vise.vim.data,
 javax.servlet.http,
 org.eclipse.osgi.framework.internal.core,
 org.springframework.beans.factory.annotation,
 org.springframework.http,
 org.springframework.stereotype,
 org.springframework.web.bind.annotation,
 org.springframework.web.context,
 org.springframework.web.context.support,
 org.springframework.web.servlet,
 org.springframework.web.servlet.view,
 org.springframework.web.servlet.view.json

Be sure to update those files as you add/remove classes or use 3rd party libraries. You can use the bundlor tool to generate MANIFEST.MF.

See also: Javascript API - Java API - FAQ