This first chapter serves as the foundations for a journey full of interesting technologies, thrilling challenges, and useful code. If you are reading this book, the chances that you have coded a Vaadin application before are high. You probably have a basic understanding of the key players in a Vaadin application: components, layouts, listeners, binders, resources, themes, and widget sets; and you, of course, have had your share of Java coding!

Having a solid base when starting a project, not only with Vaadin but with any other technology, plays an important role in successful projects. Understanding what your code does and why it is required helps you make better decisions and become more productive. This chapter will help you understand what is really needed to run a Vaadin application and how you can become more confident about the dependencies and Maven configuration required to start a new Vaadin project.

This chapter covers the following topics:

• The main Java dependencies in Vaadin
• Servlets and UIs
• Maven plugins
• Key elements in a Vaadin application

You will be required to have Java SE Development Kit and Java EE SDK version 8 or later. You also need Maven version 3 or later. A Java IDE with Maven support, such as IntelliJ IDEA, Eclipse, or NetBeans is recommended. Finally, to use the Git repository of this book, you need to install Git.

The code files of this chapter can be found on GitHub:
https://github.com/PacktPublishing/Data-centric-Applications-with-Vaadin-8/tree/master/chapter-01

Check out the following video to see the code in action:
https://goo.gl/RHavBs

This book offers value in two ways: the book itself with its explanations, and its companion source code. Instead of developing one single application throughout the book, several small demo applications demonstrate the concepts explained in each chapter. This helps you to jump to any chapter you are interested in, and fully understand the purpose of each part of the code without worrying about the technicalities that we have looked at in other chapters.

Before you compile the project, you have to start an H2 database instance. For your convenience, a server is configured in the Data-centric-Applications-with-Vaadin-8/chapter-05 Maven module. You can create a run configuration for the following Maven command or you can run it directly on the command line:

cd Data-centric-Applications-with-Vaadin-8/chapter-05
mvn test exec:java -Dexec.mainClass="packt.vaadin.datacentric.chapter05.jdbc.H2Server"

Once the database is up and running, you can build all the demo applications by executing the following:

cd Data-centric-Applications-with-Vaadin-8
mvn install

All the demo applications are aggregated in a multi-module Maven project, where each module corresponds to one chapter of the book.

Each chapter's module may contain multiple sub-modules depending on the concepts being explained in that chapter. We will use the Jetty Maven plugin to run the examples. Most IDEs today have good support for Maven. The best way to use this book's code is by importing the Data-centric-Applications-with-Vaadin-8 Maven project into your IDE and creating individual running configurations for each demo application. There are tons of resources online that explain how to do this for the most popular IDEs, such as IntelliJ IDEA, NetBeans, and Eclipse. For example, to run the example application for this chapter in IntelliJ IDEA, create a new running configuration like the following:

Make sure the working directory corresponds to the correct module in the project. Alternatively, you can run the application by executing the following on the command line:

cd Data-centric-Applications-with-Vaadin-8/chapter-01
mvn package jetty:run

This executes the package Maven phase and starts a Jetty server. The application should be available at http://localhost:8080.

So, go ahead! Download the source code, import it into your IDE, and run a couple of examples. Feel free to explore the code, modify it, and even use it in your own projects.

What's the best way of starting a new Vaadin project? It’s hard to say. It depends on your previous experience, current development environment setup, and your own preferences. One of the most popular ways of creating a new Vaadin project is by using one of the official Maven archetypes. You have probably used the vaadin-archetype-application Maven archetype, which is good to quickly get started with Vaadin. Maybe you have used the vaadin-archetype-widgetset archetype to create a Vaadin add-on, or maybe you have used the vaadin-archetype-application-multimodule or vaadin-archetype-application-example archetypes to bootstrap some of your applications. IDEs such as Eclipse provide tools to create a Vaadin project without even thinking about Maven archetypes.

All of those archetypes and tools are good in the sense that they get you started quickly and show some good practices. However, when you create a project from scratch, you get a better understanding of the whole architecture of the application. Of course, you can use the archetypes if you already feel comfortable enough with every part of the generated pom.xml file. However, building the project from scratch is a good way of truly understanding and controlling the configuration of your Vaadin application.

Usually, you would use the vaadin-archetype-application or vaadin-archetype-application-multimodule Maven archetypes to create a new Vaadin application. There's nothing wrong with using these if the generated code suits your needs. However, these archetypes generate more code than you need, partially because they try to show you how to get started with Vaadin and partially because they are general-purpose starters which are well-suited for most projects. But let's gain full control (and understanding) of the web application by creating a Vaadin project in a very different way—a more fine-grained, controlled way.

