path: root/documentation/articles/MigratingFromVaadin6ToVaadin7.asciidoc

[[migrating-from-vaadin-6-to-vaadin-7]]
Migrating from Vaadin 6 to Vaadin 7
-----------------------------------

For migration to Vaadin 7.1,  see
link:MigratingFromVaadin7.0ToVaadin7.1.asciidoc[Migrating
from Vaadin 7.0 to Vaadin 7.1]

[[getting-started]]
Getting Started
~~~~~~~~~~~~~~~

Most Vaadin 7 APIs are compatible with Vaadin 6, but there are some
changes that affect every application.

Moving to Vaadin 7 brings a number of features designed to make the
lives of developers easier. It is a major version where we could improve
(and break) some parts of the API that have been stagnant and in need of
improvement for years.

Fear not, though, as the vast majority of the API is unchanged or
practically so - many parts even for the last 10 years apart for some
package name changes. While every application requires some migration
steps, the minimal steps needed for many applications are simple enough,
although a few more changes can be useful to benefit from some of the
new features such as improvements to data binding.

The first step is to *update Vaadin libraries*. While Vaadin 6 had a
single JAR and separate GWT JARs, Vaadin 7 is packaged as multiple JARs
that also include GWT. The easiest way to get all you need is to use Ivy
(see below in the section on updating an existing Eclipse project) or
Maven (see below on updating a Maven project). If you are using the latest version of
the Vaadin Eclipse plug-in, upgrading the facet version creates an Ivy
configuration.

The first code change that applies to every Vaadin 6 application
concerns the *com.vaadin.Application* class - it *exists no more*. The
main entry point to your application is now a *com.vaadin.ui.UI*, which
replaces Application and its main window. When switching to UI, you also
get multi-window support out of the box, so bye bye to any old hacks to
make it work. On the flip side, a new UI is created on page reload. If
you prefer to keep the UI state over page reloads in the same way Vaadin
6 does, just add *@PreserveOnRefresh* annotation on your UI class.

For minimal migration, though, it is possible to replace Application
with *LegacyApplication* and its main Window with *LegacyWindow* and
postpone a little dealing with UIs, but when migrating to UIs, you get
more out of the box. The class *Window* is now only used for
"sub-windows" (windows floating inside the page) , not "browser level"
windows or tabs (the whole web page).

An example should clarify things better than lengthy explanations,
so:Vaadin 6:

[source,java]
....
package com.example.myexampleproject;

import com.vaadin.Application;
import com.vaadin.ui.*;

public class V6tm1Application extends Application {
  @Override
  public void init() {
    Window mainWindow = new Window("V6tm1 Application");
    Label label = new Label("Hello Vaadin!");
    mainWindow.addComponent(label);
    setMainWindow(mainWindow);
    setTheme(“mytheme”);
  }
}
....

Vaadin 7:

[source,java]
....
package com.example.myexampleproject;

import com.vaadin.server.VaadinRequest;
import com.vaadin.ui.*;

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

  @Override
  protected void init(VaadinRequest request) {
    VerticalLayout view = new VerticalLayout();
    view.addComponent(new Label("Hello Vaadin!"));
    setContent(view);
  }
}
....

In addition, replace `com.vaadin.terminal.gwt.server.ApplicationServlet`
with com.vaadin.server.*VaadinServlet* in web.xml and its parameter
"application" with "*UI*" pointing to your UI class, and the application
is ready to go. Likewise, *ApplicationPortlet* has become *VaadinPortlet*.

Some package names have also been changed, but a simple import
reorganization in your IDE should take care of this.

If you have a custom theme, import e.g.
"../reindeer/*legacy-styles.css*" instead of "../reindeer/styles.css".
The theme is now selected with an *@Theme* annotation on your UI class
rather than a call to *setTheme()*, the usage should be clear from the
example above.

Most remaining issues should show up as compilation errors and in most
cases should be easy to fix in your IDE.

Now you should be ready to compile your widgetset (if any) and take the
application for a first test drive. If you have customized themes, they
will probably also need other updates - see the section on themes below.

