Setting up your development environment for Vaadin

In this tutorial I’m going to walk through the steps to achieve a nice and productive Eclipse environment with working source lookup, hot-redeployment and I'll also introduce Vaadin Designer. As an example application I’m going to use the Vaadin Maven archetype application-example. In addition to having step by step instructions in a written form, I’ll also demonstrate how to do all the steps with desktop video captures.

Install Eclipse

Let’s start the show by downloading and installing Eclipse. We need to get the Java EE Eclipse distribution as the Vaadin Plugin for Eclipse needs features provided most easily by the Java EE distribution. The Java EE distribution also includes Maven and other useful plugins out of the box.

Navigate to eclipse.org/downloads and either use your platform's installer or download and install one of the archive packages. In the demo video below I’m using the latter method.

Create a project to work with

To have some code and resources to work with, I’m going to create a new project using the vaadin-application-example archetype. Maven archetypes are a great way to create project stubs with configurable properties. After the configuration you’ll end up with a nicely structured project that has all the necessary build & development tools configured for you.

Create a new Maven project using Eclipse’s New -> Project… wizard
Select Maven Project as the project type
Make sure you do not check the Create a simple project checkbox, as that will skip the archetype selection.
On the archetype selection step of the wizard set "vaadin" as the filter.
- If the table shows no results, you probably just need to add the Maven Central archetype catalog to your Eclipse. You can do this from the Configure... button: Click Add Remote Catalog... and set "https://repo1.maven.org/maven2/archetype-catalog.xml" as the Catalog File. For Description you can use "Maven Central". Now the filter should yield results in the table.
Select the vaadin-archetype-application-example artifact from the table and click Next >
Now input the Group Id and Artifact Id you want to use in your project. These are used e.g. when referencing a project from other Maven managed projects. The generated project’s package will also be named based on these ids.
After clicking Finish, Eclipse’s m2e plugin will start downloading the dependencies of the project: Vaadin framework itself & its dependencies.

Run the application-example

Now that we have our project set up and its dependencies loaded, let’s build and run the application on a development server. If you open the archetype’s Readme.md, it will instruct you to run ‘mvn install’ in the root and then run ‘mvn jetty:run’ in the UI-project, so let’s do that using Eclipse’s m2e plugin.

Select Run as -> Maven install from the root project (the one with no "-submodule" postfix). This will package and install all the submodules to your local Maven repository. It’s going to take a while as it’s going to build a customized widget set (Vaadin client-side) for the application.
When the install phase is complete, select the -ui project and use Debug As -> Maven build... to create a run configuration for the development Jetty server.
Use "jetty:run" as the goal and name the run configuration so that you can easily find it from the run configurations in the future. I usually use the goal name as in the name as well, replacing all ":" characters with ";".
Click Debug and wait until the console says something like "Started Jetty Server"
Now you should have an application running at localhost:8080

Make source lookup work with jetty:run

You might notice that when debugging and hitting breakpoints, Eclipse is not able to show you the source code when it’s paused on your breakpoint. This is because of how the debug configuration is created. Eclipse doesn’t know which classes Maven loads on its classpath. To provide Eclipse with this information we can install an Eclipse plugin called Maven Development Tools.

Open Eclipse Marketplace from the Eclipse Help menu
The easiest way to find the Maven Development Tools plugin from the marketplace is to search by its author's name. So enter "Igor Fedorenko" as the filter and click install
Restart Eclipse once the installation is done
If you now go and inspect the previously created Maven run configuration for jetty:run, you should see Dynamic Sources Lookup listed in Launch Extensions
When the launch extension is enabled and you hit your breakpoints, Eclipse is now able to look up the sources for easy navigation.

Disable scanning to deploy changes without JVM restart

When the application-example archetype creates the Jetty goal, it configures it to scan for code changes every 2 seconds and restarts the server whenever changes are detected. This can get quite annoying when making changes that could also be deployed to JVM when running in debug mode: whenever you make a change, the UI will show “Session Expired” and you have to re-navigate to the same place in the UI to see the changes.

Open the pom.xml of the "-ui" project
Change to the xml editor tab and navigate to project -> build -> plugins -> org.eclipse.jetty using the outline view
Comment out the scanIntervalSeconds from the configuration section
Now when you restart the debug configuration, you can make simple changes without losing the UI state

Install DCEVM to hot redeploy more complicated changes

Unfortunately the JVM’s built-in hot redeployment support is quite limited. You cannot e.g introduce new methods to your classes. To make JVM capable of hot redeploying more complicated changes, we can use DCEVM. It is a JVM extension that enables enhanced class redefinition functionality.

Download the Light version of the DCEVM binary from dcevm.github.io. I have found that the version number does not need to match your JVM version exactly.
Run the DCEVM-light-<version>-installer.jar with administrator privileges:
- Linux / OS X: use sudo java -jar DCEVM-light-<version>-installer.jar
- Windows: open a command prompt as Administrator and run java -jar DCEVM-light-<version>-installer.jar
Select your JDK installation directory. If the installer fails to find your installation directory automatically, here are some sample paths:
- Linux: /usr/lib/jvm/java-8-oracle
- OS X: /Library/Java/JavaVirtualMachines/jdk1.8.0_71.jdk/Contents/Home/jre
- Windows: C:\Program Files\Java\jdk1.8.0_71\jre
The easiest way to install is to replace the main JVM by DCEVM. An alternative way is to install as an altvm, but then you need to configure your launch configurations to use the altvm. I recommend to just replace the main JVM.
After the installation, all you need to do is to restart your debug configuration. Now the JVM supports hot redeploying more complex modifications, like new methods.

Vaadin declarative format

In addition to building UIs with plain Java code, Vaadin also supports a declarative, HTML-based format. The declarative format enables developers and graphic designers to create and edit UIs without any coding. In the next video I’m going to edit the product edit form’s declarative HTML.

Editing save and delete button captions
Make the editProduct method to recreate the form on product selection. This is needed for the application to display the latest version of the declaratively created UI
Wrap the save and cancel buttons inside a horizontal layout
Apply some styling to the horizontal layout

Vaadin Designer

One of the main uses for Vaadin’s declarative format is the Vaadin Designer. The declarative HTML-files are used as the native file format in Vaadin Designer. In the next video I’m going to show how to install the Vaadin plug-in for Eclipse and it’s basic usage.

Install Vaadin plug-in from Eclipse Marketplace and restart Eclipse
Revert the changes made to the button layouting
Change to Eclipse’s Vaadin perspective and open the HTML using Vaadin Designer
Wrap the buttons inside a horizontal layout
Remove the availability combo box and add an option group with the same name

That's all for this tutorial. I hope it helped you to get started with Vaadin development or gave you some ideas on how to improve your development environment. If you have any questions, please comment below, or hit me up on Twitter!