Implementing Enterprise Web applications with Vaadin

Part I - Setting up the development environment and project structure #

What is an enterprise web application? #

Enterprise web applications written in Java are mostly layered, component based applications that exist in the server side and are run in Application Server such as JBoss or GlassFish. Application Servers provide containers to host different components such as EJB Container for EJB Beans and Web Container for Servlets. In this tutorial I'll present ways to bind Vaadin together with other Java technologies used to build modern web applications. This first part of the tutorial is about setting up the development environment and project structure to support enterprise application development.

As mentioned, and as you probably knew, Vaadin is Servlet based User Interface framework that provides developer with User Interface components such as layouts, text fields, buttons and tables to implement the required UI to perform business operations. When saying backend, I mean everything below the User Interface layer. As Vaadin application is Servlet also the UI logic is run in the web container of an application server and only the representation of the application state is shown for the user in the browser window. This is sometimes called a thin client approach as Vaadin is fully Ajax based.

Enterprise web application is layered and component based application that has clear separation between User Interface, Business logic and data storage layers. On top of the application is the User Interface that can be seen as user’s window to the application. Right beneath it is usually the Facade layer that provides User Interface with ways to interact with the Business Logic. Facades are service provides that work as aggregates for Business EJB Beans. Business Beans are components that provide functionality to perform certain business operations, such as adding and updating product information to the storage system, handling product purchases from the cash register system and providing reports for management about sold products for example.

As with regular classes in every Object Oriented programming language, each class should serve only one purpose and have only one reason to change. Same applies to EJBs where one bean provides clean and simple API to serve single functionality. Of course one bean can have multiple methods to perform different business operations which are tightly related together but same EJB should not generate reports and handle updating storage amounts.

What EJBs mostly do is that they modify data within the system by certain business rules. This data is stored to the persistency layer with Java Persistence API (JPA). From developer point of view JPA manages entity instances that can be used as regular objects by the EJBs. One instance of certain entity represents a single row in one database table that can have relations to other tables. Theory of JPA is basically out of the scope of this tutorial but is mentioned as background information.

What makes an enterprise application so enterprisey is usually the usage of multiple technologies and specifications and modular structure. I hope to show you that even with more complex project structure you can easily create and maintain complex applications. Couple of simple design patterns and modular structure makes testing components and services easy and allows possibility to change things as requirements change during the development process.

Now let’s start with setting up the development environment. After that we’ll create basic enterprise application project structure “manually” without using dependency management tools like Maven. Such tools greatly help creating project structures but it’s also good to understand the basic before using such automated tools.

Setting up the development environment #

Let’s start by setting up the development environment. In this tutorial I'll be using Java EE version of Eclipse Indigo as development IDE and JBoss 7.1.1 as the Application Server that hosts my enterprise application. I’ve chosen JBoss 7 because we want to have Java EE 6 support. Other options like GlassFish 3 are also available so this is only personal preference.

If you have clean Java EE Eclipse and workspace with no JBoss 7 installed. Start off by first downloading the Community edition of JBoss 7.1.1. JBoss can be downloaded from: JBoss download site

After download extract the package to some folder. No other installation process or configuration is required at this time.

Start Eclipse and create new workspace. The purpose of new workspace is to have projects and JBoss runtime configured only to that workspace so you don’t clutter up your existing workspaces if something goes wrong. It's also good idea to have separate projects in their own workspaces.

Now that you have Eclipse running and JBoss nicely extracted, let’s attach the JBoss to Eclipse. This can be done using the JBoss Application Server tools that can be downloaded to Eclipse as plug-in from the Eclipse Marketplace. From Eclipse click Help menu item -> Eclipse Marketplace and type jboss as search term to the find dialog. From the results you should see JBoss Tools (Indigo) and have install button on the right bottom corner. Click it. After some dependency calculation and downloading Eclipse will present you a list of plug-in options. Deselect everything except ‘JBossAS Tools’.

Click next to install the selected plug-in. After installation Eclipse will prompt you with restart. Do it.

Now that you have JBoss integration plug-in installed, you can configure new server runtime. From Eclipse’s Window menu item select preferences. Dialog will open. You can type ‘runtime’ to the search box and select the runtime environment item from the list under the Server item. There you should have an empty list of server runtimes.