A Vaadin application is, at the end of the day, a Java application packaged as a WAR file. You can think of it as a standard web application in which you drop some JARs that allow you to build a web UI using the Java Programming Language instead of HTML and JavaScript. Is it as simple as dropping some JARs into your Java project? Let's find out!

Use the maven-archetype-webapp to generate a simple Java web application by executing the following on the command line:

mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-webapp

Use the following properties when prompted:

• groupId: packt.vaadin.datacentric.chapter01
• artifactId: chapter-01
• version: 1.0-SNAPSHOT
• package: packt.vaadin.datacentric.chapter01

Clean up the pom.xml file to make it look like the following:

<project ...>
    <modelVersion>4.0.0</modelVersion>

    <artifactId>chapter-01</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
</project>

    ...
    <packaging>war</packaging>
    
    <properties>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>
    ...

        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>

At this point, we have a very simple Java project setup that will be packaged as a WAR file. The next natural step is to add the required dependencies or libraries. Vaadin, like many other Java web applications, requires the Servlet API. Add it as follows to the pom.xml file:

    <dependencies>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

Notice that the scope of this dependency is set as provided, which means that a server, or more specifically, a Servlet Container, such as Jetty or Tomcat, will provide the implementation.

Let’s continue by adding the required Vaadin dependencies. First, add the vaadin-bom dependency to your pom.xml file:

     <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.vaadin</groupId>
                <artifactId>vaadin-bom</artifactId>
                <version>8.3.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

A Maven BOM, or bill of materials, frees you from worrying about versions of related dependencies; in this case, the Vaadin dependencies. Let's drop these dependencies next. Add the following to your pom.xml file:

    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-server</artifactId>
    </dependency>
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-client-compiled</artifactId>
    </dependency>
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-themes</artifactId>
    </dependency>

There's no need to explicitly set the version for these thanks to the vaadin-bom dependency. We've just added a server-side API (vaadin-server), a client-side engine or widget set (vaadin-client-compiled), and the Valo theme (vaadin-themes).

At this point, you can compile the project by running the following command inside the chapter-01 directory:

mvn clean install

This will download the dependencies to your local Maven repository if you haven't used Vaadin 8.3.2 before.

A Vaadin application in its simplest form is a Servlet that delegates user interface logic to a UI implementation. The vaadin-server dependency includes the Servlet implementation: the VaadinServlet class. Let’s configure one.

Create a new directory with the name java inside the src/main directory.

Create a new package with the name packt.vaadin.datacentric.chapter01, and add a simple UI implementation inside this package:

public class VaadinUI extends UI {

    @Override
    protected void init(VaadinRequest vaadinRequest) {
        setContent(new Label("Welcome to Data-Centric Applications with Vaadin 8!"));
    }
}

Add a new WebConfig class to encapsulate everything related to web configuration, and define the VaadinServlet as an inner class:

public class WebConfig {

    @WebServlet("/*")
    @VaadinServletConfiguration(
          ui = VaadinUI.class, productionMode = false)
    public static class WebappVaadinServlet extends VaadinServlet {
    }
}