Note that support for some older browser versions - including IE6 and
IE7 - has been dropped in Vaadin 7. If you absolutely need them, Vaadin
6 will continue to support them until its planned end of life (June
2014, five years from release of 6.0).

If you have problems with specific topics, see the related sections of
the migration guide.

In case you need more help with the migration, the Vaadin team also
provides https://vaadin.com/services#professionalservices[professional
services].

[[converting-an-eclipse-project]]
Converting an Eclipse project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have an existing Vaadin 6 Eclipse project, the easiest way to get
up and running with Vaadin 7 is to switch to *Ivy for dependency
management*. In the project properties, select Project Facets and change
the Vaadin plug-in version to 7.0. If necessary, upgrade also the Java
and Dynamic Web Module facets. _Make sure you use the latest version of
the *Eclipse plug-in* from the update site
https://vaadin.com/framework/get-started#eclipse for this, and note that currently
installing it also requires that the IvyDE update site is configured. We
will attempt to eliminate this additional complication soon._

Ivy dependency management can also be configured by hand by adding the
files ivy.xml and ivysettings.xml to the root of the project and using
them from Eclipse (with the IvyDE plug-in), Ant or other build system.
For examples of the two files, see e.g.
http://dev.vaadin.com/svn/integration/eclipse/plugins/com.vaadin.integration.eclipse/template/ivy/[here]
and update VAADIN_VERSION in the file ivy.xml.

Note that Vaadin 7 requires *Java version 6* or higher and *servlet
version 2.4* or higher (or portlet 2.0 or higher). If your project is
set up for older versions, update the corresponding facets.

[[converting-a-maven-project]]
Converting a Maven project
~~~~~~~~~~~~~~~~~~~~~~~~~~

Converting a *Maven* project is usually quite straightforward: replace
the Vaadin dependency with dependencies to the needed Vaadin artifacts,
remove any dependencies on GWT JARs, replace the GWT plug-in with the
Vaadin plug-in and recompile everything. The easiest way to get the
required sections and dependencies is to create a new project from the
vaadin-application-archetype and copy the relevant sections from it to
your project.

Note that Vaadin 7 requires Java version 6 or higher and servlet version
2.4 or higher (or portlet 2.0 or higher). If your project is set up for
older versions, update the corresponding dependencies and compiler
version.

[[content-for-windows-panels-and-more]]
Content for Windows, Panels and More
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In Vaadin 6, Window, Panel and some other components had a *default
layout* and addComponent() etc. As this often caused confusion and
caused layout problems when unaware of the implicit layout or forgetting
to set its layout parameters, Vaadin 7 now requires *explicitly setting
the content*. See See e.g.
link:CreatingABasicApplication.asciidoc[Creating
a basic application]

If you want to minimize the impact of this on the look and theme of an
old application, you can reproduce the *old structure* simply by setting
a `VerticalLayout` (with margins enabled) as the content and add your
components to it rather than the Panel/UI/Window.

Note that the class *Window* is now only used for sub-windows, not
browser level windows.

Information related to browser windows in now in *Page*, including
browser window size, URI fragment and page title. Setting the browser
location (redirecting to a URL) can also be performed via Page.

The API for *Notifications* has also changed, static methods
`Notification.show()` are now used instead of `Window.showNotification()`.

The current *UI*, *Page*, *VaadinService*, *VaadinRequest* and *VaadinResponse*
instances are easily accessible using *UI.getCurrent()*,
*Page.getCurrent()* etc. The session can be obtained using
*UI.getSession()* and the request and response are available from
*VaadinService.getCurrent()*. Thus, no more need for an explicit
*ThreadLocal* to keep track of them.

VaadinSession also provides the new entry point for *locking* access to
Vaadin components from *background threads*, replacing the old approach
of synchronizing to the Application instance - see the javadoc for
*VaadinSession.lock()* for more details.

To customize the creation of UIs - for instance to create different UIs
for mobile and desktop devices -
*link:CreatingAnApplicationWithDifferentFeaturesForDifferentClients.asciidoc[a
custom UIProvider]* can be used.