Click add button.

From the JBoss Community folder select JBoss 7.1 Runtime.

You will not see this item if you have not installed the JBossAS Tools in the previous step.

New Server Runtime Environment dialog will open. Click on the Browse button on the Home Directory and select the folder where you extracted the JBoss. Make sure that JRE option points to JDK, not JRE. If you don’t have JDK in the dropdown list, click on the JRE button and add JDK to the list of installed JRE’s. Then select it from the JRE dropdown.

After selecting JDK as your JRE click Finish.

JBoss 7.1 Runtime will appear to the list of server runtimes.

From Eclipses Window menu item, select “Show View -> Other. From the dialog select Servers item under the Server folder. Servers view will open to your Eclipse perspective. If the view is empty, right click it and select New -> Server. From ‘Define a New Server’ dialog select JBoss AS 7.1. Make sure that the Server runtime environment dropdown has the Runtime you configured in the previous step. If you did not configure the runtime, you can click the Add… link to open the runtime dialog.

Now you’re done with attaching JBoss to your Eclipse installation. It’s now possible to start the JBoss Application Server from the Eclipse and it will run the JBoss that you downloaded and extracted during the first steps.

As we’re building enterprise web application with Vaadin UI, it’s good idea to install the Vaadin plug-in to your Eclipse just as you did with JBoss plug-in. From the Eclipse Marketplace type ‘vaadin’ as search parameter. You should see Vaadin Plug-in for Eclipse.

Click Install button on the right corner just as you did with the JBoss plug-in. After installation completes, restart Eclipse once more.

Setting up the Enterprise project #

Enterprise Application Project consists of several sub modules such as EJB module, Vaadin UI Web Project module, Common Utility Project module and Enterprise Application EAR project. From these four projects the EAR project is the main project for application server deployment. You’ll deploy only the EAR project and have it manage the other projects. It’s important that all the modules are deployed within the EAR project; otherwise class loading issues will occur during runtime.

We’re going to create four separate Eclipse projects to your Eclipse workspace. First let’s create the simplest Utility Project. The purpose of the utility project is to have classes that are required by both, the UI and the backend. These classes are for example the entities of the system as well as some general helper and support classes.

Utility project #

From you workspace navigator or project explorer or whatever you have in your Eclipse perspective, Right click it and select New -> Other. A Dialog will open. From the Select a Wizard dialog type in to the filter text ‘utility’ and select Utility Project under the Java EE folder.

In the New Utility Module dialog name the project as ‘common’. Select JBoss 7.1 as Target runtime. Select Default configuration. At this point discard the EAR membership selections and press Finish.

New empty Utility project called ‘common’ will appear in your workspace.

EJB project #

As with the Utility Project, right click the workspace view and select New -> Other. To the search box type ‘ejb’ and from the EJB folder select EJB Project.

Name the project as ‘backend’. Select JBoss 7.1 Runtime as Target runtime and Default configuration. Discard the EAR membership and click Finish.

New empty EJB project will appear in your workspace.

Vaadin project #

Now that you have the Utility and EJB projects created, create new Vaadin project. Click the workspace again with right mouse button and select New -> Other and type ‘vaadin’ to the search box. From the Vaadin folder select Vaadin Project.

You will not see this option if you have not installed the Vaadin Eclipse Plug-in in the setting up the development environment chapter.

Click Next.

Name your Vaadin project as ‘ui’. Set target runtime to JBoss 7.1 and for the configuration select Vaadin, Java 6, Servlet 3.0. From the deployment configuration select Servlet (default) and from the Vaadin version dropdown select latest version. If version dropdown is empty, click Download button to get the latest version. Vaadin Eclipse plug-in will setup all the required Vaadin libraries and configuration for you.

Click next.

Accept default source and output folder by clicking Next in the following dialog page.

In Web Module configuration dialog, make sure that ‘Generate web.xml deployment descriptor’ is NOT checked, accept otherwise the default configuration and click Next.

In Vaadin project dialog uncheck the ‘Create project template’ and make sure that Portlet version is set to ‘no portlet’ and Vaadin version is the latest one that you selected.

Click Finish.

New empty Vaadin project is created to your workspace.

JBoss 7 class loading issue #

