# Virgo Tools Guide

### Ramnivas Laddad

### Colin Yates

### Sam Brannen

### Rob Harrop

### Christian Dupuis

### Andy Wilkinson

### Glyn Normington

### Steve Powell

### Christopher Frost

### Miles Parker

### Leo Dos Santos

Virgo

3.5.0.RELEASE

Copyright © 2012 VMware Inc.

## 1. Tooling

Virgo Tools support the Virgo runtime with tools for managing servers, server runtimes, and bundles. The IDE tools build on top of the Eclipse Web Tools Project (WTP) and collaborate with other Eclipse technologies such as the Eclipse Libra project.

Among other things, the Virgo Tools support the creation of new OSGi bundle and PAR projects within Eclipse, and the conversion of existing projects into OSGi bundle projects. Projects can then be deployed and debugged on a running VTS from within Eclipse.

## 2.1 What's New

## 2.2 1.0.0 M4

We've made extensive changes throughout Virgo, focusing on quality and migration, but with a few new features as well.

### Improved Server Support

Virgo now supports almost all versions and types of Virgo installs, including older versions of Virgo and Tomcat, Jetty and Kernel installations. Best of all, you can now define servers using a single Server Runtime and the tooling will automatically discover the appropriate server configurations. You can even change server installations and versions for server runtimes without having to maintain any server setttings.

### UI

We've provided a number of new features aimed at improving the user experience. We've been giving more transparency and leverage into what's actually happening on the server. Right now, interactions with the server involve frequent shifts back and forth between the Eclipse IDE, the native file system and the command line. Our ultimate goal is to have tools powerful and complete enough that you can work with the server without ever having to move out of Eclipse.

#### Virgo Perspective

You can now get your own perspective on Virgo. We've organized it to support runtime exploration but it should be usable for general development as well. Please give us feedback on the overall setup; we'll incorporate the feedback in future releases.

#### Views

When we talked to current users of the Spring Source / Virgo tools, one of the things we discovered is that there were a lot of features that they wanted to have us implement that actually already existed, but in many cases were buried somewhere -- in many cases on a page in the server editor. So we're providing some of the information and tools that are provided in the WTP-based Server Editor as stand-alone views and enriching it. The idea is provide better insight into what's happening on the server side. Some of these features involve significant changes to how server resources are treated and we'd appreciate your feedback on how well they work for your usage scenarios. We'll use these changes as a basis for further enhancements.

##### Outline View

As a first take at helping users find what they're looking for, we provided an outline view that gives quick access to server artifacts.

##### Artifacts View

A new view supports transparent access to runtime artifacts. Currently, you can view bundle jars and libraries, but we'd like to support plans, pars, properties and other artifact types as well. But the real news is what we've built behind this -- Virgo runtimes are now exposed as Eclipse projects, giving you full access to the contents of jars, including classes. You can even use JDT tools like the Type view on Server side jar contents.

All of the new views are supported through the Eclipse Common Navigator Framework (CNF), which means that the views are highly configurable, and we've provided buttons to allow you to easily toggle on and off artifact types and present the artifacts in a tree or list view so that you can see all installed jars in one place.

##### Servers View

And because the views are all supported through CNF, you can easily customize them. For example, currently you can access all of the bundle information from the server view -- but we'll probably disable that by default in the release. In any case, you can set it up anyway you want by adding or removing the content provider. Again please let us know if you think of a way that we can improve the user experience for you.

### Documentation and Help

The complete virgo documentation set -- including the Tooling, Programmer and User's Guide as well as the Wiki pages -- is now included as Eclipse Help.

### Installation Process

Virgo Tools can now be installed from a single update site location.

### Quality

- Extensive bug fixes and re-factorings.

- All Remaining Spring Dependencies have been removed.

- Updated to meet Eclipse branding, packaging build and testing standards.

## 3. Running a Virgo Server for Apache Tomcat Instance Within Eclipse

After installing the Tools from the update site outlined in the previous section, you will be able to configure an instance of the VTS inside Eclipse.

To do so bring up the WTP Servers view (i.e., Window → Show View → Other → Server → Servers ). You can now right-click in the view and select " New → Server ". This will bring up a "New Server" dialog. Select "Virgo Server for Apache Tomcat v2.1 Server" in the "Virgo" category and click " Next ".

Within the "New Server Wizard" point to the installation directory of the Virgo Server for Apache Tomcat and finish the wizard. After finishing the wizard you should see a Virgo Server for Apache Tomcat entry in the Servers view.

To start, stop, and debug the created Virgo Server for Apache Tomcat instance use the toolbar or the context menu actions of the Servers view.