[[forms-and-data-binding]]
Forms and Data Binding
~~~~~~~~~~~~~~~~~~~~~~

What enterprise applications are all about is data, and the data entry
side in Vaadin 6 has been lacking in customizability. While it has been
possible to create arbitrary forms for data input, many situations have
required either bypassing the Form mechanism or using complicated tricks
to customize their layouts etc.

Although *Form* is still there in Vaadin 7 and a lot of old code for
data binding works mostly as is, version 7 brings something better:

* *FieldGroup* supporting *automated data binding*, whether for a hand-designed
form or
link:AutoGeneratingAFormBasedOnABeanVaadin6StyleForm.asciidoc[creating
the fields automatically]

* *link:CreatingATextFieldForIntegerOnlyInputUsingADataSource.asciidoc[typed
fields and properties]*

* *link:CreatingYourOwnConverterForString.asciidoc[converters]*,
both
link:ChangingTheDefaultConvertersForAnApplication.asciidoc[automatic
via ConverterFactory] and
link:CreatingATextFieldForIntegerOnlyInputWhenNotUsingADataSource.asciidoc[explicitly set]

* improved *validation* (performed on data model values after
conversion) - see e.g.
link:UsingBeanValidationToValidateInput.asciidoc[bean validation example]

* and more

If you want to keep using the old mechanisms, just note that e.g.
*TextField* now has the type String, and automatic conversions are applied
as well as *validation* performed on values converted to the *data model
type*. You can migrate data entry views form by form.

The ancient *QueryContainer* has been removed, so it is time to switch
to *SQLContainer* or some other container implementation.

If you are using a custom implementation of *Container.Indexed*, there
is one more method to implement - see the javadoc of *getItemIds(int,
int)* for details and a utility making implementing it easy.

*Property.toString()* should not be used to try to get the value of the
property, use *Property.getValue()* instead.

[[add-ons]]
Add-ons
~~~~~~~

If your project relies on add-ons from Vaadin Directory, note that not
all of them have been updated for Vaadin 7, and a few might only be
compatible with older Vaadin 7 beta versions. *Check the add-ons* you
use before committing to migration.

You may need to click "*Available for 7*" on the add-on page to get the
correct add-on version.

You can see a list of add-ons with a version available for Vaadin 7 using https://vaadin.com/directory/search[the search],
although some of them might only be compatible with older alpha and beta
versions of Vaadin 7 at the moment.

Note also that a handful of add-ons you might have used are now obsolete
as e.g. *CustomField* is integrated in Vaadin 7.

[[widgetset]]
Widgetset
~~~~~~~~~

As long as you use the *correct version of* the Eclipse or Maven
*plug-in* to compile your widgetset and remove any old GWT libraries
from your classpath, not much changes for widgetsets.

The current default widgetset is *com.vaadin.DefaultWidgetSet* and
should be inherited by custom widgetsets, although
*com.vaadin.terminal.gwt.DefaultWidgetset* still exists for backwards
compatibility. *DefaultWidgetSet* is also used on portals, replacing
*PortalDefaultWidgetSet*.

If you are compiling your widgetset e.g. with Ant, there are some
changes to the class to execute and its parameters. The class and
parameters to use are now "com.google.gwt.dev.Compiler -workDir (working
directory) -war (output directory) (widgetset module name)" with
optional additional optional parameters before the module name.

If you have optimized your widgetset to limit what components to load
initially, see
link:OptimizingTheWidgetSet.asciidoc[this
tutorial] and the
https://vaadin.com/directory/component/widget-set-optimizer[WidgetSet
Optimizer add-on].

[[themes]]
Themes
~~~~~~

The *HTML5 DOCTYPE* is used by Vaadin 7, which can affect the behavior
of some CSS rules.Vaadin 7 brings a new option to create your themes,
with SCSS syntax of *SASS* supporting *variables, nested blocks and
mix-ins* for easier reuse of definitions etc.

