HowTo: Vaadin on Domino

This example requires a valid XPages Plugin Development Environment. The execution environment used is the XPages Domino JRE.

1. Create a new plug-in project and select „Equinox“ as OSGi framework

2. Set the name of the activator class to „ch.hasselba.vaadin.Activator“

3. Open the MANIFEST.MF file

4. On Tab „Overview„, activate the option for lazy loading and the singleton property

5. Go to „Dependencies“ tab and add the required plugin „com.ibm.pvc.webcontainer“

When entering „pvc„, you can easily find the plugin from the list:

6. Then, add  „javax.servlet“ and „javax.servlet.http“ to the list of imported packages

7. Now, download the Jar files for Vaadin. The files can be found here (the All-in-One archive is the right one).

8. Import the Jars to the project

The required Jars are:

• vaadin-client-7.3.8.jar
• vaadin-client-compiled-7.3.8.jar
• vaadin-client-compiler-7.3.8.jar
• vaadin-push-7.3.8.jar
• vaadin-server-7.3.8.jar
• vaadin-shared-7.3.8.jar
• vaadin-themes-7.3.8.jar

9. Do this with „jsoup“ and „org.json“ libaries too:

10. Now, go to the „Runtime“ tab and add the classpathes (don’t forget to move the „.“ to the top of the list)

The symbol of the filetypes have now changed:

11. On tab „Overview„, click on „Extensions“ to open the Extension tab

Click on „Yes“ to open the „Extension“ tab:

12. Here, you have to add the extension point „com.ibm.pvc.webcontainer.application“

13. Open „plugin.xml“…

14. … and configure the extension point:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>

     <extension
         point="com.ibm.pvc.webcontainer.application">
      <contextRoot>
         /helloVaadin  
      </contextRoot>
      <contentLocation>
         WebContent
      </contentLocation>
   </extension>

</plugin>

contextRoot defines the URL pattern where the Vaadin servlet is reachable.  contentLocation is a folder where the required web.xml configuration file can be found.

Save the „plugin.xml“ file.

15. Create the folder „WebContent„…

16. … and then a second folder „WEB-INF“ inside of „WebContent“

17. Create the „web.xml“ file in this folder, the tree should look like this:

18. The „web.xml“ contains the configuration of the servlet:

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" 
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_2_5.xsd">

  <display-name>HelloVaadin</display-name>
    <context-param>
        <description>Vaadin production mode</description>
        <param-name>productionMode</param-name>
        <param-value>false</param-value>
    </context-param>
    
    <servlet>
        <servlet-name>HelloVaadinServlet</servlet-name>
        <servlet-class>com.vaadin.server.VaadinServlet</servlet-class>
        <init-param>
            <param-name>UI</param-name>
            <param-value>ch.hasselba.vaadin.HelloVaadinUI</param-value>
        </init-param>
    </servlet> 

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

The <init-param> tag inside <servlet> defines our UI class of our application. We will create this class later. The <servlet-mapping> defines a mapping inside the webapplication path.

This means, if you would add a url-pattern like „/helloVaadinServlet/*“ to the Vaadin servlet, the URL to reach the application is

http://example.com/helloVaadin/helloVaadinServlet/

The „/helloVaadin/“ part is the defined in the contextPath parameter in the web application. When using another pattern as „/*„, an additional mapping for the Vaadin resources is required:

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

19. Go to „Build“ tab, and include the „Web-Content“ folder:

The following line should now appear in the build.properties file which includes the folder in the final Jar.

20. Create the Vaadin servlet class „ch.hasselba.vaadin.HelloVaadinUI“

21. Add the following code to the class

package ch.hasselba.vaadin;

import com.vaadin.server.VaadinRequest;
import com.vaadin.server.VaadinServlet;
import com.vaadin.shared.ui.label.ContentMode;
import com.vaadin.ui.Alignment;
import com.vaadin.ui.HorizontalLayout;
import com.vaadin.ui.Label;
import com.vaadin.ui.UI; 

@SuppressWarnings("serial")
public class HelloVaadinUI extends UI {
    
    public static class Servlet extends VaadinServlet {
    }
    
    @Override
    protected void init(VaadinRequest request) {
    
        HorizontalLayout layout = new HorizontalLayout();
        setContent(layout);
        layout.setSizeFull();

        Label label = new Label();
        label.setValue("<h1>Hello Vaadin!</h1>");
        label.setContentMode(ContentMode.HTML);
        layout.addComponent(label);
        layout.setComponentAlignment(label, Alignment.TOP_CENTER);
    }

}

22. At the end, organize the manifest. Open tab „Overview“ and start the „Organize Manifest Wizard“

This updates the manifest and adds all resources for the Vaadin application.

Last but not least, save all project files.

25. Create a Feature Project named „HelloVaadinFeature“ and click on „Next“

27. Select the „HelloVaadin“ Plug-In

28. On the „Plugins“ tab, check the option „Unpack the plug-in archive after the installation„:

Save the file and…

29. … create the Update Site „HelloVaadinUpdateSite“

Add the feature…

… and build the site:

30. Import it to the Update Site on the Domino server and restart the HTTP task

31. That’s it! Open the URL in the browser and enjoy.