The WebappVaadinServlet class must be public static to allow its instantiation by the Servlet Container. Notice how we are configuring /* as the servlet URL mapping using the @WebServlet annotation. This makes the application available at the root of the deployment path. Notice also how the @VaadinServletConfiguration annotation connects the Servlet to the UI implementation, the VaadinUI class we implemented in the previous step.

You must have used, or at least seen, the Vaadin Maven plugin. It allows you to compile the widget set and theme, among other tasks. When creating a new Vaadin application, though, you don’t have any add-ons, custom client-side components, or themes. This means you don’t need the Vaadin Maven plugin just yet. You can use the default widget set provided by the vaadin-client-compiled dependency.

We can benefit from at least one Maven plugin at this point: the Jetty Maven plugin. Although you can configure most IDEs to use a variety of servers in order to deploy your application during development, the Jetty Maven plugin frees you from further specific configurations, making it simple for developers to choose the tools they prefer. To use the plugin, add the following to the pom.xml file:

<build>
    <plugins>
        <plugin>
            <groupId>org.eclipse.jetty</groupId>
            <artifactId>jetty-maven-plugin</artifactId>
            <version>9.3.7.v20160115</version>
        </plugin>
    </plugins>
</build>

With this in place, you can run the application by creating a new running configuration in your IDE to execute mvn jetty:run. Point your browser to http://localhost:8080 and you should see the application running:

To get a full picture of the main parts of a Vaadin application, let's do a quick review of some of the most important classes you should already be familiar with. In a Vaadin application, most of the code deals with components and layouts. In a nutshell, you add components such as Label, TextField, CheckBox, ComboBox, and Grid into layouts such as VerticalLayout, FormLayout, GridLayout, HorizontalLayout, and CSSLayout. You can also add layouts into layouts.

Vaadin applications interact with the server through listeners and binders. Listeners allow you to handle user interaction, while binders allow you to keep values in input components (such as TextField) and domain objects (for example, a custom User class) in sync.

In a Vaadin application, the behavior is added through listeners. A listener fires an event when the corresponding action happens, usually caused by the interaction of the user with the UI. Two of the most common listeners in Vaadin are ClickListener (for buttons) and ValueChangeListener (for input components). Listeners are usually defined by implementing a functional interface, which allows you to react to an event using a method reference:

protected void init(VaadinRequest vaadinRequest) { 
   Button button = new Button("Click this");
   button.addClickListener(this::buttonClicked);
}
...
private void buttonClicked(Button.ClickEvent event) {
    Notification.show("Thanks for clicking");
}

You can also use a Lambda expression instead:

button.addClickListener(
        event -> Notification.show("Thanks for clicking"));

And to make it more readable and testable, extract the listener logic to a new method, passing only what's needed as parameters (in this case, nothing is needed):

protected void init(VaadinRequest vaadinRequest) { 
   ...
   button.addClickListener(event -> buttonClicked());
}
...
private void buttonClicked() {
    Notification.show("Thanks for clicking");
}

Data binding is typically done through the Binder class. This class allows you to connect the values in one or more fields to Java properties in a domain class. Suppose you have a User class (the domain class) with a password Java String as one of its properties. You can create a TextField and bind its value to the password property as follows:

TextField textField = new TextField(“Email”);
Binder binder = new Binder<User>()
    .forField(textField)
    .bind(User::getPassword, User::setPassword);

This is a powerful and type-safe way of implementing data binding. Imagine that you, at some point during development, decide to rename the password property in the User class to something like pin. You can use the refactoring tools of your IDE to rename the property, and the IDE will rename the getters, setters, and any code calling these two methods. Of course, you'd have to change the caption "Email" to "PIN" yourself, but that would have also been the case with other binding mechanisms.

Binders are also used to add validators and converters. These can be added using Lambda expressions or method references. For example, the following snippet of code checks that a String has exactly 4 characters and converts it into an integer:

binder.withValidator(s -> s.length() == 4, “Must be 4 characters")
      .withConverter(Integer::parseInt, Object::toString);

The Resource interface and its implementations are the connections between Java code and resources such as images, downloadable files, or embedded content. You have probably used a StreamResource to dynamically generate a file that a user can download or a ThemeResource to display an image in your UI.

A theme, in turn, is a set of static resources used to configure the appearance of a Vaadin application. By default, Vaadin applications use the Valo theme, a powerful set of styles that can be configured using variables.

So far, you have been introduced to the most common parts of a Vaadin application. Vaadin is mostly about using an API with Java running on the server side. This Java code defines how the application looks and behaves, but a Vaadin application runs on a browser using HTML 5 and JavaScript. You don't have to write a line of HTML or JavaScript in order to implement a Vaadin application. How is this possible? How does a Java class define the HTML rendered in the browser?

The key to understanding this is the widget set. A widget set is a JavaScript engine running on the client side, which contains all the code required to show components and communicate with the server side. A widget set is generated by compiling a set of Java classes into JavaScript using GWT. These Java classes are provided by the Vaadin Framework and you can add your own if you want to. If you are not using custom client-side components (your own, or those provided by a third-party Vaadin add-on), you can use the already compiled widget set which is included in the vaadin-client-compiled dependency.

This chapter served as an introduction to the architecture of a Vaadin application and its main players. We explained the most important parts of a Vaadin application and how they are connected. We also learned how to create a minimal Vaadin application from scratch by adding every single configuration required by ourselves.

In the next chapter, you will learn how to implement main screens and custom application modules that are discovered and registered with a Vaadin application at runtime.