2.5. Creating and Running a Project with Eclipse

This section gives instructions for creating a new Eclipse project using the Vaadin Plugin. The task will include the following steps:

  1. Create a new project

  2. Write the source code

  3. Configure and start Tomcat (or some other web server)

  4. Open a web browser to use the web application

We also show how you can debug the application in the debug mode in Eclipse.

This walkthrough assumes that you have already installed the Vaadin Plugin for Eclipse and set up your development environment, as instructed in Section 2.2, “Setting up the Development Environment”.

2.5.1. Creating the Project

Let us create the first application project with the tools installed in the previous section. First, launch Eclipse and follow the following steps:

  1. Start creating a new project by selecting from the menu FileNewProject....
  2. In the New Project window that opens, select WebVaadin 7 Project and click Next.

    If you choose to go the Vaadin 6 way, please use the latest Vaadin 6 version of this book for further instructions.

  3. In the Vaadin Project step, you need to set the basic web project settings. You need to give at least the project name and the runtime; the default values should be good for the other settings.

    Project name

    Give the project a name. The name should be a valid identifier usable cross-platform as a filename and inside a URL, so using only lower-case alphanumerics, underscore, and minus sign is recommended.

    Use default location

    Define the directory under which the project is created. The default is under your workspace folder, and you should normally leave it as it is. You may need to set the directory, for example, if you are creating an Eclipse project on top of a version-controlled source tree.

    Target runtime

    Define the application server to use for deploying the application. The server that you have installed, for example Apache Tomcat, should be selected automatically. If not, click New to configure a new server under Eclipse.


    Select the configuration to use; you should normally use the default configuration for the application server. If you need to modify the project facets, click Modify. The recommended Servlet 3.0 configuration uses the @WebServlet deployment, while Servlet 2.4 uses the old web.xml deployment.

    Deployment configuration

    This setting defines the environment to which the application will be deployed, to generate the appropriate project directory layout and configuration files. The choises are:

    • Servlet (default)
    • Google App Engine Servlet
    • Generic Portlet (Portlet 2.0)

    The further steps in the New Project Wizard depend on the selected deployment configuration; the steps listed in this section are for the default servlet configuration. See Section 11.7, “Google App Engine Integration” and Chapter 12, Portal Integration for instructions regarding the use of Vaadin in the alternative environments.

    Vaadin version

    Select the Vaadin version to use. The drop-down list shows, by default, the latest available version of Vaadin. The selection includes nightly SNAPSHOT builds, if you want to keep up with the absolutely latest unstable versions.

    You can change the version later in the ivy.xml.

    You can click Finish here to use the defaults for the rest of the settings, or click Next.

  4. The settings in the Web Module step define the basic web application (WAR) deployment settings and the structure of the web application project. All the settings are pre-filled, and you should normally accept them as they are.

    Context Root

    The context root (of the application) identifies the application in the URL used for accessing it. For example, if the project has a myproject context and a single UI at the context root, the URL would be http://example.com/myproject. The wizard will suggest the project name given in the first step as the context name. You can change the context root later in the Eclipse project properties.

    Content Directory

    The directory containing all the content to be included in the web application (WAR) that is deployed to the web server. The directory is relative to the root directory of the project.

    You can just accept the defaults and click Next.

  5. The Vaadin project step page has various Vaadin-specific application settings. If you are trying out Vaadin for the first time, you should not need to change anything. You can set most of the settings afterwards, except the creation of the portlet configuration.

    Create project template

    Make the wizard create an UI class stub.

    Application Name

    A name for the application UI, shown in the title bar of the browser window.

    Base package name

    The name of the Java package under which the UI class of the application is to be placed.

    Application/UI class name

    The name of the UI class for the application, in which the user interface is developed.

    Portlet version

    When a portlet version is selected (only Portlet 2.0 is supported), the wizard will create the files needed for running the application in a portal. See Chapter 12, Portal Integration for more information on portlets.

    Finally, click Finish to create the project.

2.5.2. Exploring the Project

After the New Project wizard exists, it has done all the work for us: an UI class skeleton has been written to src directory and the WebContent/WEB-INF/web.xml contains a deployment descriptor. The project hierarchy shown in the Project Explorer is shown in Figure 2.3, “A New Vaadin Project”.

Figure 2.3. A New Vaadin Project

A New Vaadin Project

The Vaadin libraries and other dependencies are managed by Ivy. Notice that the libraries are not stored under the project folder, even though they are listed in the Java ResourcesLibrariesivy.xml virtual folder.

The UI Class

The UI class created by the plugin contains the following code:

package com.example.myproject;

import com.vaadin.ui.UI;

public class MyprojectUI extends UI {