## 4. Bundle and Library Provisioning

After successful configuration of an instance of the Virgo Server for Apache Tomcat in Eclipse you can use the Repository Browser to very easily install bundles and libraries from the remote SpringSource Enterprise Bundle Repository.

To open the Repository Browser double-click a Virgo Server for Apache Tomcat instance in the Servers view and select the "Repository" tab in the server editor. Please note that opening of the Editor may take a few seconds as the contents of the local repository needs to be indexed before opening.

The left section of the Repository Browser allows the user to run searches against the SpringSource Enterprise Bundle Repository and displays matching results. The search can take parts of bundle symbolic names, class or package names and allows wildcards such as ‘?’ and ‘*’. By selecting the checkbox left to a matching bundle and/or library and clicking the "Download" button it is very easy to install new bundles in the Virgo Server for Apache Tomcat. For your convenience JARs containing the bundle source code can be automatically downloaded as well.

Clicking the "Download" button will trigger an Eclipse background job that will download the selected repository artifacts and -- if desired -- the source JARs one after another.

The section on the right displays the currently installed bundles and libraries. Bundles with available sources are visually marked. You can very easily download missing source JARs by using the "Install Sources" button.

## 5. Developing OSGi Bundles

The Tools provide functionality that makes developing OSGi bundles, especially the editing of MANIFEST.MF files, easier.

## 5.1 Resolving Bundle Dependencies

While working with OSGi bundles, one of the most interesting and challenging aspects is defining the package, bundle, and library imports in the manifest and then keeping this in sync with your compile classpath either in Ant and Maven or Eclipse. In most cases you would typically be required to manually set up the Eclipse classpath. Ultimately, the Eclipse compile classpath is still different from the bundle runtime classpath, as normally an entire JAR file is being made available on the Eclipse classpath but not necessarily at runtime due to the explicit visibility rules defined in `Import-Package` headers.

The Tools address this problem by providing an Eclipse classpath container that uses an Virgo Server for Apache Tomcat-specific dependency resolution mechanism. This classpath container makes resolved dependencies available on the project’s classpath but allows only access to those package that are imported explicitly (e.g., via `Import-Package` ) or implicitly by using `Import-Library` or `Import-Bundle` .

To use the automatic dependency resolution, an OSGi bundle or PAR project needs to be targeted to a configured Virgo Server for Apache Tomcat instance. This can be done from the project’s preferences by selecting the runtime on the "Targeted Runtimes" preference page.

| Note
In most scenarios it is sufficient to target the PAR project to a runtime. The nested bundles will then automatically inherit this setting.

After targeting the project or PAR you will see a "Bundle Dependencies" classpath container in your Java project. It is now safe to remove any manually configured classpath entries.

The classpath container will automatically attach Java source code to the classpath entries by looking for source JARs next to the binary JARs in the Virgo Server for Apache Tomcat’s repository. You can also manually override the source code attachment by using the properties dialog on a single JAR entry. This manual attachment will always override the convention-based attachment.

## 5.2 Editing the Manifest

The Tools provide a Bundle Manifest Editor that assists the developer to create and edit MANIFEST.MF files. The editor understands the Virgo Server for Apache Tomcat specific headers like `Import-Library` and `Import-Bundle` and provides content assist features while editing source code. Furthermore a Eclipse Form-based UI is also available.

To open the Bundle Manifest Editor right click a MANIFEST.MF file and select "Bundle Manifest Editor" from the "Open With" menu.

| Note
Please note that the Virgo Server for Apache Tomcat specific manifest headers appear in green color to distinguish them from those headers defined in the OSGi specification. This also makes navigating much easier.

The content assist proposals in the source tab as well as in the UI-based tabs are resolved from the bundle and library repository of an installed and configured Virgo Server for Apache Tomcat. Therefore it is important to target the project or PAR to a specific VTS instance to indicate to the tooling which bundle repository to use.

| Note
If a OSGi bundle project is not targeted to a VTS instance, either directory or indirectly via a PAR project’s targetting, the manifest editor will not be able to provide content assist for importing packages, bundles, and libraries.

The Dependencies tab of the Bundle Manifest Editor enables the user to easily download and install bundles and libraries from the SpringSource Enterprise Bundle Repository by using the "Download..." buttons next to the "Import Bundle" and "Import Library" sections.

## 6. Developing PARs

In Virgo, applications consisting of multiple bundles can be packaged as a PAR.

To create a PAR, right-click in the Package Explorer and select New → Project… . In the dialog that opens select EclipseRT → PAR Project and press Next :

