Embed for Vaadin: run your Vaadin applications in an embedded server

Vaadin is a framework for building very nice web applications in fluent Java. Vaadin has a very rich component model that allows to design an application quite quickly. It only requires a servlet container and a single servlet definition with the Application class to use as a servlet parameter.

As everything we do here internally, we were searching for mechanisms to optimize our daily work tasks. In the case of Vaadin, two come naturally to mind:

1. Quickly show a component while prototyping a screen or part of a screen to validate its layout, style and basic behavior
2. In case of a test case failing, be able to quickly display the faulty component to get more visual details

In Vaadin 6 (the upcoming 7 version will change that slightly), a Vaadin application needs the following servlet definition to work properly:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">

    <servlet>
        <servlet-name>vaadin</servlet-name>
        <servlet-class>com.vaadin.terminal.gwt.server.ApplicationServlet</servlet-class>
        <init-param>
            <param-name>application</param-name>
            <param-value>com.bsb.incubator.vaadin.ShowcaseApplication</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>vaadin</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

Since its version 7, Apache Tomcat has a very nice embed API that allows you to configure and start a Tomcat container without the need to package a web application (or install Tomcat, for that matter). And it offers other nice feature such as the ability to allocate a random HTTP port that is available on your box instead of forcing you to choose one.

Embed for Vaadin is a Vaadin add-on we developed that takes care of the boring tasks of configuring and starting a servlet container. For instance, the following line would start a tomcat container with an application showing a simple button

EmbedVaadin.forComponent(new Button("Hello")).start();

This code gives the following, very simple result:

Image may be NSFW.
Clik here to view.

Since we are embedding Tomcat, we can pass an initialized component to the application. Even though we could serialize the component and deserialize it for another user, this mode does not support multi clients and multi sessions as the purpose is for a developer to debug or prototype  a particular component.

forComponent takes any Vaadin Component. If the component is a Window, we use it as the main window of the Application; If it is a Layout, we wrap the layout in a simple Window; If it is a more basic component, we wrap it in a VerticalLayout. It is also possible to pass an Application class, just like you would do while building a regular web application. In that case, we really configure a web.xml that is similar to the one above. For instance, the following would start the ShowcaseApplication:

EmbedVaadin.forApplication(ShowcaseApplication.class).openBrowser(true).start();

Noticed the openBrowser instruction? EmbedVaadin supports more options and these can be combined very easily before starting the embed server. In this case, this instructs to open the default browser at the URL that the server is using for the application. This speeds up the process a little bit more and it works for basic component too.

By default, the thread that started the server is blocking so that you can use the web application without caring about the server lifecycle. But you could use the same mechanism for integration tests purposes. The start() instruction returns you an EmbedVaadinServer that you can stop once your test has run:

final EmbedVaadinServer server = EmbedVaadin.forComponent(myComponent).wait(false).start();
// Your test
server.stop();

To use this add-on in your application, just add the following dependency to your project:

<dependency>
    <groupId>com.bsb.common.vaadin</groupId>
    <artifactId>com.bsb.common.vaadin.embed</artifactId>
    <version>0.1</version>
</dependency>

The add-on is available on the Central repository so you should not have any problem to get it with Maven.

We believe this plugin will improve in the future. Do not hesitate to fork the repository or give us feedback!