Book of Vaadin - vaadin.com

2.3. QuickStart with Eclipse
Prev	Chapter 2. Getting Started with Vaadin	Next

2.3. QuickStart with Eclipse

Eager to start developing you own applications using Vaadin? This section presents a QuickStart into running and debugging Vaadin demos under Eclipse. The QuickStart includes a web server, so you do not need to have a full-weight web container such as Apache Tomcat installed.

If you have followed the instructions given in Section 2.2, “Setting up the Development Environment”, you can start Eclipse by running C:\dev\eclipse\eclipse.exe (Windows) or /opt/eclipse/eclipse (Linux or OS X). Depending on your environment, you may need to give additional memory settings for Eclipse, as the default values are known to cause problems often in some systems.

When starting Eclipse for the first time, it asks where to save the workspace. You can select any directory, but here we select C:\dev\workspace (Windows) or /home/<user>/workspace (Linux or OS X). We suggest that you also set this as the default.

Close the Eclipse "Welcome" -screen when you are ready to continue.

2.3.2. Importing Vaadin as a Project

If you have not yet downloaded the Vaadin package, instructions for downloading and unpacking are available at Section 2.1.1, “Installing the Distribution Package”.

The installation directory of Vaadin contains all necessary files to allow importing it as a ready-to-run Eclipse project:

Start Eclipse with any workspace you like. Switch to the Java Perspective through Window → Open Perspective → Java.
Select File → Import... to open the import dialog.
In the Import dialog, select General → Existing Projects into Workspace and click Next.
In the Select root directory option, click the Browse button, and select the folder where you unpacked Vaadin, e.g. c:/dev/vaadin-windows-6.x.x. Click OK in the selection window. The Projects list now shows a project named vaadin-examples. Click Finish in the Import window to finish importing the project.

The newly imported project should look like Figure 2.4, “Vaadin demo project imported into Eclipse”.

Figure 2.4. Vaadin demo project imported into Eclipse

You can now browse the source code of the demo applications in Eclipse. The next section describes how you can run the demos.

2.3.3. Running the Demo Applications in Eclipse

Once the project is imported, as described above, you can run the Content Browser, including the demo applications, as follows:

From the main menu, select Run → Run Configurations....
From the list on the left, select Java Application → Vaadin Web Mode.
Click Run.

Note that after the application has been launched once, it appears in the Favorites list. You can then click on the small dropdown arrow on the right side of the Run button on Eclipse toolbar and select Vaadin Web Mode.

Running the application in Web Mode will start an embedded web server and open a browser window with the Content Browser. The default system web browser is opened; make sure that the browser is compatible with Vaadin. The Console view in the lower pane of Eclipse will display text printed to standard output by the application. Clicking on the red Terminate button will stop the server.

Figure 2.5. Vaadin Content Browser Started Under Eclipse

Note that executing the web application locally may cause a security warning from your firewall software because of the started web server. You need to allow connections to port 8888 for the Content Browser to work. Also, if the web service fails to start, make sure that no other service is using port 8888.

Launching the Hosted Mode Browser

The Hosted Mode Browser of Google Web Toolkit is a special web browser that runs the client-side GWT Java code as Java runtime instead of JavaScript. This allows you to debug the client-side components in an IDE such as Eclipse.

Hosted Mode Browser in Linux

The Hosted Mode Browser in Google Web Toolkit 1.5.62/Linux is not compatible with Vaadin. If you want to debug client-side code in Linux you should download the experimental OOPHM-version of Vaadin. This contains a newer GWT which supports using a normal browser for debugging. This is explained more in Section 10.8.7, “Out of Process Hosted Mode (OOPHM)”. Note that you should not use the OOPHM version of Vaadin in production environments, only for debugging.

To run the demo applications in the Hosted Mode Browser of Google Web Toolkit, follow the following steps:

If not already started, start the demo application in Web Mode as described above. We only need the server so close the web browser which is automatically opened.
From the main menu, select Run → Debug Configurations... .
From the list select Java Application → Vaadin Hosted Mode.
Click Debug.

Starting demo applications under the Hosted Mode Browser can take considerable time! This is especially true for the Reservation and Color Picker applications, which require compilation of custom widget sets. During this time, the Hosted Mode Browser is unresponsive and does not update its window. Compiling widget sets can take 5-30 seconds, depending on the hardware.

As with the Web Mode launcher, after you have run the Hosted Mode launcher once, you can click the dropdown marker on right of the Debug button in the toolbar and select Vaadin Hosted Mode.

To use the Hosted Mode Browser in other projects, you need to create a launch configuration in Eclipse. See Section 10.8.6, “Hosted Mode Browser” for more detailed information about the Hosted Mode Browser and how to create the launch configuration.

How to Stop the Run

To stop the launched Jetty web container that serves the Content Browser web application, select the Console tab and click on the Terminate button.

Figure 2.6. Terminating a Launch

To clean up all terminated launches from the Console window, click on the Remove All Terminated Launches button.

Figure 2.7. Removing Terminated Launches

2.3.4. Debugging the Demo Applications in Eclipse

At some point when developing an application, you want to debug it. Running a web application in debug mode is easy in Eclipse. Next, we will show you how to debug the demo applications by inserting a breakpoint in the Calc example.

Make sure to stop any previous Run command as instructed above at the end of Section 2.3.3, “Running the Demo Applications in Eclipse”.
Select Run → Debug Configurations... from the main menu and the Debug configuration window will open.
Select Java Application → Vaadin Web Mode and click Debug. The server will start and the web browser will open.
Open the source code for the Calc program. It is located in WebContent/WEB-INF/src/com.vaadin.demo.Calc. WebContent/WEB-INF/src is the project's source folder, shown right below the JRE System Library. Double-click the class to open the source code in the editor.
Insert a breakpoint in the init() by right-clicking on the gray bar on the left of the editor window to open the context menu, and select Toggle Breakpoint.
Switch to the browser window and click the Calc link (below More Examples) to open it.
Eclipse encouters the breakpoint and asks to switch to the Debug perspective. Click Yes. The debug window will show the current line where the execution stopped as illustrated in Figure 2.8, “Execution Stopped at Breakpoint in Debug Perspective in Eclipse”:

Figure 2.8. Execution Stopped at Breakpoint in Debug Perspective in Eclipse
You can now step forward or use any commands you would normally use when debugging an application in Eclipse. Note that you can only debug the application code in this way. If you are running the Hosted Mode browser you can also insert break-points in client side component code and debug it.