    @WebServlet(value = "/*", asyncSupported = true)
            productionMode = false,
            ui = MyprojectUI.class)
    public static class Servlet extends VaadinServlet {

    protected void init(VaadinRequest request) {
        final VerticalLayout layout = new VerticalLayout();

        Button button = new Button("Click Me");
        button.addClickListener(new Button.ClickListener() {
            public void buttonClick(ClickEvent event) {
                    new Label("Thank you for clicking"));

In a Servlet 3.0 project, the deployment is configured with servlet class and a @WebServlet annotation. The stub includes the servlet class as a static inner class. You may want to refactor it to a separate normal class.

In a Servlet 2.3 project, you would have a web.xml deployment descriptor.

For a more detailed treatment of the deployment, see Section 4.8.4, “Using a web.xml Deployment Descriptor”.

2.5.3. Coding Tips for Eclipse

One of the most useful features in Eclipse is code completion. Pressing Ctrl+Space in the editor will display a popup list of possible class name and method name completions, as shown in Figure 2.4, “Java Code Completion in Eclipse”, depending on the context of the cursor position.

Figure 2.4. Java Code Completion in Eclipse

Java Code Completion in Eclipse

To add an import statement for a class, such as Button, simply press Ctrl+Shift+O or click the red error indicator on the left side of the editor window. If the class is available in multiple packages, a list of the alternatives is displayed, as shown in Figure 2.5, “Importing Classes Automatically”. For server-side development, you should normally use the classes under the com.vaadin.ui or com.vaadin.server packages. You can not use client-side classes (under com.vaadin.client) or GWT classes for server-side development.

Figure 2.5. Importing Classes Automatically

Importing Classes Automatically

2.5.4. Setting Up and Starting the Web Server

Eclipse IDE for Java EE Developers has the Web Standard Tools package installed, which supports control of various web servers and automatic deployment of web content to the server when changes are made to a project.

Make sure that Tomcat was installed with user permissions. Configuration of the web server in Eclipse will fail if the user does not have write permissions to the configuration and deployment directories under the Tomcat installation directory.

Follow the following steps.

  1. Switch to the Servers tab in the lower panel in Eclipse. List of servers should be empty after Eclipse is installed. Right-click on the empty area in the panel and select NewServer.
  2. Select ApacheTomcat v7.0 Server and set Server's host name as localhost, which should be the default. If you have only one Tomcat installed, Server runtime has only one choice. Click Next.
  3. Add your project to the server by selecting it on the left and clicking Add to add it to the configured projects on the right. Click Finish.
  4. The server and the project are now installed in Eclipse and are shown in the Servers tab. To start the server, right-click on the server and select Debug. To start the server in non-debug mode, select Start.
  5. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/.

2.5.5. Running and Debugging

Starting your application is as easy as selecting myproject from the Project Explorer and then RunDebug AsDebug on Server. Eclipse then opens the application in built-in web browser.

Figure 2.6. Running a Vaadin Application

Running a Vaadin Application

You can insert break points in the Java code by double-clicking on the left margin bar of the source code window. For example, if you insert a breakpoint in the buttonClick() method and click the What is the time? button, Eclipse will ask to switch to the Debug perspective. Debug perspective will show where the execution stopped at the breakpoint. You can examine and change the state of the application. To continue execution, select Resume from Run menu.

Figure 2.7. Debugging a Vaadin Application

Debugging a Vaadin Application

Above, we described how to debug a server-side application. Debugging client-side applications and widgets is described in Section 13.6, “Debugging Client-Side Code”.

I. Introduction
1. Introduction
1.1. Overview
1.2. Example Application Walkthrough
1.3. Support for the Eclipse IDE
1.4. Goals and Philosophy
1.5. Background
2. Getting Started with Vaadin
2.1. Overview
2.2. Setting up the Development Environment
2.3. Overview of Vaadin Libraries
2.4. Installing Vaadin Plugin for Eclipse
2.5. Creating and Running a Project with Eclipse
2.6. Using Vaadin with Maven
2.7. Creating a Project with NetBeans IDE
2.8. Creating a Project with IntelliJ IDEA
2.9. Vaadin Installation Package
2.10. Using Vaadin with Scala
3. Architecture
3.1. Overview
3.2. Technological Background
3.3. Client-Side Engine
3.4. Events and Listeners
II. Server-Side Framework
4. Writing a Server-Side Web Application
4.1. Overview
4.2. Building the UI
4.3. Handling Events with Listeners
4.4. Images and Other Resources
4.5. Handling Errors
4.6. Notifications
4.7. Application Lifecycle
4.8. Deploying an Application
5. User Interface Components
5.1. Overview
5.2. Interfaces and Abstractions
5.3. Common Component Features
5.4. Field Components
5.5. Component Extensions
5.6. Label
5.7. Link
5.8. TextField
5.9. TextArea
5.10. PasswordField
5.11. RichTextArea
5.12. Date and Time Input with DateField
5.13. Button
5.14. CheckBox
5.15. Selecting Items
5.16. Table
5.17. Tree
5.18. MenuBar
5.19. Embedded Resources
5.20. Upload
5.21. ProgressBar
5.22. Slider
5.23. Calendar
5.24. Component Composition with CustomComponent
5.25. Composite Fields with CustomField
6. Managing Layout
6.1. Overview
6.2. UI, Window, and Panel Content
6.3. VerticalLayout and HorizontalLayout
6.4. GridLayout
6.5. FormLayout
6.6. Panel
6.7. Sub-Windows
6.8. HorizontalSplitPanel and VerticalSplitPanel
6.9. TabSheet
6.10. Accordion
6.11. AbsoluteLayout
6.12. CssLayout
6.13. Layout Formatting
6.14. Custom Layouts
7. Visual User Interface Design with Eclipse
7.1. Overview
7.2. Creating a New Composite
7.3. Using The Visual Editor
7.4. Structure of a Visually Editable Component
8. Themes
8.1. Overview
8.2. Introduction to Cascading Style Sheets
8.3. Syntactically Awesome Stylesheets (Sass)
8.4. Creating and Using Themes
8.5. Creating a Theme in Eclipse
8.6. Responsive Themes
9. Binding Components to Data
9.1. Overview
9.2. Properties
9.3. Holding properties in Items
9.4. Creating Forms by Binding Fields to Items
9.5. Collecting Items in Containers
10. Vaadin SQLContainer
10.1. Architecture
10.2. Getting Started with SQLContainer
10.3. Filtering and Sorting
10.4. Editing
10.5. Caching, Paging and Refreshing
10.6. Referencing Another SQLContainer
10.7. Using FreeformQuery and FreeformStatementDelegate
10.8. Non-implemented methods of Vaadin container interfaces
10.9. Known Issues and Limitations
11. Advanced Web Application Topics
11.1. Handling Browser Windows
11.2. Embedding UIs in Web Pages
11.3. Debug Mode and Window
11.4. Request Handlers
11.5. Shortcut Keys
11.6. Printing
11.7. Google App Engine Integration
11.8. Common Security Issues
11.9. Navigating in an Application
11.10. Advanced Application Architectures
11.11. Managing URI Fragments
11.12. Drag and Drop
11.13. Logging
11.14. JavaScript Interaction
11.15. Accessing Session-Global Data
11.16. Server Push
12. Portal Integration
12.1. Overview
12.2. Creating a Portlet Project in Eclipse
12.3. Portlet UI
12.4. Deploying to a Portal
12.5. Installing Vaadin in Liferay
12.6. Handling Portlet Requests
12.7. Handling Portlet Mode Changes
12.8. Non-Vaadin Portlet Modes
12.9. Vaadin IPC for Liferay
III. Client-Side Framework
13. Client-Side Vaadin Development
13.1. Overview
13.2. Installing the Client-Side Development Environment
13.3. Client-Side Module Descriptor
13.4. Compiling a Client-Side Module
13.5. Creating a Custom Widget
13.6. Debugging Client-Side Code
14. Client-Side Applications
14.1. Overview
14.2. Client-Side Module Entry-Point
14.3. Compiling and Running a Client-Side Application
14.4. Loading a Client-Side Application
15. Client-Side Widgets
15.1. Overview
15.2. GWT Widgets
15.3. Vaadin Widgets
16. Integrating with the Server-Side
16.1. Overview
16.2. Starting It Simple With Eclipse
16.3. Creating a Server-Side Component
16.4. Integrating the Two Sides with a Connector
16.5. Shared State
16.6. RPC Calls Between Client- and Server-Side
16.7. Component and UI Extensions
16.8. Styling a Widget
16.9. Component Containers
16.10. Creating Add-ons
16.11. Migrating from Vaadin 6
16.12. Integrating JavaScript Components and Extensions
IV. Vaadin Add-ons
17. Using Vaadin Add-ons
17.1. Overview
17.2. Downloading Add-ons from Vaadin Directory
17.3. Installing Add-ons in Eclipse with Ivy
17.4. Using Add-ons in a Maven Project
17.5. Troubleshooting
18. Vaadin Charts
18.1. Overview
18.2. Installing Vaadin Charts
18.3. Basic Use
18.4. Chart Types
18.5. Chart Configuration
18.6. Chart Data
18.7. Advanced Uses
18.8. Timeline
19. Vaadin JPAContainer
19.1. Overview
19.2. Installing
19.3. Defining a Domain Model
19.4. Basic Use of JPAContainer
19.5. Entity Providers
19.6. Filtering JPAContainer
19.7. Querying with the Criteria API
19.8. Automatic Form Generation
19.9. Using JPAContainer with Hibernate
20. Mobile Applications with TouchKit
20.1. Overview
20.2. Considerations Regarding Mobile Browsing
20.3. Installing Vaadin TouchKit
20.4. Importing the Vornitologist Demo
20.5. Creating a New TouchKit Project
20.6. Elements of a TouchKit Application
20.7. Mobile User Interface Components
20.8. Advanced Mobile Features
20.9. Offline Mode
20.10. Building an Optimized Widget Set
20.11. Testing and Debugging on Mobile Devices
21. Vaadin TestBench
21.1. Overview
21.2. Installing Vaadin TestBench
21.3. Preparing an Application for Testing
21.4. Using Vaadin TestBench Recorder
21.5. Developing JUnit Tests
21.6. Taking and Comparing Screenshots
21.7. Running Tests in a Distributed Environment
21.8. Headless Testing
21.9. Known Issues
A. Songs of Vaadin