As we’re using JBoss 7 there is a class loader issue when using Vaadin because JBoss tries to load classes related to the Vaadin client side implementation that you don’t directly need but which are related to compiling the widget set. JBoss’ class loader will end up throwing class not found exception unless you copy gwt-user.jar to your Vaadin projects WebContent/WEB-INF/lib/ folder. You can get the gwt-user.jar from eclipse/configuration/com.vaadin.integration.eclipse/download/gwt-user/2.3.0/ folder where Vaadin Eclipse plug-in downloaded it or you can download the GWT package version 2.3.0 and extract the gwt-user.jar from it. This step is not necessary if you’re using GlassFish application server or if you’re using Vaadin version 7 which at this point is still in alpha phase. This issue is not directly related to Vaadin but instead to the way the JBoss class loading mechanism handles the class references. For the enterprise application project this is all unnecessary information and all you need to know in order to get the project set up correctly is to copy the gwt-user.jar to web project’s WEB-INF/lib/ folder mentioned above.

Enterprise Application Project (EAR) #

After creating all the enterprise application modules, create the Enterprise Application Project that will bundle together all the modules. To do this, once more right click the workspace and select New -> Other. From the dialog search ‘enterprise’ and from Java EE folder, select Enterprise Application Project.

Name your project as ‘ear’, select target runtime as JBoss 7.1 and EAR version as 6.0. Use default configuration.

Click next.

From the following dialog select all three projects you created in the previous steps as Java EE Module dependencies for the EAR project. This means that EAR will contain all the project and when it’s deployed also the contained projects will be deployed to the Application Server.

You can also check the ‘Generate application.xml deployment descriptor’ to have the xml file that manages the ear content. This is not necessary but might be helpful in some situations.

Click Finish.

New Enterprise application project is created with references to module projects.

Project hierarchy in Eclipse #

At this point you should have four separate projects in your Eclipse Workspace: EJB Project called backend, Utility Project called common, Vaadin Project called ui and Enterprise Application Project called ear. You should have copied the gwt-user.jar to your Vaadin Project’s WEB-INF/lib/ folder and you should have application.xml file in your Enterprise Application Project’s META-INF/ folder. You should not have web.xml in your Vaadin Projects WEB-INF folder. Project structure should look like the following:

Setting up the project dependencies #

As we’re building layered enterprise application we want to have dependencies between the projects. It’s important to understand the direction of dependencies. Just as the users use the software from the UI, we want to have similar dependency structure from UI layer to backend and not the other way around.

Right click your Vaadin UI project and from the properties select ‘Java Build Path’. Add backend and common projects to the Projects tab in the build path window. This means that UI project depends on Common and Backend Projects.

Click ok.

Next open the same project dependency dialog for the Backend Project. As we never call UI from the backend, add just the common project as backend’s dependency. Don’t attempt to create circular dependencies. Eclipse will warn you about this if you do.

Setting up the Context and Dependency Injection (CDI) for Vaadin Project #

At this point we’re going to insert utility library that handles Context and Dependency Injection mechanism for the Vaadin project. CDI is used by the Application Server to inject references to backend functionality to the Vaadin application.

Start by downloading CDI Utils Add-on by Tomi Virkki from the Vaadin Directory at: Directory

From the Directory you’ll get .jar package that contains CDI utility that makes it much easier to enable CDI in your Vaadin Application. Copy the jar file you downloaded to Vaadin Projects WEB-INF/lib/ folder, right next to the vaadin.jar package.

To tell your Application Container that we want to use its CDI mechanism, we’ll have to enable it manually. To do this insert EMPTY 0 byte in size file called ‘beans.xml’ to Vaadin projects WEB-INF/ folder.

After adding the CDI related files, your project structure should look like as in above picture.

Implementing basic CDI enabled Vaadin Application #

After configuring the Vaadin project with proper CDI related files and libraries in the previous step we can write our first classes which will be the foundation of our UI. First we’ll create CDI aware application servlet class. As we’re using Servlet 3.0 API creating this class will be really easy.

To your ui projects source folder, create new class called UIApplication and extend it from AbstractCdiApplication. Put the class to some reasonable package like: for example.


import org.vaadin.virkki.cdiutils.application.AbstractCdiApplication;
import com.vaadin.ui.Window;

