Author of this tutorial and NetBeans plugin: Denis Anisimov


Vaadin plugin functional description

This page isn't Vaadin tutorial. This is Vaadin plugin for NetBeans tutorial and its functional description. The purpose here is to enable comfortable code writing without need to google information about various configuration aspects and avoid most popular and hard-detectable mistakes made by newbies and experienced programmers.

Some Vaadin framework usage details will be covered here as well but please see Vaadin section for the links.


Vaadin - Web application framework for rich Internet applications.

Framework link :

Download link : current release

NetBeans plugin: current release. Book: Book of Vaadin

Vaadin tutorial: tutorial

Demo: examples

Basic functionality

There is no need to download any binaries except NetBeans and Vaadin plugin to be able to create Vaadin based project. Download nbm file, go to Tools->Plugins, Downloaded tab, and press "Add Plugins..." button. Choose downloaded file and click "Install" button.

Once the plugin is installed there will be "Vaadin" category in the "New Project" wizard. Choose this category and "Vaadin Web Application Project" template.

The project is going to be Maven based so it's possible to set up maven related attributes on the second step panel. If you are not familiar with maven then you don't have to change default values here except name of the project. Maven is used transparently for the user so there is no need to worry about it. All build and deploy actions are performed via NetBeans UI.

Project will be created after wizard finishes. All libraries will be downloaded for you transparently by maven. See the resulting project tree on the right side.

Project template contains GWT module file AppWidgetSet.gwt.xml which is required for custom widgets development. There are a lot of ready to use widgets in the Vaadin framework. So there is no need to create your own custom widget unless you have some specific requirements. Here you can find all available components and usage code snippets. If you want to use an Add-On component or a custom component then project has to contain mentioned GWT module file (see below for custom component case). We don't need it at the moment so let's delete it.

Module file deletion allows to speed up project assembly: if project contains client-side code (custom widgets) then it has to be compiled onto the JavaScript. This compilation is done transparently on the project build phase if there is a GWT module file. Core Vaadin framework components are already compiled so there is no need to compile them. Compilation process takes some significant time and slows down the development process.

Waring: Use "Refactor->Safe Delete" action to delete GWT module file. "Delete" action only deletes a file but don't update references. There is a reference to the file in the servlet configuration. Either @WebInitParam parameter of @WebServlet or widgetset parameter of @VaadinServletConfiguration has value with GWT module fully qualified name. Broken servlet configuration doesn't produce any error on the project build stage but web applicaiton will be broken at the runtime. This is the first easy and hard-detectable issue which may be a stumbling for newbie. Plugins for other IDEs don't support GWT module file refactoring. So you have to be always aware of this configuration issue. But NetBeans plugin shows an editor error even if you have used plain "Delete" action. Once you open MyVaadinUI (which is an entry point for Vaadin application and contains servlet configuration) you will see an editor error glyph.


You can build an run the project after module file deletion. Use "Build" action from the project's popup menu. Target J2EE application server could be either IDE registered server (Services tab, Servers subnode) or embedded lightweight Jetty server. Make sure you have selected J2EE server in your project properties to be able to use IDE registered server (Project properties ->Run category->Server setting). If there are no servers available then you have to register one via Services tab f.e. Use "Run" action to start a project. Project will be deployed and it's URL will be opened in the browser.

Embedded Jetty server could be used instead of IDE registered server as well. Select "Embedded Jetty->Run" popup menu action to start Jetty. Jetty server will be run via Maven plugin. In that case browser won't be opened in addition to project deployment. So you should open application URL in your browser manually. Application URL is "http://localhost:8080/{context_path}" where {context_path} is the name of your project. Your can find this value in Jetty server console output. Look up for string Context path = xxxxx.

Notice: you can switch off Jetty if you don't use it. Go to Options dialog: Tools->Options. Choose Java and Vaadin tab. Uncheck "Show Jetty Popup Menu Action" option.

Extended functionality

Most popular mistakes

The application created above consists of button, which appends text labels below the button.

This is simple application generated by Maven archetype. We are not going to extend this example further on the server side because this text is not about Vaadin as it has been already mentioned.

