An Overview of Vaadin 7 Annotations

Vaadin 7 has added a set of useful new annotations to the framework which can be found in the package com.vaadin.annotations. This package is located in the vaadin-server.jar file. This blog post wants to give you a quick overview of these annotations and provides you with some additional information about them together with links to further information you might find useful.

  • @AutoGenerated – This annotation is used by the framework itself to mark code that has been auto-generated. You’ll find this annotation in code auto-generated by Vaadin’s Visual Designer to distinguish it from hand-written code. You will typically not use this annotation yourself.
  • @JavaScript – When developing with Vaadin, there are two options available for integrating custom JavaScript code into your application. The first option is to write your own client side widgets using GWT and its JSNI feature. The other option is to load a piece of JavaScript code from an external source and include this into the application. Vaadin lets you do that with its @JavaScript annotation. You can put this annotation on any class that implements the ClientConnector interface which is basically every UI component in the Vaadin toolkit. @JavaScript lets you load JavaScript resources either from some URL or directly from the classpath. Vaadin then ensures that these resources are loaded before the annotated ClientConnector has been initialized so that these resources are available when the component needs them. Since class UI is also a ClientConnector, you can annotate your UI class with @JavaScript, too.
  • @PreserveOnRefresh – Each time the user refreshes a Vaadin application in the browser window, the Vaadin servlet will create a new UI instance and discards all UI state from the formerly displayed UI. Only state that is in some way referenced by the URL (URI fragment, query parameters, etc.) will be transferred to the newly created UI instance. If you want to change this behavior, annotate your UI class with the @PreserveOnRefresh annotation. If this annotation is used, a browser refresh will not create a new UI instance. Instead, the already existing UI with its state is reused.
  • @Push – With the addition of server push capabilities in Vaadin 7.1 came this annotation. You have to put it on your UI class in order to enable that feature for your application. You’ll find more information about server push in the Vaadin wiki, Vaadin blog, and in the Book of Vaadin.
  • @StyleSheet – As with the @JavaScript annotation, you can annotate any class implementing ClientConnector with @StyleSheet to have the framework include a set of CSS resources into the webpage. The annotation lets you load CSS from external sources or from the classpath. This feature is useful if you want to include externally provided CSS styles into your application. For example, if you want to add a web font to your application, you can do this with the following code: @StyleSheet(""). Using this annotation on your UI class will make the Google Roboto web font available to be used by your theme. However, you should not add your custom styles to your application using this feature. This should be done by creating an own theme.
  • @Theme – Annotate your UI class with the @Theme annotation to define the theme to be used for your application. For instance, to use a theme named “my-theme”, you annotate your UI class like so: @Theme("my-theme"). In Vaadin 7, you can only statically define the theme used for a UI. Contrary to Vaadin 6.x, it is not directly possible to dynamically change the employed theme for a UI during runtime. There are discussions on this topic to be found in the Vaadin forum and on Stackoverflow.
  • @Title – You can statically define the page title for your application using the @Title annotation on your UI class. For example, annotating your UI class with @Title("My Vaadin application") will set the application’s title in the browser to the given text. Note that this will set the window title once and for all, without an option to internationalize the title text. This is useful if you only need to set a static title for your application without wanting to change it later. If you want to achieve a more dynamic behavior, you can also set the application title in code. You can do this with the current Page instance: Page.getCurrent().setTitle("My dynamic window title").
  • @VaadinServletConfiguration – This annotation is meant to be used on subclasses of VaadinServlet. Using this annotation, you can configure the Vaadin servlet in code the same way you would do in the web.xml. With @VaadinServletConfiguration you can define the UI class to be used by the servlet, enable production mode, define the UI heartbeat interval, the widget set to be used, and some more configuration values.
  • @Widgetset – A Vaadin application which defines its own widgetset needs to tell the framework the name of this custom widgetset so that it will be able to serve the corresponding files through the Vaadin servlet. This is typically done through the web application deployment descriptor web.xml. In it, you declare your widgetset’s name through the init-parameter aptly named widgetset. However, you can also do this with an annotation. Annotate your UI class with @Widgetset and provide the name of your widgetset through its value. By that, you don’t have to put this information into the web.xml.

Have a look at Vaadin’s JavaDoc for the annotation package for more information about these Vaadin annotations.