To get your old application running without bigger changes, just import
e.g. "../reindeer/*legacy-styles.css*" instead of
"../reindeer/styles.css" and take the application for a spin. There will
most likely be some changes to be done in your theme, but the main parts
should be there.

The themes also support *mixing components from multiple themes* and
using multiple applications with *different themes on the same page*,
which can be especially useful for portlets. However, these depend on
fully migrating your themes to the SCSS format with a theme name
selector.

To take advantage of the new features, see
link:CreatingAThemeUsingSass.asciidoc[Creating
a theme using sass] and
link:CustomizingComponentThemeWithSass.asciidoc[Customizing
component theme with Sass].

Note that the SCSS theme needs to be *compiled* to CSS before use - in
development mode, this takes place automatically on the fly whenever the
theme is loaded, but when moving to production mode, you need to run the
theme compiler on it to produce a pre-compiled static theme.

link:WidgetStylingUsingOnlyCSS.asciidoc[CSS
can be used to style components] somewhat more freely than in Vaadin 6.

The DOM structure of several layouts has changed, which might require
changes to themes for layouts. See also the section on layouts below.

[[navigation]]
Navigation
~~~~~~~~~~

In addition to low-level support for handling URI fragments Vaadin 7
also provides a higher level *navigation* framework, allowing you to
focus on the content of your views rather than the mechanics of how to
navigate to them.

The best way to get acquainted with the new navigation features is to
check the tutorials on
link:CreatingABookmarkableApplicationWithBackButtonSupport.asciidoc[creating
a bookmarkable application],
link:UsingParametersWithViews.asciidoc[using
parameters with views],
link:AccessControlForViews.asciidoc[access
control for views] and
link:ViewChangeConfirmations.asciidoc[view
change confirmations].

When logging out a user, you can use *Page.setLocation()* to redirect
the user to a suitable page.

[[extending-the-servlet]]
Extending the Servlet
~~~~~~~~~~~~~~~~~~~~~

As ApplicationServlet moved to history and is replaced by
*VaadinServlet*, many customizations you have made to it need a rewrite.

The most common customizations:

* link:CustomizingTheStartupPageInAnApplication.asciidoc[Customizing
the bootstrap page]: JavaScript, headers, ...
* Add-ons using customized servlets for other purposes (e.g. customizing
communication between client and server) probably need more extensive
rework

Note also that *TransactionListener*, *ServletRequestListener* and
*PortletRequestListener* have been removed.

Many things that used to be taken care of by *ApplicationServlet* are now
distributed among *VaadinServletService*, *VaadinSession*, *VaadinService*
etc. You can get a *VaadinSession* with *Component.getSession()* and
*VaadinService* e.g. with *VaadinSession.getService()*.

System messages that used to be configured by "overriding" a static
method *Application.getSystemMessages()* are now set in *VaadinService*
using a *SystemMessagesProvider*.

[[client-side-widgets]]
Client side widgets
~~~~~~~~~~~~~~~~~~~

For add-on authors and creators of custom widgets, the biggest changes
in Vaadin 7 have perhaps taken place on the client side and in
client-server communication.

The first big change is a separation of the client side UI *widgets* and
the code handling communication with the server (*Connector*). The
familiar VLabel is still the client side widget corresponding to the
server side component Label, but the communication part has been split
off into LabelConnector. The annotations linking the client side and the
server side have also changed, now the LabelConnector has an *@Connect*
annotation linking it to the server side component Label.
https://vaadin.com/book/vaadin7/-/page/architecture.client-side.html[the
book] provides some background and the tutorial on
link:CreatingASimpleComponent.asciidoc[creating
a simple component] shows an example.

The connector communicates with the server primarily via shared
state from the server to the client and **RPC
calls **link:SendingEventsFromTheClientToTheServerUsingRPC.asciidoc[from
client to server] and
link:UsingRPCToSendEventsToTheClient.asciidoc[from
server to client], with a larger set of supported data types. For
component containers,
link:CreatingASimpleComponentContainer.asciidoc[the
hierarchy of the contained components is sent separately].