If you don't have any special requirements for your application and server-side development is enough then any plugin is good for this purpose. Functionality described above could be found in any Vaadin IDE plugin. There are a lot of implemented component available and ready to use for you in Vaadin core framework. So perhaps there will be no need to need to create custom client-side component. But there are a number of configuration requirements where you can go wrong once you realized that such custom component is required. Mistake could be made due to the fact that you forgot something to write in the source code or add some artifacts. As a result you will spend a time to find a reason this mistake. Plugin allows to you to avoid such mistakes.

So let's assume you want to extend your application in the way that it shows a tooltip when mouse is over the label text. It could be done without client-side code implementation. Let's create new class LabelEx which extends the Label class and set tooltip text in its constructor.

File:Vaadin-label-ex.png File:Vaadin-label-ex-usage.png

The result is:

There is an issue: it's not convenient to show tooltip text if it's big. So an additional requirement will be: show short tooltip text when mouse is over and show full text tooltip on mouse click inside tooltip only (this is similar how Eclipse Javadoc tooltips work).

It can be done in many ways and two of them are going to be used to show small mistakes, which lead to broken application. Let's discuss them in details. The most natural way to start is extending existing class Label especially that its subclass already has been created (LabelEx).

The expandable tooltip functionality cannot be implemented via extending server-side Label component only. Client side coding is required here. There is a way to start with client side widgets via wizards.

Those wizards are useful when you create component from scratch. One of the wizard templates will be used later on to show the second way to implement our usecase. But now we already have LabelEx class extending Label and it's reasonable to start with it. Wizards are not convenient here: you will have to go through created classes and correct them all.

To extend client side code for Label class one needs to create connector and override its getWidget() method, which has to return your own client side widget. Let's create dedicated package "com.mycompany.vaadin.labelex" and class LabelExConnector inside it. Add an "extends" clause to it once it created so that it's being derived from LabelConnector. The latter class is used to connect Label class on the server side and its client side code.

Method getWidget() is inherited by created LabelExConnector from its superclass. This method returns VLabel widget class available in Vaadin core framework. So we've not added any new functionality for Label class but now it seems that we have at least a client side entry point where further development could be done. It means that after project rebuild everything should work in the same way as previously but based on the new LabelExConnector. It turns out hat the latter class won't be used at all. So what's the issue ? There are a lot of issues here actually. And they are not obvious in that specific case.

package com.mycompany.vaadin.labelex;

import com.vaadin.client.ui.label.LabelConnector;

public class LabelExConnector extends LabelConnector{

Source code snippet here is used instead of image to hide actual errors because NetBeans plugin will show all the problems in the editor. Let's show here all the issues with detailed description and then show how they are marked as editor error:

