Creating and Running a Project in 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 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 Eclipse IDE, the Vaadin Plugin, and a development server, as instructed in “Installing the Eclipse IDE and Plugin”.

Creating an Ivy 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 File › New › Project…​.

2. In the New Project window that opens, select Vaadin › Vaadin 7 Project and click Next.

   

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.

   Configuration

   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 “Google App Engine Integration” and “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.

   Create TestBench test

   When enabled, the application stub will include a test case for testing the UI with Vaadin TestBench, as described in “Vaadin TestBench”. Vaadin TestBench API library will be included in ivy.xml as a dependency. Vaadin version 7.3 or later is required to create the stub.

   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 “Portal Integration” for more information on portlets.

   Finally, click Finish to create the project.

Exploring the Project

After the New Project wizard exits, it has done all the work for you: 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 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 Resources › Libraries › ivy.xml virtual folder.

The UI Class

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

Show code

Java

Expand code

package com.example.myproject;
import com.vaadin.ui.UI;
...
@SuppressWarnings("serial")
@Theme("myproject")
public class MyprojectUI extends UI {
    @WebServlet(value = "/*", asyncSupported = true)
    @VaadinServletConfiguration(
            productionMode = false,
            ui = MyprojectUI.class)
    public static class Servlet extends VaadinServlet {
    }
    @Override
    protected void init(VaadinRequest request) {
        final VerticalLayout layout = new VerticalLayout();
        layout.setMargin(true);
        setContent(layout);
        Button button = new Button("Click Me");
        button.addClickListener(new Button.ClickListener() {
            public void buttonClick(ClickEvent event) {
                layout.addComponent(
                    new Label("Thank you for clicking"));
            }
        });
        layout.addComponent(button);
    }
}

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 “Using a web.xml Deployment Descriptor”.

Creating a Maven 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 File › New › Project…​.

2. In the New Project window that opens, select Vaadin › Vaadin 7 Project (Maven) and click Next.

   

3. In the Select a Maven archetype step, you need to select the project type. To create a simple test project, select the Single-module Application Project.

   

4. In the Specify archetype parameters step, you need to give at least the Group Id and the Artifact Id. The default values should be good for the other settings.

   

   Group Id

   Give the project an organization-level identifier, for example, com.example. It is used as a prefix for your Java package names, and hence must be a valid Java package name itself.

   Artifact Id

   Give the project a name, for example, myproject. The artifact ID must be a valid Java sub-package name.

   Version

   Give the project a Maven compatible version number, for example, 1.0-SNAPSHOT. The version number should typically start with two or more integers separated with dots, and should not contain spaces.

   Package

   Give the base package name for the project, for example, com.example.myproject. It is by default generated from the group ID and the artifact ID.

   Properties

   Enter values for archetype-specific properties that control naming of various elements in the created project, such as the UI class name.

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

   Finally, click Finish to create the project.

Exploring the Project

After the New Project wizard exits, it has done all the work for you. A UI class skeleton has been written to the src directory. The project hierarchy shown in the Project Explorer is shown in A New Vaadin Project.

A new Vaadin project

The Vaadin libraries and other dependencies are managed by Maven. Notice that the libraries are not stored under the project folder, even though they are listed in the Java Resources › Libraries › Maven Dependencies virtual folder.

The UI Class

The UI class created by the plug-in contains the following code:

Show code

Java

Expand code

package com.example.myproject;
import com.vaadin.ui.UI;
...
@Theme("mytheme")
public class MyUI extends UI {
    @Override
    protected void init(VaadinRequest vaadinRequest) {
        final VerticalLayout layout = new VerticalLayout();
        final TextField name = new TextField();
        name.setCaption("Type your name here:");
        Button button = new Button("Click Me");
        button.addClickListener( e -> {
            layout.addComponent(new Label("Thanks " + name.getValue()
                    + ", it works!"));
        });
        layout.addComponents(name, button);
        layout.setMargin(true);
        layout.setSpacing(true);
        setContent(layout);
    }
    @WebServlet(urlPatterns = "/*", name = "MyUIServlet", asyncSupported = true)
    @VaadinServletConfiguration(ui = MyUI.class, productionMode = false)
    public static class MyUIServlet extends VaadinServlet {
    }
}

Compiling the Theme

Before running the project for the first time, click the Compile Vaadin Theme button in the toolbar, as shown in Compile Vaadin Theme.

Compile Vaadin Theme

Coding Tips for Eclipse

Code Completion

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

Java Code Completion in Eclipse

Generating Imports

To automatically 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 Importing classes automatically.

Importing classes automatically

For server-side Vaadin development, you should generally 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.

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 New › Server.

   

2. Select Apache › Tomcat 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/.

   

Running and Debugging

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

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.

Debugging a Vaadin Application

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

Updating the Vaadin Libraries in Maven Projects

Updating the Vaadin plugin does not update Vaadin libraries. The libraries are project specific, as a different version might be required for different projects, so you have to update them separately for each project.

1. Open the pom.xml in an editor in Eclipse.

2. Edit the vaadin.version property to set the Vaadin version.

   Updating the libraries can take several minutes. You can see the progress in the Eclipse status bar. You can get more details about the progress by clicking the indicator.

3. In Vaadin 7.6 and older: if you have compiled the widget set for your project, recompile it by clicking the Compile Vaadin Widgetset button in the Eclipse toolbar.

   

4. Stop the integrated Tomcat (or other server) in Eclipse, clear its caches by right-clicking the server and selecting Clean as well as Clean Tomcat Work Directory, and restart it.

If you experience problems after updating the libraries, you can try using Maven › Update Project.

Updating the Vaadin Libraries in Ivy Projects

Updating the Vaadin plugin does not update Vaadin libraries. The libraries are project specific, as a different version might be required for different projects, so you have to update them separately for each project.

1. Open the ivy.xml in an editor in Eclipse.

2. Edit the entity definition at the beginning of the file to set the Vaadin version.

   Show code

   Expand code

   <!ENTITY vaadin.version "7.x.x">

   You can specify either a fixed version number, as shown in the above example, or a dynamic revision tag such as latest.release. You can find more information about the dependency declarations in Ivy documentation.

3. Right-click the project and select Ivy › Resolve.

   Updating the libraries can take several minutes. You can see the progress in the Eclipse status bar. You can get more details about the progress by clicking the indicator.

4. If you have compiled the widget set for your project, recompile it by clicking the Compile Vaadin Widgetset button in Eclipse toolbar.

   

5. Stop the integrated Tomcat (or other server) in Eclipse, clear its caches by right-clicking the server and selecting Clean as well as Clean Tomcat Work Directory, and restart it.

If you experience problems after updating the libraries, you can try clearing the Ivy resolution caches by right-clicking the project and selecting Ivy › Clean all caches. Then, do the Ivy › Resolve and other tasks again.