In the New PAR Project dialog, ensure the Use default location option is unchecked, enter a suitable name for the project, set the location to a suitable directory, and press Next . For example, the Greenpages sample PAR project would look like this:

In the next dialog, some of the PAR properties are pre-populated. Set the Application Name and the Version as appropriate, then ensure that the Target Runtime is set to Virgo Web Server (Runtime) ... and press Next . For example:

In the next dialog, select the bundles so that they are contained in the PAR and press Finish . For example:

The PAR project is then created.

## 7. Deploying Applications

Currently the Tools support direct deployment of WTP Dynamic Web Projects, OSGi bundle and PAR projects to the VTS from directly within Eclipse.

To deploy an application to the Virgo Server for Apache Tomcat just bring up the context menu on the configured VTS runtime in the Servers view and choose "Add or Remove Projects...". In the dialog, select the desired project and add it to the list of "Configured projects".

| Note
Deploying and undeploying an application from the VTS certainly works while the Virgo Server for Apache Tomcat is running, but you can also add or remove projects if the VTS is not running.

Once an application is deployed on the Virgo Server for Apache Tomcat the tooling support will automatically pick up any change to source files -- for example, Java and XML context files -- and refresh the deployed application on the VTS.

The wait time between a change and the actual refresh can be configured in the configuration editor of the runtime. To bring up that editor, double-click on the configured Virgo Server for Apache Tomcat instance in the Servers view.

## 8. Installation and Release Notes

## 8.1 Features

The Virgo Tooling/IDE concept concerns the whole Virgo tooling (that was available inside SpringSource Tool Suite) being put in a separate project. The tooling supports the following:

- Bundle projects

- Par projects

- Plan files/projects

- Web Bundles

- Deployment to a Virgo Server in the server view.

## 8.2 Installation

### Install Eclipse

If you're not installing into an existing Eclipse, you'll need one.

- Eclipse Helios SR2, or

- Eclipse Indigo

Eclipse JEE Indigo recommended.

### Install Virgo

1. Select Help>Install New Software..

2. Enter one of the Virgo update sites below.

3. Select "Virgo Tools" feature and click install.

### Update Sites

Note, M4 is not quite here yet, so as of the moment you should use the snapshot build, not the milestone. As soon as M3 is formally released, this will change.

Milestone: <code> http://download.eclipse.org/virgo/milestone/tooling&lt;/code&gt;
Snapshot: <code> http://download.eclipse.org/virgo/snapshot/tooling&lt;/code&gt;

Many users will also want to install the M2E release at: <code> http://download.eclipse.org/technology/m2e/releases&lt;/code&gt;. (e.g. in order to run the greenpages examples.)

## 8.3 Known Issues

### M4 Candidate (Current Snapshot)

The Virgo tools currently do not support Eclipse 3.6 (Helios) and derived Spring Source products. Please see: https://bugs.eclipse.org/bugs/show_bug.cgi?id=377236.

Significant bugs still exist. Please see these release train bugs for a current list, and please report any other issues you discover:

- 368783: Server management UI bug train https://bugs.eclipse.org/bugs/show_bug.cgi?id=368783

- 368785: Server runtime support bug train https://bugs.eclipse.org/bugs/show_bug.cgi?id=368785

- 368782: Plugin packaging issues bug train https://bugs.eclipse.org/bugs/show_bug.cgi?id=368782

You can see all open bugs here.

### M3

There wasn't one. :) We're moving to M4 to more closely align with Virgo Runtime releases.

### Milestone M2

#### Version Compatibility

The milestone does not work well with the current milestone of the runtime environment ("3.1.0" / 3.5.0). Please target the 3.0.2 Release Virgo Runtime or use the current milestone.

## 8.4 Notes

### Web Application Bundles

To create a web application bundle choose to create a normal bundle project, but on the Bundle Content panel select the additional property entitled "Web Application Bundle". On the Bundle Properties panel enter a suitable context path for the application as the Web-ContextPath.

### Bundlor

Bundlor is not used by default, you must create you own template file and then turn on incremental manifest generation.

### PDE/Equinox Bundles not supported yet

Deploying PDE/Equinox Bundles to Virgo Web Server are not yet supported yet, although exporting the bundles (as Eclipse Plug-in JARs) and manually deploying to Virgo Web Server works. Please show your support on Bugzilla #329198.

## 8.5 Migration

### From Pre M2 to M3

#### Server Versions

The good news: We have done away with the need for managing multiple server versions. This also means that we won't have to support multiple WebTools Server Runtimes and Servers which will make adding new servers and variants much easier. See https://bugs.eclipse.org/bugs/show_bug.cgi?id=373453 for more details.