  1. It's not enough to derive Connector class from LabelConnector (or, f. e. abstract AbstractComponentConnector, which is generated via wizards by default). Component connector annotation @Connect(LabelEx.class) is required in order to link server side component class with its connector. There is already @Connect annotation defined for Label class. But the latter annotation provides a connection for Label class and not for LabelEx. This problem would not have happened if the class had been created via the wizard. In that case, the abstract would have been inserted in the generated class with the correct value.
  2. The previous error fix will solve the logically binding issue. But logical binding just give information to the GWT compiler how to do the connection. Actual binding should be done on the build project stage. And this will not be done because the GWT compiler can not find the connector class. It's not able to do that due to the fact that there is no module file (.gwt.xml). The latter file has been deleted to speed up project building at the very beginning. Again, this could have been avoided if the wizard had been used. Module file would have been created automatically in that case.
  3. It's not even enough to create GWT module file via wizard. This file FQN has to be added to the servlet configuration (this issue has been already mentioned at the very beginning). Otherwise when you run the application it won't know which module file to use. And again the wizard does it all automatically.
  4. Finally, the last issue: after the module file is created, its location defines the packages where GWT compiler will look for classes to compile. By default, the package with the client classes is defined as a subpackage named "client" of file module package. That is if the file AppWidgetSet.gwt.xml is inside the package "com.mycompany.vaadin" then client classes (including connector) will be searched only in the package "com.mycompany.vaadin.client ". Client packages can be defined by using the <source path="relative path"/> as well. In our particular case the connector is created in the package "com.mycompany.vaadin.labelex", which is not a client. Again this problem would not have happened if the wizard has been used.

The issue described in the last item is one of the most popular problems made accidentally or by beginners who don't know all Vaadin framework details. It's a result of an agreement defined by GWT compiler that you just have to remember and know. In that way we get the most popular and very hard-detectable mistake.

There is a reasonable question: why did not we use wizards from the beginning if it handled all possible cases. Of course we could. The only issue here is the way how the wizard works. It generates files by the templates and there is no way to configure generated code flexibly. Otherwise it would be required to set a lot of parameters and UI would be oversaturated by control elements. But wizard has to be as simple as possible to be able to use it quickly.

On the other hand it turns out that it's necessary to use the wizard for any action related to writing client side code. Otherwise there is always a risk to do a simple mistake. The requirement to always use the wizard is quite strange. IDE should deal with those kind of mistakes. It should help to developer solve routine issues quickly in a such a way that developer could care only about application business logic. That is exactly why we use IDEs. Fortunately, the plugin provides all this functionality for you. If you open the connector file in the editor it will show errors and offer to fix them.

It's impossible to detect client package without GWT module file so you will see its absence error mark and connect annotation absence mark.

File:Vaadin-wrong-labelex-connector.png File:Vaadin-wrong-labelex-connector-fixes.png

You will see wrong client package error mark after fixing previous issues.

File:Vaadin-wrong-labelex-package.png File:Vaadin-wrong-labelex-pckg-fixes.png

One can go through all the errors shown in the editor and use suggested ways to fix them via the assistant. It allows do not keep all framework configuration details in your mind. IDE generates all necessary artifacts and corrections transparently. But let's stop here with this approach and move forward to the next one. Just clean up the source code created at the moment and delete LabelEx and LabelExConnector classes.

Wizards and editor assistant usage for widgets creation

Let's go by the second way and use the wizards now. The wizard allows you to create components from scratch as well as based on existing components. There are two templates to create a custom widget: full fledged template which creates server side component, client side component and all classes that could be used to communicate between them (RPC interfaces and their implementations, shared status class) and simple template which creates only server-side class and its connector. The first template is useful only when you know in advance that you will need the full interaction between client and server in both directions. Typically it's not a case and development process is iterative and is performed step by step. Therefore this pattern is inconvenient because it generates all at once but it's not required: stubs remain unimplemented for a long time until you get round to it. This is exactly our case so let's use the second template that will create a minimum basis on which to continue to develop.

To generate classes using the selected template one can click "Finish" button right on the current wizard page. The other option is to go to the next page via "Next>" and select an existing component to inherit. The first option is useful for fast component creation from scratch. In that case generated server side component extends AbstractComponent and its connector extends AbstractComponentConnector. To adopt generated classes to our requirements we have to go through generated classes and change their extends clauses. The second option could be used when you want to extend existing component functionality. This approach is preferable in our specific case because it generates the required code immediately and there is no need to do any corrections. Just choose class com.vaadin.ui.Label on the last step. As a result the wizard will generate server side component class and its correctly annotated connector in the right package. GWT module file will be created as well (if there is no one) and servlet configuration will be correctly updated.

File:Vaadin-labelex-location-wizard.png File:Vaadin-labelex-super-wizard.png

Wizard generates three files as the result of its work: LabelEx server side class, its connector LabelExConnector and widget class LabelExWidget.

       package com.mycompany.vaadin;

       import com.vaadin.ui.Label;