The old mechanism with UIDL, *paintContent()* and *changeVariables()* is
still there for a while to ease migration, but it is recommended to
update your components to the new mechanisms, which also tend to result
in much cleaner code. Using the old mechanisms requires implementing
*LegacyComponent*.

There are also new features such as support for *Extensions* (components
which
link:CreatingAUIExtension.asciidoc[extend
the UI] or
link:CreatingAComponentExtension.asciidoc[other
components] without having a widget in a layout) and
link:UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc[support
for JavaScript], also for
link:IntegratingAJavaScriptComponent.asciidoc[implementing
components] and
link:IntegratingAJavaScriptLibraryAsAnExtension.asciidoc[extensions],
which might simplify the implementation of some components. Shared state
and RPC can also be used from JavaScript, and there are other techniques
for client-server communication.

*Package names* for the client side have changed but a simple import
reorganization by the IDE should be able to take care of that, the new
packages are under *com.vaadin.client.ui*.

If you have implemented a *component that contains other components*
(HasComponents, ComponentContainer) or have client side widgets which do
size calculations etc, see the layouts chapter - these should now be
much simpler to implement than previously, although much of custom
layout widgets will probably need to be rewritten.

A final note about client side development:
*https://vaadin.com/blog/vaadin-and-superdevmode[SuperDevMode]*
has been integrated to Vaadin 7, eliminating the need for browser
plug-ins in many cases when debugging client side code.

[[migration-steps-quick-and-dirty]]
Migration steps (quick and dirty)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Create a connector class for the add-on
* Extend *LegacyConnector*, override the *getWidget()* method, change its
signature to return *VMyWidget* and implement it as return *(VMyWidget)
super.getWidget();*
* Replace the *@ClientWidget(VMyWidget.class)* annotation (on the
server-side component) with *@Connect(MyServerSideComponent.class)* on the
connector class
* Remove the call to *super.updateFromUIDL(...)* in
*VMyWidget.updateFromUIDL(...)* if no such method exists in the
superclass.
* If the widget has implemented *setHeight* and *setWidth*, make the
connector implement *SimpleManagedLayout* and move the layout logic to the
*layout()* method.
* The actual sizes of the widget is available through
*getLayoutManager().getOuterHeight(getWidget().getElement())* and similar
for the width.
* If the widget implements *ContainerResizedListener*, make the connector
implement *SimpleManagedLayout* and call *getWidget().iLayout()* from the
*layout()* method.
* Be prepared for problems if you are doing layouting in *updateFromUIDL*
as the actual size of a relatively sized widget will most likely change
during the layout phase, i.e. after *updateFromUIDL*

The connector class should look like

[source,java]
....
@Connect(MyComponent.class)
public class MyConnector extends LegacyConnector {
  @Override
  public VMyWidget getWidget() {
    return (VMyWidget) super.getWidget();
  }
}
....

