Thanks, we value your feedback!

4.9. Deploying an Application

Vaadin applications are deployed as Java web applications, which can contain a number of servlets, each of which can be a Vaadin application or some other servlet, and static resources such as HTML files. Such a web application is normally packaged as a WAR (Web application ARchive) file, which can be deployed to a Java application server (or a servlet container to be exact). A WAR file, which has the .war extension, is a subtype of JAR (Java ARchive), and like a regular JAR, is a ZIP-compressed file with a special content structure.

For a detailed tutorial on how web applications are packaged, please refer to any Java book that discusses Java Servlets.

In the Java Servlet parlance, a "web application" means a collection of Java servlets or portlets, JSP and static HTML pages, and various other resources that form an application. Such a Java web application is typically packaged as a WAR package for deployment. Server-side Vaadin UIs run as servlets within such a Java web application. There exists also other kinds of web applications. To avoid confusion with the general meaning of "web application", we often refer to Java web applications with the slight misnomer "WAR" in this book.

4.9.1. Creating Deployable WAR in Eclipse

To deploy an application to a web server, you need to create a WAR package. Here we give the instructions for Eclipse.

  1. Select FileExport and then WebWAR File. Or, right-click the project in the Project Explorer and select WebWAR File.

  2. Select the Web project to export. Enter Destination file name (.war).

  3. Make any other settings in the dialog, and click Finish.

4.9.2. Web Application Contents

The following files are required in a web application in order to run it.

Web Application Organization

WEB-INF/web.xml (optional with Servlet 3.0)

This is the web application descriptor that defines how the application is organized, that is, what servlets and such it has. You can refer to any Java book about the contents of this file. It is not needed if you define the Vaadin servlet with the @WebServlet annotation in Servlet API 3.0.

