Book of Vaadin - vaadin.com

2.4. Your First Project with Vaadin
Prev	Chapter 2. Getting Started with Vaadin	Next

2.4. Your First Project with Vaadin

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

Create a new project
Write the source code
Configure and start Tomcat (or some other web server)
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 and set up your development environment, as instructed in Section 2.1.1, “Installing the Distribution Package” and Section 2.2, “Setting up the Development Environment”.

2.4.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:

Start creating a new project by selecting from the menu File → New → Project....

In the New Project window that opens, select Web → Vaadin Project and click Next.

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

Defines the directory under which the project is created. 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

Defines 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.

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, and
Generic Portlet (Portlet 2.0).
Old Portlet (Portlet 1.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.9, “Google App Engine Integration” and Section 11.8, “Portal Integration” for details on 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. If you want to use another version, click Download. The dialog that opens lists all official releases of Vaadin.

If you want to use a pre-release version or a nightly development build, select Show pre-release versions and nightly builds. Select a version and click Ok to download it. It will appear as a choise in the drop-down list.

If you want to change the project to use another version of Vaadin, for example to upgrade to a newer one, you can go to project settings and download and select the other version.

You can click Finish here to use the defaults for the rest of the settings, or click Next.
The settings in the Web Module step define the basic servlet-related 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 server runs in the apps context and the application has myproject context, the URL would be http://example.com/app/url. The wizard will suggest myproject for the context name.

Content Directory

The directory containing all the content to be included in the servlet and served by the web server. The directory is relative to the root directory of the project.

Java Source Directory

The default source directory containing the application sources. The src directory is suggested; another convention common in web applications is to use WebContent/WEB-INF/src, in which case the sources are included in the servlet (but not served in HTTP requests).

Generate deployment descriptor

Should the wizard generate the web.xml deployment descriptor required for running the servlet in the WebContent/WEB-INF directory. Strongly recommended. See Section 4.8.3, “Deployment Descriptor web.xml” for more details.

This will be the sub-path in the URL, for example http://localhost:8080/myproject. The default for the application root will be / (root).

You can just accept the defaults and click Next.
The Vaadin project step page has various Vaadin-specific application settings. If you are trying Vaadin out 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 application class stub.

Application Name

The name of the application appears in the browser window title.

Base package name

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

Application class name

Name of the Vaadin application class.

Create portlet configuration

When this option is selected, the wizard will create the files needed for running the application in a portal. See Section 11.8, “Portal Integration” for more information on portlets.

Finally, click Finish to create the project.
Eclipse may ask to switch to J2EE perspective. A Dynamic Web Project uses an external web server and the J2EE perspective provides tools to control the server and manage application deployment. Click Yes.

2.4.2. Exploring the Project

After the New Project wizard exists, it has done all the work for us: Vaadin libraries are installed in the WebContent/WEB-INF/lib directory, an application class skeleton has been written to src directory, and WebContent/WEB-INF/web.xml already contains a deployment descriptor.

Figure 2.9. A New Dynamic Web Project

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

package com.example.myproject;
import com.vaadin.Application;
import com.vaadin.ui.*;
public class MyprojectApplication extends Application
{
   @Override 
   public void init() {
      Window mainWindow = 
         new Window("Myproject Application");
      Label label = new Label("Hello Vaadin user");
      mainWindow.addComponent(label);
      setMainWindow(mainWindow);
   }
}

Let us add a button to the application to make it a bit more interesting. The resulting init() method could look something like:

public void init() {
   final Window mainWindow = 
      new Window("Myproject Application");
   Label label = new Label("Hello Vaadin user");
   mainWindow.addComponent(label);
   mainWindow.addComponent(
      new Button("What is the time?",
         new Button.ClickListener() {
         public void buttonClick(ClickEvent event) {
            mainWindow.showNotification(
               "The time is " + new Date());
         }
      }));
   setMainWindow(mainWindow);
}

The deployment descriptor WebContent/WEB-INF/web.xml defines Vaadin framework servlet, the application class, and servlet mapping:

Example 2.1. Web.xml Deployment Descriptor for our project

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns="http://java.sun.com/xml/ns/javaee" 
  xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" 
  id="WebApp_ID" version="2.5">
  <display-name>myproject</display-name>
  <context-param>
      <description>Vaadin production mode</description>
      <param-name>productionMode</param-name>
      <param-value>false</param-value>
  </context-param>
  <servlet>
      <servlet-name>Myproject Application</servlet-name>
      <servlet-class>
        com.vaadin.terminal.gwt.server.ApplicationServlet
      </servlet-class>
      <init-param>
      <description>Vaadin application class to start</description>
      <param-name>application</param-name>
      <param-value>
        com.example.myproject.MyprojectApplication
      </param-value>
      </init-param>
  </servlet>
  <servlet-mapping>
      <servlet-name>Myproject Application</servlet-name>
      <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

For a more detailed treatment of the web.xml file, see Section 4.8.3, “Deployment Descriptor web.xml”.

2.4.3. 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.

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.
Select Apache → Tomcat v6.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.
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.
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.
The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/.

2.4.4. 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.

Figure 2.10. 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.11. Debugging a Vaadin Application