vaadin-framework/documentation/getting-started/getting-started-first-project.asciidoc

---
title: Creating a Project in Eclipse
order: 100
layout: page
---

[[getting-started.first-project]]
= Creating and Running a Project in Eclipse

TIP: If you are new to Vaadin, we suggest to start with <<dummy/../../../framework/tutorial#tutorial,"the tutorial">>. It also contains instructions how to set up Eclipse based development environment.

This section gives instructions for creating a new Eclipse project using the
Vaadin Plugin. The task will include the following steps:

. Create a new project

. Write the source code

. Configure and start web server

. Open a web browser to use the web application

We also show how you can debug the application in the debug mode in Eclipse.

This walkthrough assumes that you have already installed the Eclipse IDE, the Vaadin Plugin, and a development server, as instructed in
<<dummy/../../../framework/installing/installing-eclipse#installing.eclipse, "Installing the Eclipse IDE and Plugin">>.

[[getting-started.first-project.creation]]
== Creating a Maven Project

Let us create the first application project with the tools installed in the previous section.
First, launch Eclipse and follow the following steps:

. Start creating a new project by selecting from the menu "File > New > Project...".

. In the [guilabel]#New Project# window that opens, select "Vaadin > Vaadin 8
Project (Maven)" and click [guibutton]#Next#.
+
image::img/myproject-new-vaadin.png[width=70%, scaledwidth=90%]

. In the [guilabel]#Select a Maven archetype# step, you need to select the project type.
To create a simple test project, select the [guilabel]#Single-module Application Project#.
+
image::img/myproject-archetype-selection.png[width=70%, scaledwidth=90%]

. In the [guilabel]#Specify archetype parameters# step, you need to give at least the [guilabel]#Group Id# and the [guilabel]#Artifact Id#.
The default values should be good for the other settings.
+
image::img/myproject-settings.png[width=70%, scaledwidth=90%]

[guilabel]#Group Id#::
Give the project an organization-level identifier, for example, [packagename]#com.example#.
It is used as a prefix for your Java package names, and hence must be a valid Java package name itself.

[guilabel]#Artifact Id#:: Give the project a name, for example, `myproject`.
The artifact ID must be a valid Java sub-package name.

[guilabel]#Version#:: Give the project a Maven compatible version number, for example, `1.0-SNAPSHOT`.
The version number should typically start with two or more integers separated with dots, and
should not contain spaces.

[guilabel]#Package#:: Give the base package name for the project, for example,
[packagename]#com.example.myproject#.
It is by default generated from the group ID and the artifact ID.

[guilabel]#Properties#:: Enter values for archetype-specific properties that control naming of various elements in the created project, such as the UI class name.
+
You can change the version later in the [filename]#pom.xml#.
+
Finally, click [guibutton]#Finish# to create the project.

[[getting-started.first-project.exploring]]
== Exploring the Project

After the [guilabel]#New Project# wizard exits, it has done all the work for you.
A UI class skeleton has been written to the [filename]#src# directory.
The project hierarchy shown in the Project Explorer is shown in <<figure.getting-started.first-project.exploring>>.

[[figure.getting-started.first-project.exploring]]
.A new Vaadin project
image::img/myproject-created-annotated-hi.png[width=80%, scaledwidth=100%]

The Vaadin libraries and other dependencies are managed by Maven.
Notice that the libraries are not stored under the project folder, even though they are listed in the "Java Resources > Libraries > Maven Dependencies" virtual folder.

[[getting-started.first-project.exploring.ui]]
=== The UI Class

The UI class created by the plug-in contains the following code:

[source, java]
----
package com.example.myproject;

import com.vaadin.ui.UI;
...

@Theme("mytheme")
public class MyUI extends UI {

    @Override
    protected void init(VaadinRequest vaadinRequest) {
        final VerticalLayout layout = new VerticalLayout();

        final TextField name = new TextField();
        name.setCaption("Type your name here:");

        Button button = new Button("Click Me");
        button.addClickListener(e ->
            layout.addComponent(new Label("Thanks " + name.getValue()
                    + ", it works!")));

        layout.addComponents(name, button);

        setContent(layout);
    }

    @WebServlet(urlPatterns = "/*", name = "MyUIServlet", asyncSupported = true)
    @VaadinServletConfiguration(ui = MyUI.class, productionMode = false)
    public static class MyUIServlet extends VaadinServlet {
    }
}
----

[[getting-started.first-project.theme]]
== Compiling the Theme

Before running the project for the first time, click the [guilabel]#Compile Vaadin Theme# button in the toolbar, as shown in <<figure.getting-started.first-project.compiletheme>>.