Besides the above listed annotations, there are several other miscellaneous annotations to be found in various packages.

  • @com.vaadin.shared.ui.Connect – Using this annotation, you establish the relationship between a client side connector with its corresponding server side connector. You need to do this when you’re writing your own custom components or extensions. You annotate your custom client side connector class with this annotation and specify the corresponding server side connector class in its value.
  • – The following two annotations are needed when working with the FieldGroup component. You can bind data held in a Vaadin Item instance to a set of form fields using the FieldGroup component. You can either create all necessary field components yourself or alternatively have this done for you by a FieldGroup instance. The FieldGroup binds the input fields of a form to a corresponding set of properties held in an Item object. In order to automatically establish this binding, the FieldGroup by default tries to bind an input field to a property id that has the same name as the field instance. So, if you have a TextField instance in your form with name “lastName” the FieldGroup tries to bind this input field to a property in a given Item with the same property id. If this name equality does not hold in your code, you can explicitly set the property id to which an input field is supposed to be bound. To do that, you annotate your input field with the @PropertyId annotation. In the example above, you would annotate your text field “lastName” with @PropertyId("surname") to bind it to a property with id “surname”.
  • – If you have the FieldGroup create the input field instances for you, you need a way to tell the FieldGroup which caption it should set on the auto-created fields. By default, the FieldGroup will use the bound property’s id as caption where the property id is capitalized and split on camel case. If you want to define your custom caption, you can do this by annotating your input field with the @Caption annotation. In the previous example for annotation @PropertyId, you could annotate the text field “lastName” with @Caption("Your surname") to define a custom caption.
  • @com.vaadin.shared.ui.dd.AcceptCriterion – This annotation is used by Vaadin’s Drag and Drop feature. It is similar to the @Connect annotation in that it connects a client side accept criterion with its server side counterpart. For example, this annotation is used to connect the client side accept criterion com.vaadin.client.ui.dd.VAnd with the server side class com.vaadin.event.dd.acceptcriteria.And which is used to combine a set of different accept criteria. Using this annotation, you can create your own criteria for accepting drop events.
  • @com.vaadin.shared.annotations.Delayed – With the @Delayed annotation you can specify that a server RPC call defined in a com.vaadin.shared.communication.ServerRPC interface should be sent to the server lazily. A call to a delayed RCP method will be held back by the framework until the next regular non-delayed call needs to be sent to the server (such as a button click). This is useful to reduce server roundtrips for components. The annotation adds the option to only send the last invocation of an RPC method to the server with the lastOnly attribute. If this attribute is set to true only the last invocation of a series of method invocations are sent to the server. All previous invocations are skipped. An example usage for this annotation is given in the following piece of code:
    public interface MyServerRpc extends ServerRpc {
        @Delayed(lastOnly = true)
        public void setText(String text);
  • @com.vaadin.shared.annotations.DelegateToWidget – When defining the shared state class for a custom Vaadin widget, you have to take care that server-side changes to the shared state are correctly forwarded by the connector to the widget object. This typically
    happens in a connector’s onStateChanged() method.
    In it, you pass the changed state values to corresponding data fields of your widget. This task can also be automated with the @DelegateToWidget annotation. If you annotate a field of your shared state class with this annotation, the framework will forward value changes for these fields to the corresponding
    fields of your widget. To do so, Vaadin will call the setter method on your widget which sets a JavaBean property with the same name as your shared state value field. For instance, if you have a shared state String field text, annotation @DelegateToWidget will transport value changes of text to method setText(String) of your widget. With the annotation’s value attribute, you can specify a differently named setter method for handing over the shared state values. Let’s have a look at an example usage of @DelegateToWidget in the Vaadin core classes. The shared state for the ColorPicker component, ColorPickerState, defines a boolean state field popupVisible. This field is annotated as follows:

    public boolean popupVisible = false;

    By that, changes in the popupVisible field will be automatically delegated to the corresponding widget’s method VColorPicker#setOpen(boolean open).

Short URL for this post:

About Roland Krüger

Software Engineer at Trivadis / Orientation in Objects GmbH. Follow me on Twitter.
This entry was posted in Did you know?, Java Web Frameworks and tagged , . Bookmark the permalink.

2 Responses to An Overview of Vaadin 7 Annotations

  1. Pingback: Select Nested JavaBeans With a Vaadin FieldGroup - techscouting through the java news

  2. Pingback: Vaadin 7.3 Introduces New Valo Theme - techscouting through the java news

Leave a Reply

Your email address will not be published. Required fields are marked *