Getting Started with Vaadin

deployment server window that opens, select Glassfish or Apache Tomcat, and click OK. If all goes well, NetBeans starts the server in port 8080 and, depending on your system configuration, launches the default browser to display the web application. If not, you can open it manually, for example, at http://localhost:8080/myproject. The project name is used by default as the context path of the application.

2.7.2. Regular Web Application Project

This section describes the basic way of creating a Vaadin application project in NetBeans. This approach is useful if you do not wish to use Maven, but requires more manual work.

1. Open File New Project.

2. Select Java Web Web Application and click Next.

3.Give a project name, such as myproject. As the project name is by default also used as the context path, it should only contain alphanumerics, underscore and minus sign. Click Next.

4.Select a server.The reference toolchain recommends Apache Tomcat, as many instructions in this book are given specifically for Tomcat, but any other server should work just as fine. Click Next.

5.Click Finish.

The project is created. However, it is a simple skeleton for a JSP-based web application project. To make it a proper Vaadin project, you need to include the Vaadin libraries in the WEB-INF/lib folder, create the application class, and define the web.xml deployment descriptor.

2.8. Vaadin Installation Package

While the recommended way to install Vaadin is to use the Eclipse plugin, one of the other IDE plugins, or a dependency management system, such as Maven, Vaadin is also available as a ZIP distribution package.

You can download the newest Vaadin installation package from the download page at http://vaadin.com/download/. Please use a ZIP decompression utility available in your operating system to extract the files from the ZIP package.

2.8.1. Package Contents

README.TXT

This Readme file gives simple instructions for installing Vaadin in your project.

release-notes.html

The Release Notes contain information about the new features in the particular release, give upgrade instructions, describe compatibility, etc. Please open the HTML file with a web browser.

license.html

Apache License version 2.0. Please open the HTML file with a web browser.

lib folder

All dependency libraries required by Vaadin are contained within the lib folder.

Getting Started with Vaadin

*.jar

Vaadin libraries, as described in Section 2.3, “Overview of Vaadin Libraries”.

2.8.2. Installing the Libraries

You can install the Vaadin ZIP package in a few simple steps:

1.Copy the JAR files at the package root folder to the WEB-APP/lib web library folder in the project. Some of the libraries are optional, as explained in Section 2.3, “Overview of Vaadin Libraries”.

2.Also copy the dependency JAR files at the lib folder to the WEB-APP/lib web library folder in the project.

The location of the WEB-APP/lib folder depends on the project organization, which depends on the development environment.

•In Eclipse Dynamic Web Application projects: WebContent/WEB-INF/lib.

•In Maven projects: src/main/webapp/WEB-INF/lib.

Chapter 3

Architecture

In Chapter 1, Introduction, we gave a short introduction to the general architecture of Vaadin. This chapter looks deeper into the architecture at a more technical level.

3.1. Overview

Vaadin provides two development models for web applications: for the client-side (the browser) and for the server-side. The server-driven development model is the more powerful one, allowing application development solely on the server-side, by utilizing an AJAX-based Vaadin Client-Side Engine that renders the user interface in the browser. The client-side model allows developing widgets and applications in Java, which are compiled to JavaScript and executed in the browser. The two models can share their UI widgets, themes, and back-end code and services, and can be mixed together easily.

Figure 3.1, “Vaadin Runtime Architecture” gives a basic illustration of the client-side and serverside communications, in a running situation where the page with the client-side code (engine or application) has been initially loaded in the browser.

Vaadin Framework consists of a server-side API, a client-side API, a horde of user interface components/widgets on the both sides, themes for controlling the appearance, and a data model that allows binding the server-side components directly to data. For client-side development, it includes the Vaadin Compiler, which allows compiling Java to JavaScript.

Architecture

Figure 3.1. Vaadin Runtime Architecture