WEB-INF/lib/*.jar

These are the Vaadin libraries and their dependencies. They can be found in the installation package or as loaded by a dependency management system such as Maven or Ivy.

Your UI classes

You must include your UI classes either in a JAR file in WEB-INF/lib or as classes in WEB-INF/classes

Your own theme files (OPTIONAL)

If your application uses a special theme (look and feel), you must include it in VAADIN/themes/themename directory.

Widget sets (OPTIONAL)

If your application uses a project-specific widget set, it must be compiled in the VAADIN/widgetset/ directory.

4.9.3. Web Servlet Class

When using the Servlet 3.0 API, you normally declare the Vaadin servlet classes with the @WebServlet annotation. The Vaadin UI associated with the servlet and other Vaadin-specific parameters are declared with a separate @VaadinServletConfiguration annotation.

@WebServlet(value = "/*",
            asyncSupported = true)
@VaadinServletConfiguration(
        productionMode = false,
        ui = MyProjectUI.class)
public class MyProjectServlet extends VaadinServlet {
}

The Vaadin Plugin for Eclipse creates the servlet class as a static inner class of the UI class. Normally, you may want to have it as a separate regular class.

The value parameter is the URL pattern for mapping request URLs to the servlet, as described in Section 4.9.5, “Servlet Mapping with URL Patterns”. The ui parameter is the UI class. Production mode is disabled by default, which enabled on-the-fly theme compilation, debug window, and other such development features. See the subsequent sections for details on the different servlet and Vaadin configuration parameters.

You can also use a web.xml deployment descriptor in Servlet 3.0 projects.

4.9.4. Using a web.xml Deployment Descriptor

A deployment descriptor is an XML file with the name web.xml in the WEB-INF sub-directory of a web application. It is a standard component in Java EE describing how a web application should be deployed. The descriptor is not required with Servlet API 3.0, where you can also define servlets with the @WebServlet annotation as decribed earlier, as web fragments, or programmatically. You can use both a web.xml and WebServlet in the same application. Settings in the web.xml override the ones given in annotations.

The following example shows the basic contents of a deployment descriptor for a Servlet 2.4 application. You simply specify the UI class with the UI parameter for the com.vaadin.server.VaadinServlet. The servlet is then mapped to a URL path in a standard way for Java Servlets.

<?xml version="1.0" encoding="UTF-8"?>
<web-app
  id="WebApp_ID" version="2.4"
  xmlns="http://java.sun.com/xml/ns/j2ee" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
     http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

  <servlet>
    <servlet-name>myservlet</servlet-name>
    <servlet-class>
        com.vaadin.server.VaadinServlet
    </servlet-class>

    <init-param>
      <param-name>UI</param-name>
      <param-value>com.ex.myprj.MyUI</param-value>
    </init-param>

    <!-- If not using the default widget set-->
    <init-param>
      <param-name>widgetset</param-name>
      <param-value>com.ex.myprj.MyWidgetSet</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>myservlet</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

The descriptor defines a servlet with the name myservlet. The servlet class, com.vaadin.server.VaadinServlet, is provided by Vaadin framework and is normally the same for all Vaadin projects. For some purposes, you may need to use a custom servlet class that extends the VaadinServlet. The class name must include the full package path.

Servlet API Version

The descriptor example given above was for Servlet 2.4. For a later version, such as Servlet 3.0, you should use:

<web-app
id="WebApp_ID" version="3.0"
xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

Servlet 3.0 support is useful for at least server push.

Widget Set

If the UI uses add-on components or custom widgets, it needs a custom widget set, which can be specified with the widgetset parameter for the servlet. Alternatively, you can defined it with the @WidgetSet annotation for the UI class. The parameter is a class name with the same path but without the .gwt.xml extension as the widget set definition file. If the parameter is not given, the com.vaadin.DefaultWidgetSet is used, which contains all the widgets for the built-in Vaadin components.

Unless using the default widget set (which is included in the vaadin-client-compiled JAR), the widget set must be compiled, as described in Chapter 16, Using Vaadin Add-ons or Section 12.4, “Compiling a Client-Side Module”, and properly deployed with the application.

4.9.5. Servlet Mapping with URL Patterns

The servlet needs to be mapped to an URL path, which requests it is to handle.

With @WebServlet annotation for the servlet class:

@WebServlet(value = "/*", asyncSupported = true)

In a web.xml:

  <servlet-mapping>
    <servlet-name>myservlet</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

The URL pattern is defined in the above examples as /*. This matches any URL under the project context. We defined above the project context as myproject so the URL for the page of the UI will be http://localhost:8080/myproject/.

Mapping Sub-Paths

If an application has multiple UIs or servlets, they have to be given different paths in the URL, matched by a different URL pattern. Also, you may need to have statically served content under some path. Having an URL pattern /myui/* would match a URL such as http://localhost:8080/myproject/myui/. Notice that the slash and the asterisk must be included at the end of the pattern. In such case, you also need to map URLs with /VAADIN/* to a servlet (unless you are serving it statically as noted below).

With a @WebServlet annotation for a servlet class, you can define multiple mappings as a list enclosed in curly braces as follows:

@WebServlet(value = {"/myui/*", "/VAADIN/*"},
            asyncSupported = true)

In a web.xml:

    ...
    <servlet-mapping>
        <servlet-name>myservlet</servlet-name>
        <url-pattern>/myui/*</url-pattern>
    </servlet-mapping>

    <servlet-mapping>
        <servlet-name>myservlet</servlet-name>
        <url-pattern>/VAADIN/*</url-pattern>
    </servlet-mapping>

If you have multiple servlets, you should specify only one /VAADIN/* mapping. It does not matter which servlet you map the pattern to, as long as it is a Vaadin servlet.

You do not have to provide the above /VAADIN/* mapping if you serve both the widget sets and (custom and default) themes statically in the /VAADIN directory in the web application. The mapping simply allows serving them dynamically from the Vaadin JAR. Serving them statically is recommended for production environments as it is faster. If you serve the content from within the same web application, you may not have the root pattern /* for the Vaadin servlet, as then all the requests would be mapped to the servlet.

4.9.6. Other Servlet Configuration Parameters

The servlet class or deployment descriptor can have many parameters and options that control the execution of a servlet. You can find complete documentation of the basic servlet parameters in the appropriate Java Servlet Specification. @VaadinServletConfiguration accepts a number of special parameters, as described below.

In a web.xml, you can set most parameters either as a <context-param> for the entire web application, in which case they apply to all Vaadin servlets, or as an <init-param> for an individual servlet. If both are defined, servlet parameters override context parameters.

Production Mode

By default, Vaadin applications run in debug mode (or development mode), which should be used during development. This enables various debugging features. For production use, you should have the productionMode=true setting in the @VaadinServletConfiguration, or in web.xml:

<context-param>
<param-name>productionMode</param-name>
<param-value>true</param-value>
<description>Vaadin production mode</description>
</context-param>

The parameter and the debug and production modes are described in more detail in Section 10.3, “Debug Mode and Window”.

Custom UI Provider

Vaadin normally uses the DefaultUIProvider for creating UI class instances. If you need to use a custom UI provider, you can define its class with the UIProvider parameter. The provider is registered in the VaadinSession.

In a web.xml:

  <servlet>
    ...
    <init-param>
      <param-name>UIProvider</param-name>
      <param-value>com.ex.my.MyUIProvider</param-value>
    </init-param>

The parameter is logically associated with a particular servlet, but can be defined in the context as well.

UI Heartbeat

Vaadin follows UIs using a heartbeat, as explained in Section 4.8.5, “UI Expiration”. If the user closes the browser window of a Vaadin application or navigates to another page, the Client-Side Engine running in the page stops sending heartbeat to the server, and the server eventually cleans up the UI instance.

The interval of the heartbeat requests can be specified in seconds with the heartbeatInterval parameter either as a context parameter for the entire web application or an init parameter for the individual servlet. The default value is 300 seconds (5 minutes).

In a web.xml:

<context-param>
<param-name>heartbeatInterval</param-name>
<param-value>300</param-value>
</context-param>

Session Timeout After User Inactivity

In normal servlet operation, the session timeout defines the allowed time of inactivity after which the server should clean up the session. The inactivity is measured from the last server request. Different servlet containers use varying defaults for timeouts, such as 30 minutes for Apache Tomcat. You can set the timeout under <web-app> with:

In a web.xml:

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

The session timeout should be longer than the heartbeat interval or otherwise sessions are closed before the heartbeat can keep them alive. As the session expiration leaves the UIs in a state where they assume that the session still exists, this would cause an Out Of Sync error notification in the browser.

However, having a shorter heartbeat interval than the session timeout, which is the normal case, prevents the sessions from expiring. If the closeIdleSessions parameter for the servlet is enabled (disabled by default), Vaadin closes the UIs and the session after the time specified in the session-timeout parameter expires after the last non-heartbeat request.

In a web.xml:

  <servlet>
    ...
    <init-param>
      <param-name>closeIdleSessions</param-name>
      <param-value>true</param-value>
    </init-param>

Push Mode

You can enable server push, as described in Section 10.16, “Server Push”, for a UI either with a @Push annotation for the UI or in the descriptor. The push mode is defined with a pushmode parameter. The automatic mode pushes changes to the browser automatically after access() finishes. With manual mode, you need to do the push explicitly with push(). If you use a Servlet 3.0 compatible server, you also want to enable asynchronous processing with the async-supported parameter.

In a web.xml:

<servlet>
  ...
  <init-param>
    <param-name>pushmode</param-name>
    <param-value>automatic</param-value>
</init-param>
<async-supported>true</async-supported>

Cross-Site Request Forgery Prevention

Vaadin uses a protection mechanism to prevent malicious cross-site request forgery (XSRF or CSRF), also called one-click attacks or session riding, which is a security exploit for executing unauthorized commands in a web server. This protection is normally enabled. However, it prevents some forms of testing of Vaadin applications, such as with JMeter. In such cases, you can disable the protection by setting the disable-xsrf-protection parameter to true.

In a web.xml:

<context-param>
<param-name>disable-xsrf-protection</param-name>
<param-value>true</param-value>
</context-param>

4.9.7. Deployment Configuration

The Vaadin-specific parameters defined in the deployment configuration are available from the DeploymentConfiguration object managed by the VaadinSession.

DeploymentConfiguration conf =
        getSession().getConfiguration();

// Heartbeat interval in seconds
int heartbeatInterval = conf.getHeartbeatInterval();

Parameters defined in the Java Servlet definition, such as the session timeout, are available from the low-level HttpSession or PortletSession object, which are wrapped in a WrappedSession in Vaadin. You can access the low-level session wrapper with getSession() of the VaadinSession.

WrappedSession session = getSession().getSession();
int sessionTimeout = session.getMaxInactiveInterval();

You can also access other HttpSession and PortletSession session properties through the interface, such as set and read session attributes that are shared by all servlets belonging to a particular servlet or portlet session.

Preface
1. Introduction
1.1. Overview
1.2. Example Application Walkthrough
1.3. Support for the Eclipse IDE
1.4. Goals and Philosophy
1.5. Background
2. Getting Started with Vaadin
2.1. Overview
2.2. Setting up the Development Environment
2.2.1. Installing Java SDK
2.2.2. Installing Eclipse IDE
2.2.3. Installing Apache Tomcat
2.2.4. Firefox and Firebug
2.3. Overview of Vaadin Libraries
2.4. Installing Vaadin Plugin for Eclipse
2.4.1. Installing the IvyDE Plugin
2.4.2. Installing the Vaadin Plugin
2.4.3. Updating the Plugins
2.4.4. Updating the Vaadin Libraries
2.5. Creating and Running a Project with Eclipse
2.5.1. Creating the Project
2.5.2. Exploring the Project
2.5.3. Coding Tips for Eclipse
2.5.4. Setting Up and Starting the Web Server
2.5.5. Running and Debugging
2.6. Using Vaadin with Maven
2.6.1. Working from Command-Line
2.6.2. Compiling and Running the Application
2.6.3. Using Add-ons and Custom Widget Sets
2.7. Creating a Project with NetBeans IDE
2.7.1. Maven Project from a Vaadin Archetype
2.8. Creating a Project with IntelliJ IDEA
2.8.1. Configuring an Application Server
2.8.2. Creating a Vaadin Web Application Project
2.8.3. Creating a Maven Project
2.9. Vaadin Installation Package
2.9.1. Package Contents
2.9.2. Installing the Libraries
2.10. Using Vaadin with Scala
3. Architecture
3.1. Overview
3.2. Technological Background
3.2.1. HTML and JavaScript
3.2.2. Styling with CSS and Sass
3.2.3. AJAX
3.2.4. Google Web Toolkit
3.2.5. Java Servlets
3.3. Client-Side Engine
3.4. Events and Listeners
4. Writing a Server-Side Web Application
4.1. Overview
4.2. Building the UI
4.2.1. Application Architecture
4.2.2. Compositing Components
4.2.3. View Navigation
4.2.4. Accessing UI, Page, Session, and Service
4.3. Designing UIs Declaratively
4.3.1. Declarative Syntax
4.3.2. Component Elements
4.3.3. Component Attributes
4.3.4. Component Identifiers
4.3.5. Using Designs in Code
4.4. Handling Events with Listeners
4.4.1. Using Anonymous Classes
4.4.2. Handling Events in Java 8
4.4.3. Implementing a Listener in a Regular Class
4.4.4. Differentiating Between Event Sources
4.5. Images and Other Resources
4.5.1. Resource Interfaces and Classes
4.5.2. File Resources
4.5.3. Class Loader Resources
4.5.4. Theme Resources
4.5.5. Stream Resources
4.6. Handling Errors
4.6.1. Error Indicator and Message
4.6.2. Customizing System Messages
4.6.3. Handling Uncaught Exceptions
4.7. Notifications
4.7.1. Notification Type
4.7.2. Customizing Notifications
4.7.3. Styling with CSS
4.8. Application Lifecycle
4.8.1. Deployment
4.8.2. Vaadin Servlet, Portlet, and Service
4.8.3. User Session
4.8.4. Loading a UI
4.8.5. UI Expiration
4.8.6. Closing UIs Explicitly
4.8.7. Session Expiration
4.8.8. Closing a Session
4.9. Deploying an Application
4.9.1. Creating Deployable WAR in Eclipse
4.9.2. Web Application Contents
4.9.3. Web Servlet Class
4.9.4. Using a web.xml Deployment Descriptor
4.9.5. Servlet Mapping with URL Patterns
4.9.6. Other Servlet Configuration Parameters
4.9.7. Deployment Configuration
5. User Interface Components
5.1. Overview
5.2. Interfaces and Abstractions
5.2.1. Component Interface
5.2.2. AbstractComponent
5.3. Common Component Features
5.3.1. Caption
5.3.2. Description and Tooltips
5.3.3. Enabled
5.3.4. Icon
5.3.5. Locale
5.3.6. Read-Only
5.3.7. Style Name
5.3.8. Visible
5.3.9. Sizing Components
5.3.10. Managing Input Focus
5.4. Field Components
5.4.1. Field Interface
5.4.2. Data Binding and Conversions
5.4.3. Handling Field Value Changes
5.4.4. Field Buffering
5.4.5. Field Validation
5.5. Selection Components
5.5.1. Binding Selection Components to Data
5.5.2. Adding New Items
5.5.3. Item Captions
5.5.4. Getting and Setting Selection
5.5.5. Handling Selection Changes
5.5.6. Allowing Adding New Items
5.5.7. Multiple Selection
5.5.8. Item Icons
5.6. Component Extensions
5.7. Label
5.7.1. Text Width and Wrapping
5.7.2. Content Mode
5.7.3. Spacing with a Label
5.7.4. Data Binding
5.7.5. CSS Style Rules
5.8. Link
5.9. TextField
5.9.1. Data Binding
5.9.2. String Length
5.9.3. Handling Null Values
5.9.4. Text Change Events
5.9.5. CSS Style Rules
5.10. TextArea
5.11. PasswordField
5.12. RichTextArea
5.13. Date and Time Input with DateField
5.13.1. PopupDateField
5.13.2. InlineDateField
5.13.3. Date and Time Resolution
5.13.4. DateField Locale
5.14. Button
5.15. CheckBox
5.16. ComboBox
5.16.1. Filtered Selection
5.17. ListSelect
5.18. NativeSelect
5.19. OptionGroup
5.19.1. Disabling Items
5.20. TwinColSelect
5.21. Table
5.21.1. Selecting Items in a Table
5.21.2. Table Features
5.21.3. Editing the Values in a Table
5.21.4. Column Headers and Footers
5.21.5. Generated Table Columns
5.21.6. Formatting Table Columns
5.21.7. CSS Style Rules
5.22. Tree
5.23. Grid
5.23.1. Overview
5.23.2. Binding to Data
5.23.3. Handling Selection Changes
5.23.4. Configuring Columns
5.23.5. Generating and Hiding Columns
5.23.6. Column Renderers
5.23.7. Header and Footer
5.23.8. Filtering
5.23.9. Sorting
5.23.10. Editing
5.23.11. Programmatic Scrolling
5.23.12. Generating Row or Cell Styles
5.23.13. Styling with CSS
5.24. MenuBar
5.25. Upload
5.26. ProgressBar
5.27. Slider
5.28. Calendar
5.28.1. Date Range and View Mode
5.28.2. Calendar Events
5.28.3. Getting Events from a Container
5.28.4. Implementing an Event Provider
5.28.5. Styling a Calendar
5.28.6. Visible Hours and Days
5.28.7. Drag and Drop
5.28.8. Using the Context Menu
5.28.9. Localization and Formatting
5.28.10. Customizing the Calendar
5.28.11. Backward and Forward Navigation
5.28.12. Date Click Handling
5.28.13. Handling Week Clicks
5.28.14. Handling Event Clicks
5.28.15. Event Dragging
5.28.16. Handling Drag Selection
5.28.17. Resizing Events
5.29. Composition with CustomComponent
5.30. Composite Fields with CustomField
5.31. Embedded Resources
5.31.1. Embedded Image
5.31.2. Adobe Flash Graphics
5.31.3. BrowserFrame
5.31.4. Generic Embedded Objects
6. Managing Layout
6.1. Overview
6.2. UI, Window, and Panel Content
6.3. VerticalLayout and HorizontalLayout
6.3.1. Properties or Attributes
6.3.2. Spacing in Ordered Layouts
6.3.3. Sizing Contained Components
6.4. GridLayout
6.4.1. Sizing Grid Cells
6.5. FormLayout
6.6. Panel
6.6.1. Scrolling the Panel Content
6.7. Sub-Windows
6.7.1. Opening and Closing Sub-Windows
6.7.2. Window Positioning
6.7.3. Scrolling Sub-Window Content
6.7.4. Modal Sub-Windows
6.8. HorizontalSplitPanel and VerticalSplitPanel
6.9. TabSheet
6.9.1. Adding Tabs
6.9.2. Tab Objects
6.9.3. Tab Change Events
6.9.4. Enabling and Handling Closing Tabs
6.10. Accordion
6.11. AbsoluteLayout
6.12. CssLayout
6.12.1. CSS Injection
6.12.2. Browser Compatibility
6.13. Layout Formatting
6.13.1. Layout Size
6.13.2. Expanding Components
6.13.3. Layout Cell Alignment
6.13.4. Layout Cell Spacing
6.13.5. Layout Margins
6.14. Custom Layouts
7. Themes
7.1. Overview
7.2. Introduction to Cascading Style Sheets
7.2.1. Applying CSS to HTML
7.2.2. Basic CSS Rules
7.2.3. Matching by Element Class
7.2.4. Matching by Descendant Relationship
7.2.5. Importance of Cascading
7.2.6. Style Class Hierarchy of a Vaadin UI
7.2.7. Notes on Compatibility
7.3. Syntactically Awesome Stylesheets (Sass)
7.3.1. Sass Overview
7.3.2. Sass Basics with Vaadin
7.4. Compiling Sass Themes
7.4.1. Compiling On the Fly
7.4.2. Compiling in Eclipse
7.4.3. Compiling with Maven
7.4.4. Compiling in Command-line
7.4.5. Compiling with Ant
7.5. Creating and Using Themes
7.5.1. Sass Themes
7.5.2. Plain Old CSS Themes
7.5.3. Styling Standard Components
7.5.4. Built-in Themes
7.5.5. Add-on Themes
7.6. Creating a Theme in Eclipse
7.7. Valo Theme
7.7.1. Basic Use
7.7.2. Common Settings
7.7.3. Valo Mixins and Functions
7.7.4. Valo Fonts
7.7.5. Component Styles
7.7.6. Theme Optimization
7.8. Font Icons
7.8.1. Loading Icon Fonts
7.8.2. Basic Use
7.8.3. Using Font icons in HTML
7.8.4. Using Font Icons in Other Text
7.8.5. Custom Font Icons
7.9. Custom Fonts
7.9.1. Loading Fonts
7.9.2. Using Custom Fonts
7.10. Responsive Themes
8. Binding Components to Data
8.1. Overview
8.2. Properties
8.2.1. Property Viewers and Editors
8.2.2. ObjectProperty Implementation
8.2.3. Converting Between Property Type and Representation
8.2.4. Implementing the Property Interface
8.3. Holding properties in Items
8.3.1. The PropertysetItem Implementation
8.3.2. Wrapping a Bean in a BeanItem
8.4. Creating Forms by Binding Fields to Items
8.4.1. Simple Binding
8.4.2. Using a FieldFactory to Build and Bind Fields
8.4.3. Binding Member Fields
8.4.4. Buffering Forms
8.4.5. Binding Fields to a Bean
8.4.6. Bean Validation
8.5. Collecting Items in Containers
8.5.1. Basic Use of Containers
8.5.2. Container Subinterfaces
8.5.3. IndexedContainer
8.5.4. BeanContainer
8.5.5. BeanItemContainer
8.5.6. Iterating Over a Container
8.5.7. GeneratedPropertyContainer
8.5.8. Filterable Containers
9. Vaadin SQLContainer
9.1. Architecture
9.2. Getting Started with SQLContainer
9.2.1. Creating a connection pool
9.2.2. Creating the TableQuery Query Delegate
9.2.3. Creating the Container
9.3. Filtering and Sorting
9.3.1. Filtering
9.3.2. Sorting
9.4. Editing
9.4.1. Adding items
9.4.2. Fetching generated row keys
9.4.3. Version column requirement
9.4.4. Auto-commit mode
9.4.5. Modified state
9.5. Caching, Paging and Refreshing
9.5.1. Container Size
9.5.2. Page Length and Cache Size
9.5.3. Refreshing the Container
9.5.4. Cache Flush Notification Mechanism
9.6. Referencing Another SQLContainer
9.7. Making Freeform Queries
9.8. Non-Implemented Methods
9.9. Known Issues and Limitations
10. Advanced Web Application Topics
10.1. Handling Browser Windows
10.1.1. Opening Popup Windows
10.1.2. Closing Popup Windows
10.2. Embedding UIs in Web Pages
10.2.1. Embedding Inside a div Element
10.2.2. Embedding Inside an iframe Element
10.2.3. Cross-Site Embedding with the Vaadin XS Add-on
10.3. Debug Mode and Window
10.3.1. Enabling the Debug Mode
10.3.2. Opening the Debug Window
10.3.3. Debug Message Log
10.3.4. General Information
10.3.5. Inspecting Component Hierarchy
10.3.6. Communication Log
10.3.7. Debug Modes
10.4. Request Handlers
10.5. Shortcut Keys
10.5.1. Shortcut Keys for Default Buttons
10.5.2. Field Focus Shortcuts
10.5.3. Generic Shortcut Actions
10.5.4. Supported Key Codes and Modifier Keys
10.6. Printing
10.6.1. Printing the Browser Window
10.6.2. Opening a Print Window
10.6.3. Printing PDF
10.7. Google App Engine Integration
10.8. Common Security Issues
10.8.1. Sanitizing User Input to Prevent Cross-Site Scripting
10.9. Navigating in an Application
10.9.1. Setting Up for Navigation
10.9.2. Implementing a View
10.9.3. Handling URI Fragment Path
10.10. Advanced Application Architectures
10.10.1. Layered Architectures
10.10.2. Model-View-Presenter Pattern
10.11. Managing URI Fragments
10.11.1. Setting the URI Fragment
10.11.2. Reading the URI Fragment
10.11.3. Listening for URI Fragment Changes
10.11.4. Supporting Web Crawling
10.12. Drag and Drop
10.12.1. Handling Drops
10.12.2. Dropping Items On a Tree
10.12.3. Dropping Items On a Table
10.12.4. Accepting Drops
10.12.5. Dragging Components
10.12.6. Dropping on a Component
10.12.7. Dragging Files from Outside the Browser
10.13. Logging
10.14. JavaScript Interaction
10.14.1. Calling JavaScript
10.14.2. Handling JavaScript Function Callbacks
10.15. Accessing Session-Global Data
10.15.1. Passing References Around
10.15.2. Overriding attach()
10.15.3. ThreadLocal Pattern
10.16. Server Push
10.16.1. Installing the Push Support
10.16.2. Enabling Push for a UI
10.16.3. Accessing UI from Another Thread
10.16.4. Broadcasting to Other Users
10.17. Vaadin CDI Add-on
10.17.1. CDI Overview
10.17.2. Installing Vaadin CDI Add-on
10.17.3. Preparing Application for CDI
10.17.4. Injecting a UI with @CDIUI
10.17.5. Scopes
10.17.6. Deploying CDI UIs and Servlets
10.17.7. View Navigation
10.17.8. CDI Events
11. Portal Integration
11.1. Overview
11.2. Creating a Generic Portlet in Eclipse
11.2.1. Creating a Project with Vaadin Plugin
11.3. Developing Vaadin Portlets for Liferay
11.3.1. Defining Liferay Profile for Maven
11.3.2. Creating a Portlet Project with Maven
11.3.3. Creating a Portlet Project in Liferay IDE
11.3.4. Removing the Bundled Installation
11.3.5. Installing Vaadin Resources
11.4. Portlet UI
11.5. Deploying to a Portal
11.5.1. Portlet Deployment Descriptor
11.5.2. Liferay Portlet Descriptor
11.5.3. Liferay Display Descriptor
11.5.4. Liferay Plugin Package Properties
11.5.5. Using a Single Widget Set
11.5.6. Building the WAR Package
11.5.7. Deploying the WAR Package
11.6. Vaadin IPC for Liferay
11.6.1. Installing the Add-on
11.6.2. Basic Communication
11.6.3. Considerations
11.6.4. Communication Through Session Attributes
11.6.5. Serializing and Encoding Data
11.6.6. Communicating with Non-Vaadin Portlets
12. Client-Side Vaadin Development
12.1. Overview
12.2. Installing the Client-Side Development Environment
12.3. Client-Side Module Descriptor
12.3.1. Specifying a Stylesheet
12.3.2. Limiting Compilation Targets
12.4. Compiling a Client-Side Module
12.4.1. Vaadin Compiler Overview
12.4.2. Compiling in Eclipse
12.4.3. Compiling with Ant
12.4.4. Compiling with Maven
12.5. Creating a Custom Widget
12.5.1. A Basic Widget
12.5.2. Using the Widget
12.6. Debugging Client-Side Code
12.6.1. Launching Development Mode
12.6.2. Launching SuperDevMode
12.6.3. Debugging Java Code in Chrome
13. Client-Side Applications
13.1. Overview
13.2. Client-Side Module Entry-Point
13.2.1. Module Descriptor
13.3. Compiling and Running a Client-Side Application
13.4. Loading a Client-Side Application
14. Client-Side Widgets
14.1. Overview
14.2. GWT Widgets
14.3. Vaadin Widgets
14.4. Grid
14.4.1. Renderers
15. Integrating with the Server-Side
15.1. Overview
15.2. Starting It Simple With Eclipse
15.2.1. Creating a Widget
15.2.2. Compiling the Widget Set
15.3. Creating a Server-Side Component
15.3.1. Basic Server-Side Component
15.4. Integrating the Two Sides with a Connector
15.4.1. A Basic Connector
15.4.2. Communication with the Server-Side
15.5. Shared State
15.5.1. Accessing Shared State on Server-Side
15.5.2. Handing Shared State in a Connector
15.5.3. Handling Property State Changes with @OnStateChange
15.5.4. Delegating State Properties to Widget
15.5.5. Referring to Components in Shared State
15.5.6. Sharing Resources
15.6. RPC Calls Between Client- and Server-Side
15.6.1. RPC Calls to the Server-Side
15.7. Component and UI Extensions
15.7.1. Server-Side Extension API
15.7.2. Extension Connectors
15.8. Styling a Widget
15.8.1. Determining the CSS Class
15.8.2. Default Stylesheet
15.9. Component Containers
15.10. Advanced Client-Side Topics
15.10.1. Client-Side Processing Phases
15.11. Creating Add-ons
15.11.1. Exporting Add-on in Eclipse
15.11.2. Building Add-on with Ant
15.12. Migrating from Vaadin 6
15.12.1. Quick (and Dirty) Migration
15.13. Integrating JavaScript Components and Extensions
15.13.1. Example JavaScript Library
15.13.2. A Server-Side API for a JavaScript Component
15.13.3. Defining a JavaScript Connector
15.13.4. RPC from JavaScript to Server-Side
16. Using Vaadin Add-ons
16.1. Overview
16.2. Downloading Add-ons from Vaadin Directory
16.2.1. Compiling Widget Sets with an Ant Script
16.3. Installing Add-ons in Eclipse with Ivy
16.4. Using Add-ons in a Maven Project
16.4.1. Adding a Dependency
16.4.2. Compiling the Project Widget Set
16.4.3. Enabling Widget Set Compilation
16.5. Installing Commercial Vaadin Add-on Licence
16.5.1. Obtaining License Keys
16.5.2. Installing License Key in License File
16.5.3. Passing License Key as System Property
16.6. Troubleshooting
17. Vaadin Charts
17.1. Overview
17.2. Installing Vaadin Charts
17.2.1. Maven Dependency
17.2.2. Ivy Dependency
17.2.3. Installing License Key
17.3. Basic Use
17.3.1. Basic Chart Configuration
17.3.2. Plot Options
17.3.3. Chart Data Series
17.3.4. Axis Configuration
17.3.5. Displaying Multiple Series
17.3.6. Mixed Type Charts
17.3.7. 3D Charts
17.3.8. Chart Themes
17.4. Chart Types
17.4.1. Line and Spline Charts
17.4.2. Area Charts
17.4.3. Column and Bar Charts
17.4.4. Error Bars
17.4.5. Box Plot Charts
17.4.6. Scatter Charts
17.4.7. Bubble Charts
17.4.8. Pie Charts
17.4.9. Gauges
17.4.10. Solid Gauges
17.4.11. Area and Column Range Charts
17.4.12. Polar, Wind Rose, and Spiderweb Charts
17.4.13. Funnel and Pyramid Charts
17.4.14. Waterfall Charts
17.4.15. Heat Maps
17.5. Chart Configuration
17.5.1. Plot Options
17.5.2. Axes
17.5.3. Legend
17.5.4. Formatting Labels
17.6. Chart Data
17.6.1. List Series
17.6.2. Generic Data Series
17.6.3. Range Series
17.6.4. Container Data Series
17.7. Advanced Uses
17.7.1. Server-Side Rendering and Exporting
17.8. Timeline
17.8.1. Graph types
17.8.2. Interaction Elements
17.8.3. Event Markers
17.8.4. Efficiency
17.8.5. Data Source Requirements
17.8.6. Events and Listeners
17.8.7. Configurability
17.8.8. Localization
17.8.9. Timeline Tutorial
18. Vaadin JPAContainer
18.1. Overview
18.2. Installing
18.2.1. Downloading the Package
18.2.2. Installation Package Content
18.2.3. Downloading with Maven
18.2.4. Including Libraries in Your Project
18.2.5. Persistence Configuration
18.2.6. Troubleshooting
18.3. Defining a Domain Model
18.3.1. Persistence Metadata
18.4. Basic Use of JPAContainer
18.4.1. Creating JPAContainer with JPAContainerFactory
18.4.2. Creating and Accessing Entities
18.4.3. Nested Properties
18.4.4. Hierarchical Container
18.5. Entity Providers
18.5.1. Built-In Entity Providers
18.5.2. Using JNDI Entity Providers in JEE6 Environment
18.5.3. Entity Providers as Enterprise Beans
18.6. Filtering JPAContainer
18.7. Querying with the Criteria API
18.7.1. Filtering the Query
18.7.2. Compatibility
18.8. Automatic Form Generation
18.8.1. Configuring the Field Factory
18.8.2. Using the Field Factory
18.8.3. Master-Detail Editor
18.9. Using JPAContainer with Hibernate
18.9.1. Lazy loading
18.9.2. The EntityManager-Per-Request pattern
18.9.3. Joins in Hibernate vs EclipseLink
19. Mobile Applications with TouchKit
19.1. Overview
19.2. Considerations Regarding Mobile Browsing
19.2.1. Mobile Human Interface
19.2.2. Bandwidth and Performance
19.2.3. Mobile Features
19.2.4. Compatibility
19.3. Installing Vaadin TouchKit
19.3.1. Installing as Ivy Dependency
19.3.2. Defining the Maven Dependency
19.3.3. Installing the Zip Package
19.4. Importing the Parking Demo
19.5. Creating a New TouchKit Project
19.5.1. Using the Maven Archetype
19.5.2. Starting from a New Eclipse Project
19.6. Elements of a TouchKit Application
19.6.1. The Servlet Class
19.6.2. Defining Servlet and UI with web.xml Deployment Descriptor
19.6.3. TouchKit Settings
19.6.4. The UI
19.6.5. Mobile Widget Set
19.6.6. Mobile Theme
19.6.7. Using Font Icons
19.7. Mobile User Interface Components
19.7.1. NavigationView
19.7.2. Toolbar
19.7.3. NavigationManager
19.7.4. NavigationButton
19.7.5. Popover
19.7.6. SwipeView
19.7.7. Switch
19.7.8. VerticalComponentGroup
19.7.9. HorizontalButtonGroup
19.7.10. TabBarView
19.7.11. EmailField
19.7.12. NumberField
19.7.13. UrlField
19.8. Advanced Mobile Features
19.8.1. Providing a Fallback UI
19.8.2. Geolocation
19.8.3. Storing Data in the Local Storage
19.8.4. Uploading Content
19.9. Offline Mode
19.9.1. Enabling the Cache Manifest
19.9.2. Enabling Offline Mode
19.9.3. The Offline User Interface
19.9.4. Sending Data to Server
19.9.5. The Offline Theme
19.10. Building an Optimized Widget Set
19.10.1. Generating the Widget Map
19.10.2. Defining the Widget Loading Style
19.10.3. Applying the Custom Widget Map Generator
19.10.4. Deployment
19.11. Testing and Debugging on Mobile Devices
19.11.1. Debugging
20. Vaadin Spreadsheet
20.1. Overview
20.2. Installing Vaadin Spreadsheet
20.2.1. Installing as Ivy Dependency
20.2.2. Defining the Maven Dependency
20.2.3. Installing the Zip Package
20.2.4. Installing License Key
20.2.5. Compiling Widget Set
20.2.6. Compiling Theme
20.2.7. Importing the Demo
20.3. Basic Use
20.3.1. Creating a Spreadsheet
20.3.2. Working with Sheets
20.4. Spreadsheet Configuration
20.4.1. Spreadsheet Elements
20.4.2. Frozen Row and Column Panes
20.5. Cell Content and Formatting
20.5.1. Cell Formatting
20.5.2. Cell Font Style
20.5.3. Cell Comments
20.5.4. Merging Cells
20.5.5. Components in Cells
20.5.6. Hyperlinks
20.5.7. Popup Buttons in Cells
20.6. Context Menus
20.6.1. Default Context Menu
20.6.2. Custom Context Menus
20.7. Tables Within Spreadsheets
20.7.1. Creating a Table
20.7.2. Filtering With a Table
21. Vaadin TestBench
21.1. Overview
21.2. Quick Start
21.2.1. Installing License Key
21.2.2. Quick Start with Eclipse
21.2.3. Quick Start with Maven
21.3. Installing Vaadin TestBench
21.3.1. Test Development Setup
21.3.2. A Distributed Testing Environment
21.3.3. Installation Package Contents
21.3.4. TestBench Demo
21.3.5. Installing Browser Drivers
21.3.6. Test Node Configuration
21.4. Developing JUnit Tests
21.4.1. Basic Test Case Structure
21.4.2. Running JUnit Tests in Eclipse
21.5. Creating a Test Case
21.5.1. Test Setup
21.5.2. Basic Test Case Structure
21.5.3. Creating and Closing a Web Driver
21.6. Querying Elements
21.6.1. Generating Queries with Debug Window
21.6.2. Querying Elements by Component Type ($)
21.6.3. Non-Recursive Component Queries ($$)
21.6.4. Element Classes
21.6.5. ElementQuery Objects
21.6.6. Query Terminators
21.7. Element Selectors
21.7.1. Finding by ID
21.7.2. Finding by CSS Class
21.8. Special Testing Topics
21.8.1. Waiting for Vaadin
21.8.2. Testing Tooltips
21.8.3. Scrolling
21.8.4. Testing Notifications
21.8.5. Testing Context Menus
21.8.6. Profiling Test Execution Time
21.9. Creating Maintainable Tests
21.9.1. Increasing Selector Robustness
21.9.2. The Page Object Pattern
21.10. Taking and Comparing Screenshots
21.10.1. Screenshot Parameters
21.10.2. Taking Screenshots on Failure
21.10.3. Taking Screenshots for Comparison
21.10.4. Practices for Handling Screenshots
21.10.5. Known Compatibility Problems
21.11. Running Tests
21.11.1. Running Tests with Ant
21.11.2. Running Tests with Maven
21.12. Running Tests in a Distributed Environment
21.12.1. Running Tests Remotely
21.12.2. Starting the Hub
21.12.3. Node Service Configuration
21.12.4. Starting a Grid Node
21.12.5. Mobile Testing
21.13. Parallel Execution of Tests
21.13.1. Local Parallel Execution
21.13.2. Multi-Browser Execution in a Grid
21.14. Headless Testing
21.14.1. Basic Setup for Running Headless Tests
21.14.2. Running Headless Tests in a Distributed Environment
21.15. Behaviour-Driven Development
21.16. Known Issues
21.16.1. Running Firefox Tests on Mac OS X
Index