Файл: book-of-vaadin.pdf

Getting Started with Vaadin

Figure 2.7. 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”.

2.6. Using Vaadin with Maven

Maven is a commonly used build and dependency management system. The Vaadin core library and all Vaadin add-ons are available through Maven.You can use a Maven with a front-end from Eclipse or NetBeans, or by using the command-line as described in this section.

In addition to regular Maven, you can use any Maven-compatible build or dependency management system, such as Ivy or Gradle. For Gradle, see the Gradle Vaadin Plugin [https://github.com/johndevs/gradle-vaadin-plugin]. Vaadin Plugin for Eclipse uses Ivy for resolving dependencies in Vaadin projects, and it should provide you with the basic Ivy configuration.

2.6.1. Working from Command-Line

You can create a new Maven project with the following command (given in one line):

$ mvn archetype:generate -DarchetypeGroupId=com.vaadin -DarchetypeArtifactId=vaadin-archetype-application

-DarchetypeVersion=7.x.x

-DgroupId=your.company

-DartifactId=project-name -Dversion=1.0 -Dpackaging=war

The parameters are as follows:

archetypeGroupId

The group ID of the archetype is com.vaadin for Vaadin archetypes.

Getting Started with Vaadin

archetypeArtifactId

The archetype ID. Vaadin 7 currently supports only the vaadin-archetype-application.

archetypeVersion

Version of the archetype to use. This should be LATEST for normal Vaadin releases. For prerelease versions it should be the exact version number, such as 7.0.0.beta3.

groupId

A Maven group ID for your project. It is used for the Java package name and should normally be your domain name reversed, such as com.example.myproject. The group ID is also used for the Java source package name of your project, so it should be Java compatible - only alphanumerics and an underscore.

artifactId

Identifier of the artifact, that is, your project. The identifier may contain alphanumerics, minus, and underscore.

version

Initial version number of your application. The number must obey the Maven version numbering format.

packaging

How will the project be packaged. It is normally war.

Creating a project can take a while as Maven fetches all the dependencies. The created project structure is shown in Figure 2.8, “A New Vaadin Project with Maven”.

Figure 2.8. A New Vaadin Project with Maven

2.6.2. Compiling and Running the Application

Before the application can be deployed, it must be compiled and packaged as a WAR package. You can do this with the package goal as follows:

$ mvn package

The location of the resulting WAR package should be displayed in the command output.You can then deploy it to your favorite application server.

Getting Started with Vaadin

The easiest way to run Vaadin applications with Maven is to use the light-weight Jetty web server. After compiling the package, all you need to do is type:

$ mvn jetty:run

The special goal starts the Jetty server in port 8080 and deploys the application. You can then open it in a web browser at http://localhost:8080/project-name.

2.6.3. Using Add-ons and Custom Widget Sets

If you use Vaadin add-ons that include a widget set or make your custom widgets, you need to enable widget set compilation in the POM.The required configuration is described in Section 17.4, “Using Add-ons in a Maven Project”.

2.7. Creating a Project with NetBeans IDE

You have two choices to create a Vaadin project in NetBeans: as a regular web application project or as a Maven project. We cover these both ways in the following sections.

2.7.1. Maven Project from a Vaadin Archetype

Creating a Maven project with a Vaadin archetype is simpler than a normal web application project in NetBeans. It creates an application skeleton, defines the web.xml deployment descriptor, and also retrieves the latest Vaadin library automatically.

1. Select File New Project.

2. Select Maven Project from Archetype and click Next.

3.Find vaadin-archetype-application, select it, and click Next.

4.In the Name and Location step, enter Project Name, which is recommended to be only lower-case alphabetics, as it is used also as a suggestion for the Java package name of the project. Modify the other parameters for your project and click Finish.

Figure 2.9. Adding a New Maven Project in NetBeans

Creating the project can take a while as Maven loads all the needed dependencies. Once created, you can run it by right-clicking on the project in the Projects view and selecting Run. In the Select

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.