public class UIApplication extends AbstractCdiApplication {

	public void init() {
		Window window = new Window("Vaadin Application");

To your ui projects source folder and to the same package in which you created the UIApplication class, create new class called UIApplicationServlet and extend it from AbstractCdiApplicationServlet.

Leave the class empty but annotate it with two annotations @WebServlet(urlPatterns =”/*”) and @ApplicationClass(UIApplication.class).


import javax.servlet.annotation.WebServlet;
import org.vaadin.virkki.cdiutils.application.AbstractCdiApplicationServlet;
import org.vaadin.virkki.cdiutils.application.AbstractCdiApplicationServlet.ApplicationClass;

@WebServlet(urlPatterns = "/*")
public class UIApplicationServlet extends AbstractCdiApplicationServlet {


The above class will work as ApplicationServlet that is capable of injecting references to application instance with CDI. WebServlet annotation is used to define the URL to which your application responds to. ApplicationClass annotation is used to tell the application servlet which application class it should instantiate.

Deploying the project to JBoss #

Now that you have the development environment and the project structure set up and CDI enabled Vaadin Application stub defined you can test that it’s deployable to the Application Server. To do this first open the servers view in your Eclipse if it’s not open. In the first steps related to setting up the development environment you added the JBoss runtime to Eclipse and added the server instance to Servers view in Eclipse. If Servers view is not visible you can open it from Window -> Show View -> Other. Type ‘servers’ to the dialog’s field. Select Server in Servers folder.

In the servers view you should see your JBoss 7.1 Runtime Server. Right click the server and Select ‘Add and Remove…’ In the Available column you should see your ‘ear’ project. Click the small arrow on the left side of the project icon to open the project hierarchy. Under the ear project you should have the three modules listed you created and added to the EAR in previous steps. If all three modules are in place move the ear project to Configured column with the Add button.

Click Finish.

You have now deployed the multi module enterprise application stub project to the JBoss application server. Try running your JBoss by clicking the green “play” button in the Servers view. As application server starts it automatically deploys the EAR and makes it available for you. If you have disabled automatic deployment, right click the server and from the menu select publish. During deployment process that usually takes couple of seconds for “empty” projects you should see lines like following in the Eclipse log:

JBAS015876: Starting deployment of "ear.ear" 
JBAS015876: Starting deployment of "ui.war" 
JBAS015876: Starting deployment of "backend.jar" 
JBAS018210: Registering web context: /ui 
JBAS018559: Deployed "ear.ear" 

If log indicates no errors you’re good to go and try viewing the UI project with your web browser. Enter


to your web browser. You should see grey color background in your browser with ‘Vaadin Application’ title. This indicates that the deployment has succeeded and Vaadin application is deployed with /ui web context. If you chose different name for you Vaadin project during the project setup the web context name may be different. Use it to access your application. Notice that common.jar will not be directly deployed as EJB and web projects were because it does not contain deployable components but it works just as library for other modules. That’s why it’s not listed in the deployed items logs.

At the moment the web application part is still completely separate from other modules. Only thing that links them together is that they’re all present in the same EAR package. Next we’ll take a look how to create few EJB beans and bind them to Vaadin application with Model View Presenter (MVP) Pattern. To accomplish this we'll be building our implementation on top of the CDI stub we deployed above.

18 Attachments
Average (0 Votes)
- @ApplicationClass(UIApplication.class) doesn't exists
- AbstractCdiApplicationServlet doesn't exists, replaced with CdiApplicationServlet.
-> localhost:8080/ui doesn't work
Summary : ???

Posted on 9/27/12 9:21 AM.

Is there a Part II following? When?

Posted on 10/29/12 7:13 PM.

How does vaadin*.jar get into WEB-INF/lib?

"Create project template" would do the trick using ivy - but this tutorial explicitly mentions to uncheck that feature...

Posted on 6/1/13 8:48 PM.

The referenced cdi-utils (in version 2.1.1) do not contain the imported org.vaadin.virkki.cdiutils.application.AbstractCdiApplicationServlet...

Posted on 6/1/13 8:56 PM.

backend cannot be deployed to glassfish while no bean is defined...

Posted on 6/1/13 9:04 PM.