Virgo recipe "Building RESTful Web Service"

Virgo Homepage


This guide is inspired by "Building RESTful Web Service" from the Spring Guides.

Building RESTful Web Service

The original guide uses Spring Boot to bootstrap the demo application. This guide shows what needs to be done to get the "Building RESTful Web Service" up and running on Virgo.

Shopping list


Only Virgo Server for Apache Tomcat and Virgo Jetty Server are supported by the Virgo Tooling.



Get the code

Clone the code from the Git repository: Sample Git repository:

$ cd ~/MyAwesomeProjectDirectory/
$ git clone git://
$ cd org.eclipse.virgo.samples
$ cd recipe-rest-service

Once inside the source directory of this recipe - your are good to go.

Create the Custom Virgo Runtime

Create your own Virgo runtime with Gradle and Dockerizor:

$ ./gradlew :recipe-rest-service-runtime dockerize

The custom Virgo Runtime is packaged as tar archive and available from the runtime build directory. Extract the runtime into some directory - let’s say into VIRGO_HOME.


You’ll need a Docker daemon running in order to create your custom Virgo runtime. For more information please refer to the Dockerizor documentation.

Create Eclipse Project Metadata

Create the Eclipse IDE metadata with:

$ ./gradlew eclipse

Prepare the Virgo Tooling

Download Eclipse IDE for Java EE Developers e.g. Eclipse Mars.2 (4.5.2).

Start your Eclipse IDE and add the Virgo Tooling to your Eclipse IDE.

Optionally add the Docker Tooling to your Eclipse IDE.

Import the code into your Eclipse IDE

Now you can menu:Import[Gradle > Gradle Project] into your IDE. The project folder is called recipe-rest-service and lies directly in the "Sample Applications" folder you created previously with the Git clone command. (org.eclipse.virgo.samples).


Before you can drag’n’drop the project onto your freshly created Virgo Server you might have to execute menu:Virgo[Run Generation] of META-INF/MANIFEST.MF (via a right click on the project) within your Eclipse IDE.

Create new Virgo Server Runtime

Define a new server

Within the IDE menu:New[Server > EclipseRT > Virgo Runtime] and choose the directory of the previously installed Virgo server VIRGO_HOME.


Virgo has no support for Spring’s @EnableAutoConfiguration, so you have to be more explicit than in the Spring Boot version of this guide - after all, Virgo is an OSGi runtime and every bundle needs to declare its needs in the META-INF/MANIFEST.MF. Basically, you have to specify necessary dependencies (via Import-Package or Import-Bundle headers) and the Web-ContextPath the REST service application wants to be published on.
Bundle-Version: 0.1
Bundle-Name: Virgo Recipe REST service
Bundle-SymbolicName: org.eclipse.virgo.samples.recipe.restservice
Bundle-Vendor: Eclipse Virgo
Bundle-Version: 0.1.0.BUILD-SNAPSHOT
Import-Bundle: org.springframework.beans,
Web-ContextPath: /restservice-guide
Bundle-Classpath: .

You can mix and match the Virgo specific header Import-Bundle and OSGi standard header Import-Package within the MANIFEST.MF. In the sample the fine-tuning of the generated MANIFEST.MF is done within

If you intend to run your bundles in different OSGi containers you have to limit yourself to the OSGi standard headers.

Next step is to configure the servlet container via WEB-INF/web.xml:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="" xmlns:xsi=""
	xsi:schemaLocation="" version="2.4">

    <!-- The definition of the Root Spring Container shared by all Servlets and Filters -->


    <!-- Creates the Spring Container shared by all Servlets and Filters -->

    <!-- Processes application requests -->


The most important parameter is the contextClass which is not the default from the Spring Framework, but

Finally the Spring web application context.:

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns=""
	xmlns:xsi="" xmlns:beans=""

	<!-- Enables the Spring MVC @Controller programming model -->
    	<message-converters register-defaults="false">
        	<beans:bean id="jackson2MessageConverter" class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter" />

	<context:component-scan base-package="org.eclipse.virgo.samples.recipe.restservice" />

	<beans:bean class="org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter" />


Within the servlet-context.xml we define a single message converter jacksonMessageConverter using Jackson 2:

<message-converters register-defaults="false">
    <beans:bean id="jackson2MessageConverter" class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter" />

Let’s taste

Start the Virgo server inside the Springsource Tool Suite to appreciate what you build. With curl and the command line simply run the following command within the project’s directory:

$ curl -i -H "Accept: application/json" 'http://localhost:8080/restservice-guide/greeting?name=test'

You should see an output like:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 12 Oct 2015 11:06:50 GMT

{"id":2,"content":"Hello, test!"}%

Dockerise the Application

We use Gradle and Dockerizor to build the application. Instead of running the sample within the Eclipse IDE you can build a Docker image:

$ ./gradlew dockerize

and run the application with:

$ docker run --rm -it --name rest-service --publish 8080:8080 virgo-recipe/rest-service-app