       public class LabelEx extends Label {
           public LabelEx() {

       package com.mycompany.vaadin.client;

       import com.vaadin.client.ui.VLabel;

       public class LabelExWidget extends VLabel {

LabelEx will behave now in the same way as a standard class Label if you build the project and run it. Tooltip on the text will not appear because the LabelEx generated constructor does not call setDescription() method. We are not going to use this method because it will require Vaadin tooltip implementation details knowledge. Let's take a static text instead and extend the client side class: implement required functionality in the LabelExWidget class. We have already all the necessary binding between server side and client side classes. So the only remaining thing is just put the code inside LabelExWidget class. Let's skip the deep implementation details. Below is the code based on GWT API and Vaadin client classes which does what we need.

       package com.mycompany.vaadin.client;

       import com.vaadin.client.ui.VLabel;
       import com.vaadin.client.ui.VOverlay;

       public class LabelExWidget extends VLabel {
           private static final String SHORT_TOOLTIP = "Short tooltip";
           private static final String FULL_TEXT = "Lorem ipsum dolor sit amet, "
                   + "consectetuer adipiscing elit, sed diam nonummy nibh euismod "
                   + "tincidunt ut laoreet dolore magna aliquam erat volutpat. "
                   + "Ut wisi enim ad minim veniam, quis nostrud exerci tation "
                   + "ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo "
                   + "consequat.";
           private final Timer timer = new Timer() {

               public void run() {
           private final Label tooltip;
           private final TextArea textArea;
           private VOverlay overlay;
               overlay = new VOverlay(true);
               tooltip = new Label(SHORT_TOOLTIP);
               textArea = new TextArea();
               MouseListener listener = new MouseListener();
               addHandler(listener, MouseOverEvent.getType());
               addHandler(listener, MouseOutEvent.getType());
               overlay.addDomHandler(listener, MouseOverEvent.getType());
               overlay.addDomHandler(listener, MouseOutEvent.getType());
               overlay.addDomHandler(listener, ClickEvent.getType());
           private class MouseListener implements MouseOverHandler, MouseOutHandler, ClickHandler{

               public void onMouseOver(MouseOverEvent event) {
                   if ( !overlay.isShowing()){

               public void onMouseOut(MouseOutEvent event) {

               public void onClick(ClickEvent event) {
                   Widget widget = overlay.getWidget();
                   if ( tooltip.equals(widget)){

The only detail that is important here to note for the subsequent text: both short and long tooltip text are statically defined in the class and can not be changed dynamically. It differs f.e. from the way how the content text could be set for Label class. The latter text can be set on the server side and changed dynamically at runtime. Let's implement the same behavior for our custom tooltip: we need the ability to set short and full text values on the server side.

Required interaction between server and client could be solved by using shared state class (subclass of SharedState). We would like to create methods in the LabelEx class that allow to set short and long tooltip text. Those methods should initialize fields of state class. The latter state will be transferred to the client on the server request. But what is the most convenient way to do that? Of course you can create a new class and add "extends" clause to it. But you have to care about correctness of the superclass. Our custom LabelEx component extends Label component and the latter component already has its own state class. It means that new custom state class has to extend Label state class. So that state class creation requires several steps. There is no wizard to do that but it wouldn't solve several steps issue: you would require to call the wizard, choose the file type, select a location for it and choose the superclass. And all this information except its name is already available in the context of the server component or its connector. So editor assistant offers a hint to create this class and this hint is available as an editor annotation attached to the server component class and its connector class. In order to get this hint you should choose the class as an editor context (cursor must be somewhere inside the body of the class), f.e. put the cursor on its name in the declaration.

File:Vaadin-labelex-component-state.png File:Vaadin-labelex-connector-state.png

File:Vaadin-labelex-component-state-fixes.png File:Vaadin-labelex-connector-state-fixes.png

There are two fixes available for the hint. The first one creates state class and define a getState() method only in the current context class. The second fix defines the latter method in the paired class as well. You can specify a class name in the dialog which appears when fix is chosen.


As a result of the fix one will get a state class which has a correct superclass and method getState() will be defined in the class itself and its paired class in case if appropriate fix has been chosen. Let's add the state class usage logic into the server side component and client side to transmit its content in between. The code below allows you to set tooltip values on the server side.

File:Vaadin-labelex-component-connector.png File:Vaadin-labelex-widget-state.png

Thus we have implemented the functionality that allows to set tooltips text on the server side. Let's assume now we want to get notification when short tooltip text gets clicked so that one can add listeners for this event on the server side. It could be useful in order to set long tooltip text dynamically exactly at the moment when click happens instead of doing it beforehand.

We are not going to delve into the details here how it could be done exactly. Only sketch of implementation will be shown here based on features provided by IDE for developing RPC communication. We do already have client side method onClick() implemented in the private MouseListener class (nested class in LabelExWidget). The latter method is called when mouse is clicked. The only thing we should do is notify the server about the event. To do that we have to use RPC communication. We need an interface that extends com.vaadin.shared.communication.ServerRpc. This interface represents the server side interaction. The interface method calls will be transmitted via the network to the methods implemented by the server side class.

Once can create RPC interface and register it manually on the client side in a few steps. There is a wizard which creates a new component from scratch with all interaction classes (full fledged template). This wizard has already been mentioned above and it's inconvenient to use it here because we want only one side interaction and we already have a component class. It just has no sense to use the wizard to generate classes only for code templates (to copy the snippets and delete all generated artifacts). That's exactly the way of iterative component development which you often have to deal with. The situation we have here is similar to that class state creation case. We don't need a wizard to do it because the context provides all information except RPC interface name.

Server component class or connector class could be used as a context (its reference is required to be able to create a proxy class for RPC interface, see below). You can choose any of them but it's reasonable to start with the connector in this case. Editor assistant offers hints and fixes for the connector class as a context just as with the state class.

File:Vaadin-labelex-connector-rpc.png File:Vaadin-labelex-connector-rpc-fix.png

Empty interface along with a new method in the connector class will be created as a result of the proposed fix for the hint. The latter method returns a reference to the interface proxy to be able to use the interface by calling its methods on the client side.


All you need to do now is add the appropriate method in the generated interface and call it somewhere in the connector code. That's the only thing IDE is not able to on its own because this is the application business logic. All binding routine work has been done within minimum required steps.

So the only remaining action on the client side is RPC interface method call (of course you have to create one there) from nested MouseListener class. You just have to provide somehow an access to the RPC proxy reference which is available inside connector but not inside LabelExWidget widget class. That's a trivial implementation detail and could be solved in a many different ways. Let's omit those remaining details here and move forward on to the server component.

It's necessary to create RPC interface implementation class on the server side and write the appropriate business logic there. When you open server component class LabelEx in the editor then the assistant will show a hint attached to it. The hint reports an absence of the registered server RPC interface implementation.

File:Vaadin-labelex-component-rpc.png File:Vaadin-labelex-component-rpc-fix.png

Editor assistant finds an existing server RPC interface and offers either use it or create a new one from scratch. Fix based on the existing interface creates anonymous stub class inside LabelEx class and assign a reference to it to the rpc field. Also registerRpc method call will be added into the LabelEx class constructor. This call registers the anonymous class reference in order to call its methods when they are requested from the client side.


Thus all the routine work has been made by an assistant again. All that's left to do is implement generated anonymous class whose reference is assigned to rpc field. The latter class is empty because we haven't added here a method to the RPC interface before applying the fix. The method should be added and implemented inside the anonymous class (if the interface had had the method before fix has been applied then generated anonymous class would have been generated with a stub method implementation). Well written implementation should notify the listeners registered to the server component with a custom event. But these are business logic details and component API which are out of scope this article and could be done easily by the developer.

The main purpose of the article is show how to do iterative development following the editor assistant without using wizards. There are a lot of different cases where one can forget to add required artifacts or doesn't take into account something while developing client/server communication. The editor assistant is your best friend for such cases. Here you can find a few of these tips which will be useful to work on implementation of this interaction. In particular the same method described above can be applied to make RPC interaction from the server to the client, state class related issues (like serialization f.e.), RPC interfaces methods and their arguments.

Client side compilation and Dev Mode

Client side code in your application has to be compiled into JavaScript. This is done automatically when you build the project. Compilation can be run via the Compile Widgetset and Theme pop-up menu project action as well. Here are other related actions in the project popup menu:
  • Compile Theme - compiles theme. You can define styles using SCSS files. But they have to be compiled into css in the resulting application. That's exactly what the action does. The mentioned above action Compile Widgetset and Theme performs both Java code compilation into JavaScript and theme compilation.
  • Run Dev Mode - runs Dev Mode which executes client side code inside JVM instead of JavaSceipt browser engine. It allows to investigate issues inside your client side source code.
  • Run Dev Mode (debug) - debugs Dev Mode. This action starts Dev Mode debug server and attach NetBeans debugger to it. As a result you can debug your client side code in the same way as a plain Java application code.
  • Run Super Dev Mode - starts GWT Super Dev Mode. This mode allows to debug client side code inside your browser via browser debugger. See details in GWT documentation.
There are also Jetty actions available in addition to those Vaadin related action. Embedded Jetty server has been already mentioned and you can use it via maven plugin. Jetty popup menu action could be disabled if you don't want to use it all (see above). Here are the Jetty actions:
  • Run - starts Jetty server.
  • Debug - starts Jetty server in debug mode. As a result you will be able to debug your Java code on the server.
  • Run with Dev Mode - starts Jetty server and GWT Dev Mode. The result of the action is not the same as an invocation result of two actions separately (Jetty Run action and Run Dev Mode respectively). Run Jetty action depends on build project action. It means that Run starts client side classes compilation before server start. But Dev Mode is used for the reason to avoid recompilation and speed up the development: if you change the client side source code then it immediately becomes available in runtime via Dev Mode. As a result you save your time. It will happen only when Dev Mode is already activated but you still have to wait until full client side compilation be finished if you use plain Run Jetty action. That's most likely not what you would want and that is why this action starts to build the project with a special flag before starting the server to prevent compilation client side code.

Besides the Dev Mode there are a number of options that allows to speed up compilation process and change its behavior. Those options are available via project properties: Vaadin category contains several sub-categories, which allow you to configure the compiler.

Here is the options description for Compiler and GWT category. (here you can find other categories options description):
  • Extra JVM Arguments - Extra JVM arguments that are passed to the GWT-Maven generated scripts.
  • JavaScript Style - GWT JavaScript compiler output code style.
  • Compiler Threads - Number of parallel processes used to compile GWT permutations. Defaults to platform available processors number.
  • Logging Level - GWT logging level.
  • Faster compilation (draft) - Enable faster, but less-optimized, compilations.

Directory Add-Ons

You could realize at some point that there is no standard Vaadin core component for your purpose. Try to search existing component before starting to write your own custom component. Add-Ons Directory contains a large number of Add-Ons, which are UI components and libraries extending application functionality. Find required Add-On via specifying search parameters. Copy XML snippet and insert it into your POM file. All Add-On files will be downloaded from the remote maven repository and added to the project as dependencies at build [phase.

The other option is available for you here instead of using an external web browser application to search for add-ons. There is an Add-Ons Browser dialog which could be opened via the action "Vaadin-> Open Add-Ons Browser".


The dialog that you get as a result of the action allows you search Add-Ons in a similar way to Add-Ons Directory web page mentioned previously. This browser shows almost the same information as the original directory. You can get basic information about Add-On and quickly go to the complete Add-On description in web page via the available link.


Search results can be sorted by columns in the table and the selected addition can be added to the project as a dependency via the button "Add". POM file will be updated with appropriate Add-On snippet in the result of this action and all dependency libraries will be downloaded from the maven repository transparently for you.

You can use Add-On in your project even easier and faster if you know exact name of Add-On classes (f.e. you have already used it previously or just guessing). Just use standard IDE code completion for this purpose. Code completion list is extended with classes available via the Directory. So even if there is no class in your project classpath but its name starts with the prefix typed in the editor it will be listed among other code completion items. To do that type the class prefix, press Ctrl-Space and you will see matched classes from the Directory. They are rendered using different color.


As a result of selected Directory code completion item standard behavior is applied along with appropriate POM file modification and extending project dependencies with downloaded artifacts.

Code completion class items are classified into three categories: server side classes, client side classes and classes for tests. Server side classes are shown only for code inside the server component classes, client side classes and tests based classes are shown only for client code and tests respectively.

All information about the available Directory Add-Ons from is taken from the local cache, so there is no need to request the remote server each time to obtain this information and search it. and hence no possible problems with speed and performance related to communication over the network. Relevance same information maintained periodic update the cache, which is configured via the global settings. Therefore there is no network related performance issues and server response delays. Information relevance is managed by cache periodic update, which is configured via the global settings.


All cache synchronization settings have five values:

  • Use cached data - don't update cache at all. Use only latest available cached data since last update or plugin bundled data.
  • Download on each IDE start - update cache per IDE session.
  • Download daily - update cache daily.
  • Download weekly - update cache weekly.
  • Download monthly - update cache monthly.

These settings give you a full control of information transmitting over the network. It's possible to completely disable cache update if you do not want to send remote Internet request.

You can completely disable the Directory code completion as well if you do not want to use this functionality and it obstructs your work.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo