Part II. Server-Side Framework

Of the two sides of Vaadin, the server-side code runs in a Java web server as a servlet, or a portlet in a portal. It offers a server-side API with dozens of user interface components for developing user interfaces, and employs a client-side engine to render them in the browser. User interaction is communicated transparently to the server-side application.The user interface can be styled with themes, and bound to data through the Vaadin Data Model.

Chapter 4

Writing a

Server-Side Web

Application

4.1. Overview ..................................................................................................	61
4.2. Building the UI .........................................................................................	64
4.3. Handling Events with Listeners ................................................................	68
4.4. Images and Other Resources ..................................................................	70
4.5. Handling Errors ........................................................................................	74
4.6. Notifications .............................................................................................	76
4.7. Application Lifecycle ................................................................................	79
4.8. Deploying an Application .........................................................................	83

This chapter provides the fundamentals of server-side web application development with Vaadin, concentrating on the basic elements of an application from a practical point-of-view.

4.1. Overview

A server-side Vaadin application runs as a Java Servlet in a servlet container. The Java Servlet API is, however, hidden behind the framework.The user interface of the application is implemented as a UI class, which needs to create and manage the user interface components that make up

Book of Vaadin

61

Writing a Server-Side Web Application

the user interface. User input is handled with event listeners, although it is also possible to bind the user interface components directly to data. The visual style of the application is defined in themes as CSS and SCSS files. Icons, other images, and downloadable files are handled as resources, which can be external or served by the application server or the application itself.

Figure 4.1. Server-Side Application Architecture

Figure 4.1, “Server-Side Application Architecture” illustrates the basic architecture of an application made with the Vaadin Framework, with all the major elements, which are introduced below and discussed in detail in this chapter.

First of all, a Vaadin application must have one or more UI classes that extend the abstract com.vaadin.ui.UI class and implement the init() method. A custom theme can be defined as an annotation for the UI.

@Theme("hellotheme")

public class HelloWorld extends UI {

protected void init(VaadinRequest request) {

... initialization code goes here ...

}

}

A UI is a viewport to a Vaadin application running in a web page. A web page can actually have multiple such UIs within it. Such situation is typical especially with portlets in a portal. An application can run in multiple browser windows, each having a distinct UI instance. The UIs can be the same UI class or different.

62

Overview

Writing a Server-Side Web Application

The UI API may seem similar to Java Servlet API, but that is only superficial. Vaadin framework handles servlet requests internally and associates the requests with user sessions and a UI state. Because of this, you can develop Vaadin applications much like you would develop desktop applications.

The most important task in the initialization is the creation of the initial user interface. This, and the deployment of a UI as a Java Servlet in the Servlet container, as described in Section 4.8, “Deploying an Application”, are the minimal requirements for an application.

Below is a short overview of the other basic elements of an application besides UI:

UI

A UI represents an HTML fragment in which a Vaadin application runs in a web page. It typically fills the entire page, but can also be just a part of a page. You normally develop a Vaadin application by extending the UI class and adding content to it. A UI is essentially a viewport connected to a user session of an application, and you can have many such views, especially in a multi-window application. Normally, when the user opens a new page with the URL of the Vaadin UI, a new UI (and the associated Page object) is automatically created for it. All of them share the same user session.

The current UI object can be accessed globally with UI.getCurrent(). The static method returns the thread-local UI instance for the currently processed request (see Section 11.14.3, “ThreadLocal Pattern”).

Page

A UI is associated with a Page object that represents the web page as well as the browser window in which the UI runs.

The Page object for the currently processed request can be accessed globally from a Vaadin application with Page.getCurrent(). This is equivalent to calling

UI.getCurrent().getPage().

Vaadin Session

A VaadinSession object represents a user session with one or more UIs open in the application. A session starts when a user first opens an UI of a Vaadin application, and closes when the session expires in the server or when it is closed explicitly.

User Interface Components

The user interface consists of components that are created by the application. They are laid out hierarchically using special layout components, with a content root layout at the top of the hierarchy. User interaction with the components causes events related to the component, which the application can handle. Field components are intended for inputting values and can be directly bound to data using the Vaadin Data Model. You can make your own user interface components through either inheritance or composition. For a thorough reference of user interface components, see Chapter 5,

User Interface Components, for layout components, see Chapter 6, Managing Layout, and for compositing components, see Section 5.22, “Component Composition with

CustomComponent”.

Events and Listeners

Vaadin follows an event-driven programming paradigm, in which events, and listeners that handle the events, are the basis of handling user interaction in an application. Section 3.4, “Events and Listeners” gave an introduction to events and listeners from an architectural point-of-view, while Section 4.3, “Handling Events with Listeners” later in this chapter takes a more practical view.

Overview

63