The bad news: Any Server Runtimes that you already created for Virgo Server 3.5 will not work. But since Virgo Tooling didn't work with Virgo Server 3.5 *anyway*, this is sort of a moot issue.

What to do: If you have an existing (i.e., created using Virgo IDE installed before 10 March 2012) Virgo Server 3.5 Runtime defined, just delete it and replace it with a new Virgo Runtime in Preferences:Server:Runtime Environments. You'll see that the correct version is discovered automatically. Then, open any Servers that uses the old runtime and select the new one from the Runtime Environment popup menu.

### From Spring Source and Virgo 2.x Tooling

Moving from the old tooling to the new requires some changes to your existing projects, these are documented here.

The Bundlor .settings file has a new name ( com.springsource.server.ide.bundlor.core.prefs -&gt; org.eclipse.virgo.ide.bundlor.core.prefs) and the property keys in it have new names as well. Currently these just need to be changed manually (replace com.springsource.server by org.eclipse.virgo) or use the project properties pane to create new settings and delete the old one. (recommended)

The Bundle Dependencies classpath entry has a new name ( com.springsource.server.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER -&gt; org.eclipse.virgo.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER). This can be changed manually (in the .classpath file) or in the Java Build Path section of the project properties.

The attributes used to mark folders as test folders have been renamed ( com.springsource.server.ide.jdt.core.test.classpathentry -&gt; org.eclipse.virgo.ide.jdt.core.test.classpathentry). This can be changed manually (in the .classpath file).

The PAR and Bundle nature have been renamed ( com.springsource.server.ide.facet.core.bundlenature -&gt; org.eclipse.virgo.ide.facet.core.bundlenature and ( com.springsource.server.ide.facet.core.parnature -&gt; org.eclipse.virgo.ide.facet.core.parnature)). This can be changed manually (in the .project file).

The format and name of a PAR project changed. Rename .settings/com.springsource.server.ide.runtime.core.par.xml to .settings/org.eclipse.virgo.ide.runtime.core.par.xml. Inside the file rename occurences of com.springsource.server to org.eclipse.virgo.

Snapshot build change: We've made a change in our tooling that will require modifying the org.eclipse.virgo.ide.runtime.core.par.xml file so that it points to the correct par.ecore URI. Rename xmlns:com.springsource.server.ide.par=" http:///com/springsource/server/ide/par.ecore&quot; to "xmlns:org.eclipse.virgo.ide.par=" http://eclipse.org/virgo/par.ecore&quot;

Inside the WST settings file ( .settings/org.eclipse.wst.common.project.facet.core.xml) rename occurences of com.springsource.server.bundle to org.eclipse.virgo.server.bundle and occurences of com.springsource.server.par to org.eclipse.virgo.server.par.

Most/all of the conversion should be done by the following script (it has only see marginal testing, use at your own risk): < pre>#!/bin/sh

1. NOTE1: Run this at your own risk&nbsp;:)

2. NOTE2: I should quote more dots in sed expressions but I'm lazy.

3. TODO: Delete old com.springsource files after conversion

if -d &quot;$1&quot; ; then

echo &quot;Please point me at an eclipse project&quot;&amp;nbsp;;
exit 1

fi

1. Bundlor settings

f="$1/.settings/com.springsource.server.ide.bundlor.core.prefs" [ -f "$f" ] &amp;&amp; (

echo &quot;$1: Converting bundlor preferences&quot;
sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' &quot;$f&quot; &amp;gt; &quot;$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)&quot;

)

1. convert PAR

f="$1/.settings/com.springsource.server.ide.runtime.core.par.xml" [ -f "$f" ] &amp;&amp; (

echo &quot;$1: Converting PAR project dependencies&quot;
sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' &quot;$f&quot; &amp;gt; &quot;$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)&quot;

)

1. Fix classpaths

f="$1/.classpath" [ -f "$f" ] &amp;&amp; (

echo &quot;$1: Converting classpath containers and entries&quot;
sed -i \
-e 's/com.springsource.server.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER/org.eclipse.virgo.ide.jdt.core.MANIFEST_CLASSPATH_CONTAINER/g' \
-e 's/com.springsource.server.ide.jdt.core.test.classpathentry/org.eclipse.virgo.ide.jdt.core.test.classpathentry/g' \
&quot;$f&quot;

)

1. Fix natures..

f="$1/.project" [ -f "$f" ] &amp;&amp; (

echo &quot;$1: Converting project natures&quot;
sed -i \
-e 's/com.springsource.server.ide.facet.core.bundlenature/org.eclipse.virgo.ide.facet.core.bundlenature/g' \
-e 's/com.springsource.server.ide.facet.core.parnature/org.eclipse.virgo.ide.facet.core.parnature/g' \
&quot;$f&quot;

)