[[figure.getting-started.first-project.compiletheme]]
.Compile Vaadin Theme
image::img/myproject-compiletheme.png[width=40%, scaledwidth=60%]

[[getting-started.first-project.coding]]
== Coding Tips for Eclipse

=== Code Completion

One of the most useful features in Eclipse is __code completion__. Pressing
kbd:[Ctrl+Space] in the editor will display a pop-up list of possible class name and
method name completions, as shown in
<<figure.getting-started.first-project.coding.codecompletion>>, depending on the
context of the cursor position.

[[figure.getting-started.first-project.coding.codecompletion]]
.Java Code Completion in Eclipse
image::img/codingtips-codecompletion.png[scaledwidth=100%]

=== Generating Imports

To automatically add an [literal]#++import++# statement for a class, such as
[classname]#Button#, simply press kbd:[Ctrl+Shift+O] or click the red error indicator on the left side of the editor window.
If the class is available in multiple packages, a list of the alternatives is displayed, as shown in <<figure.getting-started.first-project.coding.import>>.

[[figure.getting-started.first-project.coding.import]]
.Importing classes automatically
image::img/codingtips-automaticimports.png[scaledwidth=70%]

For server-side Vaadin development, you should generally use the classes under the [package]#com.vaadin.ui# or [package]#com.vaadin.server# packages.
_You can not use client-side classes (under [package]#com.vaadin.client#) or GWT classes for server-side development._

[[getting-started.first-project.server]]
== Setting Up and Starting the Web Server

Eclipse IDE for Java EE Developers has the Web Standard Tools package installed,
which supports control of various web servers and automatic deployment of web
content to the server when changes are made to a project.

Make sure that Tomcat was installed with user permissions. Configuration of the
web server in Eclipse will fail if the user does not have write permissions to
the configuration and deployment directories under the Tomcat installation
directory.

Follow the following steps:

. Switch to the [guilabel]#Servers# tab in the lower panel in Eclipse.
List of servers should be empty after Eclipse is installed.
Right-click on the empty area in the panel and select "New > Server".

. Select "Apache > Tomcat v8.0 Server" and set [guilabel]#Server's host name# as [literal]#++localhost++#, which should be the default. If you have only one Tomcat installed, [guilabel]#Server runtime# has only one choice. Click [guibutton]#Next#.

. Add your project to the server by selecting it on the left and clicking [guibutton]#Add# to add it to the configured projects on the right. Click [guibutton]#Finish#.

. The server and the project are now installed in Eclipse and are shown in the [guilabel]#Servers# tab.
To start the server, right-click on the server and select [guilabel]#Debug#.
To start the server in non-debug mode, select [guilabel]#Start#.

. The server starts and the WebContent directory of the project is published to the server on http://localhost:8080/myproject/.

[[getting-started.first-project.run]]
== Running and Debugging

Starting your application is as easy as selecting [guilabel]#myproject# from the
[guilabel]#Project Explorer# and then "Run > Debug As > Debug on Server".
Eclipse then opens the application in built-in web browser.

You can insert break points in the Java code by double-clicking on the left
margin bar of the source code window. For example, if you insert a breakpoint in
the [methodname]#buttonClick()# method and click the [guibutton]#What is the
time?# button, Eclipse will ask to switch to the Debug perspective. Debug
perspective will show where the execution stopped at the breakpoint. You can
examine and change the state of the application.
To continue execution, select [guilabel]#Resume# from [guilabel]#Run# menu.

.Debugging a Vaadin Application
image::img/debuggingMyProject.png[scaledwidth=100%]

Above, we described how to debug a server-side application.
Debugging client-side applications and widgets is described in
<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging Client-Side Code">>.

[[getting-started.eclipse.mavenlibraryupdate]]
== Updating the Vaadin Framework Libraries

Updating the Vaadin plugin does not update Vaadin Framework libraries. The libraries are
project specific, as a different version might be required for different
projects, so you have to update them separately for each project.

. Open the [filename]#pom.xml# in an editor in Eclipse.

. Edit the [propertyname]#vaadin.version# property to set the Vaadin version.
+
Updating the libraries can take several minutes. You can see the progress in the
Eclipse status bar. You can get more details about the progress by clicking the
indicator.

. _In Vaadin 7.6 and older_: if you have compiled the widget set for your project, recompile it by clicking the *Compile Vaadin Widgetset* button in the Eclipse toolbar.
+
image::img/myproject-compilewidgetset.png[width=50%, scaledwidth=60%]

. Stop the integrated Tomcat (or other server) in Eclipse, clear its caches by
right-clicking the server and selecting [guilabel]#Clean# as well as
[guilabel]#Clean Tomcat Work Directory#, and restart it.

If you experience problems after updating the libraries, you can try using
"Maven > Update Project".