* Implement the interface *LegacyComponent* in the server side class
* If your widget has not delegated caption handling to the framework
(i.e. used *ApplicationConnection.updateComponent(..., ..., false)* you
should override *delegateCaptionHandling()* in your connector and return
false. Please note, however, that this is not recommended for most
widgets.

[[basic-widget-add-on-using-vaadin-7-apis]]
Basic widget add-on using Vaadin 7 APIs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Note: migration to new communication mechanisms etc. should be performed
step by step.These instructions continue from where the quick and dirty
migration ended.

* Intermediate step: move *updateFromUIDL(...)* implementation from the
widget to the connector
* Change the visibility of any methods and fields it accesses in the
widget to "package"
* Intermediate step: design an API for the widget that does not access
Vaadin communication mechanisms directly
* Use listeners for events from the widget to the server
* Use setters and action methods for server to client modifications
* Convert state variables and their transmission in
*paintContent()*/*updateFromUIDL()* to use shared state
* Convert one-time actions (events etc.) to use RPC
* Remove "implements LegacyComponent" from the server-side class and the
methods *paintContent()* and *changeVariables()*
* Remove "implements Paintable" or "extends LegacyConnector" and
*updateFromUIDL()* from the client-side connector class (extend
*AbstractComponentConnector* instead of *LegacyConnector*)

[[layouts-and-component-containers]]
Layouts and Component Containers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

While the server side API of various layouts has not changed much, the
implementations on the client side have. With the currently supported
browsers, much more can now be calculated by the browser, so Vaadin
layouts often do not need to measure and calculate sizes.

Most of the differences are only relevant to those who develop client
side component containers, but a few can also affect other developers.

Among the changes affecting others than layout developers, *CssLayout*
now consists of a single DIV instead of three nested elements, and
link:WidgetStylingUsingOnlyCSS.asciidoc[CSS
can be used to do more customization] than in previous Vaadin versions.
Also other layouts have changed in terms of their *DOM structure* on the
client, which might require changes to themes. The interface
*MarginHandler* is now only implemented by layouts that actually support
it, not in *AbstractLayout*, and *margins* should be set in CSS for
*CssLayout*.

When implementing components that are not full-blown layouts (with
*addComponent()*, *removeComponent()* etc.) but should contain other
components, the simpler interface *HasComponents* should be used instead
of *ComponentContainer*.

For those implementing new component containers or layouts, see the
related tutorials
link:CreatingASimpleComponentContainer.asciidoc[Creating
a simple component container] and
link:WidgetStylingUsingOnlyCSS.asciidoc[Widget
styling using only CSS].

[[migration-steps-for-componentcontainers]]
Migration steps for ComponentContainers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

These continue from where the add-on migration steps above left off

* Component containers (e.g. layouts) require more changes as the
underlying layout mechanisms and updates have changed
* Client-side child connectors are now created by the framework
* Hierarchy change events. Guaranteed to run before child calls
*updateCaption*. Create any child slots here and attach the widget.
* Don't paint children
* Don't call *child.updateFromUidl*
* Update caption management (called before *updateFromUidl*, from state
change event listener)

[[miscellaneous-changes]]
Miscellaneous Changes
~~~~~~~~~~~~~~~~~~~~~

Many overloaded *addListener()* methods have been deprecated. Use
*addClickListener()*, *addValueChangeListener()* etc. instead of them,
reducing ambiguity and the need for explicit casts.

Many *constants* have been replaced with enums, although in most cases
the old names refer to enum values to ease migration.

If using *background threads, locking* has changed: there is no longer
an *Application* class to synchronize to, but *getSession().lock()* etc.
should be used - see the javadoc for details on its correct use, using a
correct try-finally is crucial for building reliable multi-threaded
Vaadin applications.

*ApplicationResource* has been replaced with *ConnectorResource*, taking
different parameters.

*URIHandler* has been replaced with *RequestHandler*. See also the related
class *DownloadStream*.

*JavaScript* can now be executed using *JavaScript.execute()*.

Various methods that were *deprecated* until 6.8 etc. have been removed,
and some classes and methods have been deprecated. In most of those
cases, the deprecation comment or javadoc indicates what to use as a
replacement.

AbstractComponent.*isEnabled()* and *isVisible()* do not take the state
of the parent component into account, but only inquire the state set for
the component itself. A component inside a disabled component still is
disabled, and one inside an invisible component is not rendered on the
browser.

No information is sent to the browser about components marked as
*invisible* - they simply do not exist from the point of view of the
client.

[[components]]
Components
~~~~~~~~~~

*Button* is no longer a Field and does not have a constructor that takes
a method name to call, use anonymous inner class instead. Because of
this, *CheckBox* is no longer a Button and uses a *ValueChangeListener*
instead of a *ClickListener*.

*DateField* no longer supports milliseconds and its default resolution
is day.

*Label* now supports converters.

*RichTextArea* custom formatting methods removed, use a
*PropertyFormatter* or a *Converter* instead of overriding formatting
methods.

[[need-help]]
Need help?
----------

If you need any advice, training or hands on help in migrating your app
to Vaadin 7, please be in touch with sales@vaadin.com. Vaadin team would
be happy to be at your service.