1. Fix the wst file, could also replace runtime name here

f="$1/.settings/org.eclipse.wst.common.project.facet.core.xml" [ -f "$f" ] &amp;&amp; (

echo &quot;$1: Converting org.eclipse.wst.common.project.facet.core.xml&quot;
sed -i \
-e 's/com.springsource.server.bundle/org.eclipse.virgo.server.bundle/g' \
-e 's/com.springsource.server.par/org.eclipse.virgo.server.par/g' \
&quot;$f&quot;

)

</pre>

## 8.6 Maven plugin

To support the development of OSGi bundles for Eclipse Virgo with Maven a Maven plugin is available. This plugin is able to start/stop a local Eclipse Virgo instance. Moreover it is possible to deploy/undeploy/refresh bundles via Maven.

### Build

In order to use the plugin one has to download the source code from Github&nbsp;and build the binary manually. This can be easily done by executing the following Maven command in the root folder of the plugin where the pom.xml file is located. < pre>mvn clean install</pre> Moreover to generate the documentation just execute the following Maven command (or take the one provided in the repository on Github). < pre>mvn clean&nbsp;plugin:xdoc javadoc:javadoc jxr:jxr site < /pre>

### Goals

The plugin provides a set of Maven goals that allow different actions.

Goal | Description
<code>virgo:start</code> | Starts a Virgo instance by executing the provided startup script. <br>
<code>virgo:shutdown</code> | Stops a running Virgo instance.
<code>virgo:immediateShutdown</code> | Stops a running Virgo instance immediately.
<code>virgo:deploy</code> | Deploys an OSGi bundle to a running Virgo instance.
<code>virgo:undeploy</code> | Undeploys an OSGi bundle from a running Virgo instance.
<code>virgo:refresh</code> | Refreshs an already installed module on a running Virgo instance.
<code>virgo:bundleRefresh</code> | Refreshs an already installed OSGi bundle on a running Virgo instance.

### Simple example POM

Once the plugin has been build and installed in the local Maven repository it can be used within a Maven project. Following is a simple example of a pom file that uses the Maven plugin.&nbsp; < pre>&lt;project xmlns=" http://maven.apache.org/POM/4.0.0&quot; xmlns:xsi=" http://www.w3.org/2001/XMLSchema-instance&quot; xsi:schemaLocation=" http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd&quot;&amp;gt; &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt; &lt;groupId&gt;org.example.osgi&lt;/groupId&gt; &lt;artifactId&gt;test-bundle&lt;/artifactId&gt; &lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt; &lt;packaging&gt;bundle&lt;/packaging&gt; &lt;name&gt;OSGi Test Bundle&lt;/name&gt; &lt;properties&gt; &lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt; &lt;/properties&gt; &lt;build&gt; &lt;plugins&gt; &lt;plugin&gt; &lt;groupId&gt;org.apache.felix&lt;/groupId&gt; &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt; &lt;version&gt;2.3.6&lt;/version&gt; &lt;extensions&gt;true&lt;/extensions&gt; &lt;configuration&gt; &lt;instructions&gt; &lt;Bundle-SymbolicName&gt;${project.groupId}.${project.artifactId}&lt;/Bundle-SymbolicName&gt; &lt;Bundle-Name&gt;${project.name}&lt;/Bundle-Name&gt; &lt;Bundle-Version&gt;${project.version}&lt;/Bundle-Version&gt; &lt;/instructions&gt; &lt;/configuration&gt; &lt;/plugin&gt; &lt;plugin&gt; &lt;groupId&gt;net.flybyte.virgo&lt;/groupId&gt; &lt;artifactId&gt;virgo-maven-plugin&lt;/artifactId&gt; &lt;version&gt;1.0.0&lt;/version&gt; &lt;configuration&gt; &lt;virgoRoot&gt;C:/Java/virgo-tomcat-server-3.0.2.RELEASE&lt;/virgoRoot&gt; &lt;/configuration&gt; &lt;/plugin&gt; &lt;/plugins&gt; &lt;/build&gt; & lt;/project&gt; < /pre> More examples can be found in the documentation. Following are some exemplary Maven commands. < pre>mvn virgo:start &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;-- will start a Virgo instance mvn clean package virgo:deploy &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&lt;-- will create an artifact and deploy it to Virgo</pre>

## 8.7 Importing Virgo Projects into Eclipse

See Eclipse Setup under the Committers tab.

Category:Virgo Category:EclipseRT</rev></revisions></page></pages></query></api>