Jump to: navigation, search

Difference between revisions of "Virgo/Tooling"

Line 43: Line 43:
*The greenpages sample does not work. We're not yet sure if this is a tooling or runtime issue. https://bugs.eclipse.org/bugs/show_bug.cgi?id=368781  
*The greenpages sample does not work. We're not yet sure if this is a tooling or runtime issue. https://bugs.eclipse.org/bugs/show_bug.cgi?id=368781  
**You can see all open bugs [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=1289794;query_format=advanced;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;component=tooling;product=Virgo here].
**You can see all open bugs [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=1289794;query_format=advanced;bug_status=NEW;bug_status=ASSIGNED;bug_status=REOPENED;component=tooling;product=Virgo here].
=What's New=
==1.0.0 Release==
We've added more views and other tools for working with Virgo Runtime instances. See the expanded Tooling Guide for more information on these new features.
In addition to the new Repository View, we've added:
=====Properties View=====
The properties view allows you to directly access all of those Virgo Runtime properties that are buried away in one file or another.
=====Logs View=====
The logs view gives you direct access to all of the relevant Virgo logs, no matter where they are located.
====Virgo Server Projects====
To support those new features, Virgo Tooling now maintains a project for each configured Runtime. Because these are Eclipse projects you can use all of the powerful Eclipse IDE tools to explore artifacts installed on the servers. (You shouldn't try to modify these projects directly though.) For example, you can use the JDT Type Hierarchy and Open Type tools.
*We've addressed a number of significant bugs for the final release.
*Clarified UI.
*Improved documentation.
==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.
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.
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.
*Extensive bug fixes and re-factorings.
*All Remaining Spring Dependencies have been removed.
*Updated to meet Eclipse branding, packaging build and testing standards.
= Migration  =
= Migration  =

Revision as of 14:07, 7 September 2012


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.


Install Eclipse

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

  • Eclipse Indigo 3.7.x or Indigo based suite such as SpringSource Tool Suite 2.9.x
  • Eclipse Juno 3.8/4.2

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.

Note: Select only Virgo Tooling. This is a composite site, and the other features are not designed to work within the Eclipse IDE.


Update Sites

http://download.eclipse.org/virgo/release/tooling (Recommended)
http://download.eclipse.org/virgo/snapshot/tooling (Bleeding Edge)

Known Issues


From Pre M2 to M4

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 -- and you will see nasty exceptions if you try to use them. But since pre-M4 Virgo Tooling didn't work with Virgo Server 3.5 anyway, this should be a moot issue for most people.

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 -> 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 -> 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 -> 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 -> org.eclipse.virgo.ide.facet.core.bundlenature and (com.springsource.server.ide.facet.core.parnature -> 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" to "xmlns:org.eclipse.virgo.ide.par="http://eclipse.org/virgo/par.ecore"

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):

# NOTE1: Run this at your own risk :)
# NOTE2: I should quote more dots in sed expressions but I'm lazy.
# TODO: Delete old com.springsource files after conversion
if [ ! -d "$1" ]; then 
        echo "Please point me at an eclipse project" ; 
        exit 1

# Bundlor settings
[ -f "$f" ] &&  (
        echo "$1: Converting bundlor preferences"
        sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' "$f" > "$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)"

# convert PAR
[ -f "$f" ] &&  (
        echo "$1: Converting PAR project dependencies"
        sed -e 's/com\.springsource\.server/org.eclipse.virgo/g' "$f" > "$(echo $f | sed -e s/com.springsource.server/org.eclipse.virgo/)"

# Fix classpaths        
[ -f "$f" ] && (
        echo "$1: Converting classpath containers and entries"
        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' \
# Fix natures..
[ -f "$f" ] && (
        echo "$1: Converting project natures"
        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' \

# Fix the wst file, could also replace runtime name here
[ -f "$f" ] && (
        echo "$1: Converting org.eclipse.wst.common.project.facet.core.xml"
        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'  \

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.


In order to use the plugin one has to download the source code from Github 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.

mvn clean install

Moreover to generate the documentation just execute the following Maven command (or take the one provided in the repository on Github).

mvn clean plugin:xdoc javadoc:javadoc jxr:jxr site


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

Goal Description
virgo:start Starts a Virgo instance by executing the provided startup script.
  • This goal has only been tested on Windows. Feedback for Unix/Mac is appreciated.
  • When executing this goal from within Eclipse (at least on Windows) a console view keeps running even though the build itself has succeeded. Once the opened window has been closed (shutting down the server will not be sufficient) the console view will finish as well.
  • Currently no starting arguments are provided. Once people start asking for this feature it will be added.
virgo:shutdown Stops a running Virgo instance.
virgo:immediateShutdown Stops a running Virgo instance immediately.
virgo:deploy Deploys an OSGi bundle to a running Virgo instance.
virgo:undeploy Undeploys an OSGi bundle from a running Virgo instance.
virgo:refresh Refreshs an already installed module on a running Virgo instance.
virgo:bundleRefresh 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. 

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<name>OSGi Test Bundle</name>	

More examples can be found in the documentation. Following are some exemplary Maven commands.

mvn virgo:start                             <-- will start a Virgo instance
mvn clean package virgo:deploy              <-- will create an artifact and deploy it to Virgo

Importing Virgo Projects into Eclipse

See Eclipse Setup under the Committers tab.


  • How do I turn on (or turn off) automatic Manifest generation? (Bundlor)

Bundlor is not used by default, you must create you own template file and then turn on incremental manifest generation. Right-click your Virgo project, select the Virgo subcategory from the context menu and select Enable (or Disable) Incremental Generation of MANIFEST.MF File. You can also modify this setting from the Overview page of the Bundle Manifest Editor, under the Bundle Actions section.

  • Sometimes I'd like to automatically update my Manifest without having to turn on the automatic Manifest setting. How can I do this?

Right-click your Virgo project, select the Virgo subcategory from the context menu and select Run Generation of MANIFEST.MF File. This command has a keybinding that you may customize through Eclipse's Keys preferences. You can also perform an automatic update of the Manifest from the Overview page of the Bundle Manifest Editor, under the Bundle Actions section.

  • Automatic Manifest generation doesn't appear to be picking up changes to my source files.

Sometimes Manifest generation may behave differently depending on whether the tools are configured to scan source folders or to scan output folders. To modify this setting right-click your Virgo project, select Properties and select the Virgo -> Manifest Generation subcategory. If Manifest generation isn't working correctly for you, uncheck the "Scan output folders instead of source folders to generate MANIFEST.MF" setting and re-run the Manifest generation. If your Manifest is not being properly generated under either setting, please file a bug.


  • My Virgo project is validating its dependencies against the wrong Virgo runtime! How do I manage server runtimes for my Virgo projects?

If you've deployed your Virgo projects to multiple Virgo runtimes the tools will associate the project with each runtime, but will only validate against one runtime. In order to manage which Virgo runtime your bundle dependencies are validated against, right-click on the project, select Properties and select the Targeted Runtimes category. From this dialog you can give priority to a particular Virgo runtime.


  • How do I deploy a Plan with the Virgo tools?

Deploying a Plan works much the same way as deploying a Bundle or PAR from the tools. Unfortunately, the tools only handle Plan deployment correctly when the Plan refers to items already in Virgo's watched repository directories. If you try to deploy a Plan that references a project in the Eclipse workspace, the tools will fail. One workaround is to copy your workspace bundle(s) into repository/usr or some other watched repository directory. A discussion of this bug and other workarounds is available at https://bugs.eclipse.org/bugs/show_bug.cgi?id=379765

  • How do I create a Web Application Bundle?

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.

  • How do I export a Web Application Bundle (WAB)? Export -> Bundle Project produces an incorrect product.

To export a WAB invoke Export -> Web -> WAR File

This can happen after starting VJS clean because VJS is looking for a directory at $KERNEL_HOME/work/tmp but no tmp directory exists. A workaround is to start VJS from the command line without the -clean command, which will create the tmp directory. VJS can then be used from the tools. This bug and workaround are documented at https://bugs.eclipse.org/bugs/show_bug.cgi?id=384288

  • Can I get a deeper look into the state of the server from the Virgo Tools?

Yes! If you double-click a Virgo server runtime in the Servers view, you'll open up the server editor, with several pages of information. The Repository, Bundle Overview, Bundle Dependency Graph, and Server Console pages all give valuable insight into the state of the server. The Virgo perspective also provides several views into the Virgo Repository, Virgo Properties and Virgo Logs. See the Virgo Tooling Guide for more information.

  • I want to install Virgo Tools. Should I install all of this neat looking stuff under Virgo Add-ons?

We really don't recommend doing so (see #Install_Virgo). Select only Virgo Tooling and Eclipse will take care of installing anything the tooling relies on.

  • Can I use the Virgo Tools with traditional PDE/Equinox Bundles?

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.