A server-side Vaadin application runs as a servlet in a Java web server, serving HTTP requests. The VaadinServlet is normally used as the servlet class. The servlet receives client requests and inteprets them as events for a particular user session. Events are associated with user interface components and delivered to the event listeners defined in the application. If the UI logic makes changes to the server-side user interface components, the servlet renders them in the web browser by generating a response. The client-side engine running in the browser receives the responses and uses them to make any necessary changes to the page in the browser.

The major parts of the server-driven development architecture and their function are as follows:

User Interface

Vaadin applications provide a user interface for the user to interface with the business logic and data of the application. At technical level, the UI is realized as a UI class that extends com.vaadin.ui.UI. Its main task is to create the initial user interface out of UI components and set up event listeners to handle user input.The UI can then be loaded in the browser using an URL, or can be embedded to any HTML page. For detailed information about implementing a UI, see Chapter 4, Writing a Server-Side Web Application.

Please note that the term "UI" is used throughout this book to refer both to the general UI concept as well as the technical UI class concept.

User Interface Components/Widgets

The user interface of a Vaadin application consists of components that are created and laid out by the application. Each server-side component has a client-side counterpart, a "widget", by which it is rendered in the browser and with which the user interacts. The client-side widgets can also be used by client-side applications. The server-side components relay these events to the application logic. Field components that have a value, which the user can view or edit, can be bound to a data source (see below). For a more detailed description of the UI component architecture, see Chapter 5, User Interface Components.

Architecture

Client-Side Engine

The Client-Side Engine of Vaadin manages the rendering of ther UI in the web browser by employing various client-side widgets, counterparts of the server-side components. It communicates user interaction to the server-side, and then again renders the changes in the UI.The communications are made using asynchronous HTTP or HTTPS requests. See Section 3.3, “Client-Side Engine”.

Vaadin Servlet

Server-side Vaadin applications work on top of the Java Servlet API (see Section 3.2.5, “Java Servlets”).The Vaadin servlet, or more exactly the VaadinServlet class, receives requests from different clients, determines which user session they belong to by tracking the sessions with cookies, and delegates the requests to their corresponding sessions. You can customize the Vaadin servlet by extending it.

Themes

Vaadin makes a separation between the appearance and component structure of the user interface. While the UI logic is handled as Java code, the presentation is defined in themes as CSS or Sass. Vaadin provides a number of default themes. User themes can, in addition to style sheets, include HTML templates that define custom layouts and other resources, such as images. Themes are discussed in detail in Chapter 8,

Themes.

Events

Interaction with user interface components creates events, which are first processed on the client-side by the widgets, then passed all the way through the HTTP server, Vaadin servlet, and the user interface components to the event listeners defined in the application. See Section 3.4, “Events and Listeners”.

Data Binding

In addition to the user interface model, Vaadin provides a data model for binding data presented in field components, such as text fields, check boxes and selection components, to a data source. Using the data model, the user interface components can update the application data directly, often without the need for any control code. All the field components in Vaadin use this data model internally, but any of them can be bound to a separate data source as well. For example, you can bind a table component to an SQL query response. For a complete overview of the Vaadin Data Model, please refer to Chapter 9, Binding Components to Data.

Client-Side Applications

In addition to server-side web applications, Vaadin supports client-side application modules, which run in the browser. Client-side modules can use the same widgets, themes, and back-end services as server-side Vaadin applications. They are useful when you have a need for highly responsive UI logic, such as for games or for serving a large number of clients with possibly stateless server-side code, and for various other purposes, such as offering an off-line mode for server-side applications. Please see Chapter 14, Client-Side Applications for further details.

Back-end

Vaadin is meant for building user interfaces, and it is recommended that other application layers should be kept separate from the UI. The business logic can run in the same servlet as the UI code, usually separated at least by a Java API, possibly as EJBs, or distributed to a remote back-end service. The data storage is usually distributed to a database management system, and is typically accessed through a persistence solution, such as JPA.