Using Vaadin In IBM Domino

Vaadin can be used as a UI technology in Domino. This page will contain the instruction how to setup the development environment and to get started with your first Vaadin app in Domino.

The steps for setting up XPages SDK are:

  1. Download the XPages SDK for Luna and above from OpenNTF

  2. In Eclipse, from the Help menu select Install New Software….

  3. Select Add…, then choose Archive… and navigate to the zip file downloaded.
    Add XPages repository

  4. You will need to deselect Group items by category. Two features will show. The first includes sources, so select the second and click Next.
    Select features

  5. Accept the terms and finish the dialog. You will be prompted to restart Eclipse to complete the install.

  6. Select Window > Preferences (on Mac the location is Eclipse > Preferences). In the XPages SDK category tick Automatically create JRE and point to your local Notes and Domino installs. Then click Apply.
    Select XPages SDK

  7. In the Java > Installed JREs category you should now have two additional options, “XPages Domino JRE” and “XPages Notes JRE”. Under Plug-in Development > Target Platform click Add…. Select the Domino Install Target template and complete.
    Configure target definition

  8. Apply this as the target platform.
    Apply target definition

If you do not have a Domino server installed, there is an alternative approach. However, to test your OSGi plugin, you will need to create a Feature project, add the Plugin to that feature, then create an Update Site Project, add the feature to the update site, build and export. Then you will need to import that into an Update Site database on your server. This is the same process for creating and testing any other OSGi plugin on the server, such as XPages Extension Library.

  1. Download the IBM Domino Update Site for Build Management from OpenNTF. This is basically a zip file that contains features and plugins required for Maven and Tycho development in Eclipse, but also has all the dependencies required for Eclipse.

  2. In Eclipse, go to Window > Preferences (on Mac the location is Eclipse > Preferences). Then go to Plug-in Development > Target Platform.

  3. Edit the existing target platform configuration and in the dialog, click Add…, then Directory, then Next. Browse to and select the folder where you extracted the Update Site.>
    Add content

  4. The current release of Domino, 9.0.1, only supports Java 1.6. The next release, probably called Domino 9.0.2 and expected to ship first half 2016, is expected to include Java 1.8. But in the meantime, it’s best to set the JRE accordingly. In the preferences, go to Java > Installed JREs category.

  5. Add…, Standard VM, then Next
    Add JRE

  6. Click Directory and browse to your IBM Notes install’s “jvm” library. Give it an appropriate name and click Finish. Alternatively, if you don’t have IBM Notes installed on the development environment, download Java SE 6 SDK from Oracle.
    Configure JRE

Setting up Vaadin

Eclipse has a set of Vaadin plugins that can easily be installed to set up your environment.

  1. Select *Help > Eclipse Marketplace….*

  2. Search for “Vaadin” amd install theVaadin Plugin for Eclipse
    Select Vaadin plugin

  3. The options to install will include the Vaadin Designer, so leave all selected, confirm and accept the license. You will be prompted to restart Eclipse to complete the install.

Hello World Example

Now the development environment is set up, it’s time to create a Hello World application. But this one will not just print “Hello World” to the browser, instead it will add in the other key aspect, integrating with Domino. Maven is a useful tool for loading dependencies automatically, but will require the IBM Domino Update Site for Build Management mentioned earlier. So at this point the approach will just create a simple non-Mavenized plugin.

  1. In Eclipse, select File > New > Plug-in Project and give it a name. As an OSGi plugin, tell it to run with the OSGi framework “Equinox”.

    1

  2. Until the next release of Domino is out, the execution environment needs to be changed to Java 1.6. Then finish – the Eclipse perspective used for development is not significant at this stage.

    2

  3. The MANIFEST.MF will be opened and some additional configuration is required. The plugin should be set as a singleton on the Overview tab.

    3

  4. On the Dependencies tab some plugins and packages need loading for OSGi and Domino, as below.

    4

  5. Back on the Overview tab, click the Extension Points link and confirm you want to display the Extension and Extension Point pages.

    5

  6. On the Extensions tab, click Add… and choose com.ibm.pvc.webcontainer.application.

    6

  7. Set the contextRoot to “/helloVaadin”.

    7

  8. Right-click on com.ibm.pvc.webcontainer.application and select New > contentLocation. Set it to “WebContent”. These two steps can be done by manually typing the relevant XML onto the plugin.xml tab and I would recommend you loop at what the resulting XML is.

    8

  9. Next download the Vaadin jar files that will be needed from the Vaadin website. The README.txt file outlines the steps required to add it to the project, but are repeated below.

  10. Right-click the project and select New > Folder and call it WebContent/WEB-INF/lib.

    9

  11. Copy all jars to WebContent/WEB-INF/lib. Copy all jars in the lib folder to WebContent/WEB-INF/lib.

  12. In the MANIFEST.MF, on the Runtime tab in the Classpath section, click Add… and add all the jar files added to WebContent/WEB-INF/lib. You must select the jars, not the folder. Then remember to move the “.” entry to the top of the list.

    10

  13. Right-click the WebContent/WEB-INF folder and select New > File. Call it web.xml.

  14. Paste in the code below:

  1. XML
  5. ```
  6. <?xml version="1.0" encoding="ISO-8859-1"?>
  7. <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  8. xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  9. xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
  10. http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
  11. <display-name>HelloVaadin</display-name>
  12.    <welcome-file-list>
  13.      <welcome-file>index.html</welcome-file>
  14.      <welcome-file>index.htm</welcome-file>
  15.      <welcome-file>index.jsp</welcome-file>
  16.      <welcome-file>default.html</welcome-file>
  17.      <welcome-file>default.htm</welcome-file>
  18.      <welcome-file>default.jsp</welcome-file>
  19.    </welcome-file-list>
  20.    <context-param>
  21.        <description>Vaadin production mode</description>
  22.        <param-name>productionMode</param-name>
  23.        <param-value>false</param-value>
  24.    </context-param>
  26.    <servlet>
  27.        <servlet-name>HelloVaadinServlet</servlet-name>
  28.        <servlet-class>com.vaadin.server.VaadinServlet</servlet-class>
  29.        <init-param>
  30.            <param-name>UI</param-name>
  31.            <param-value>com.paulwithers.hellovaadin.HelloVaadinUI</param-value>
  32.        </init-param>
  33.    </servlet>
  35.    <servlet-mapping>
  36.        <servlet-name>HelloVaadinServlet</servlet-name>
  37.        <url-pattern>/*</url-pattern>
  38.    </servlet-mapping>
  39. </web-app>
  40. ```
  42. This first block gives a list of default URL extensions accepted for mapping and tells the application to run in development mode. The &lt;servlet&gt; block gives the servlet name and points to a class we will create later which will initialise the NotesThread required for talking to Domino. The initParam points to a class we will create later that will be the entry point into the application.

  1. Right-click com.paulwithers.hellovaadin and select New > Vaadin Design. You will need an evaluation or full license for Vaadin Designer. To get the trial license, log into the vaadin.com website and go to https://vaadin.com/designer#license-modal.

  2. Call the design page “WelcomeDesign” and use the Vertical Layout template. Finish and confirm to switch to the Vaadin perspective.

  3. Drag and drop a new Label onto the page (components are displayed alphabetically). In the Properties view set the name to “label1”. Click the ellipsis button next to StyleName. Select “LABEL_H2” and click Add →, then OK. Change ComponentAlignment to “TOP_CENTER”. Save and close.

  4. Switch back to the Plug-in Development perspective. This is better suited to plugin development. Note the “WelcomeDesign.html” and “WelcomeDesign.java” files. Review WelcomeDesign.java.

  5. Right-click on com.paulwithers.hellovaadin and select New > Class. Call it WelcomeView and set the superclass as WelcomeDesign.

    12

  6. Add the following code to the class to extend the auto-generated class and to compute the value of label1.

  1. Java
  5. ```
  6. import com.ibm.domino.osgi.core.context.ContextInfo;
  8. public class WelcomeView extends WelcomeDesign {
  9.     private static final long serialVersionUID = 1L;
  11.     public WelcomeView() {
  12.         super();
  13.         try {
  14.             label1.setValue("Welcome " +
  15. ContextInfo.getUserSession().getEffectiveUserName());
  16.         } catch (final Exception e) {
  17.             // TODO: handle exception
  18.         }
  19.     }
  20. }
  21. ```

  1. You may get an error that the method Session.getEffectiveUserName() is not API. That can be fixed by amending the Java compiler settings, by changing the setting for forbidden reference to “Warning”.

    13

  2. Right-click on src/com.paulwithers.hellovaadin and select New > Class. Class it “HelloVaadinUI” and set the superclass as “com.vaadin.ui.UI”.

    14

  3. Add the following code to the class:

  1. Java
  5. ```
  6. import com.vaadin.server.VaadinRequest;
  7. import com.vaadin.ui.UI;
  9. public class HelloVaadinUI extends UI {
  10.     @Override
  11.     protected void init(VaadinRequest request) {
  12.         final WelcomeView welcome = new WelcomeView();
  13.         setContent(welcome);
  14.     }
  15. }
  16. ```
  18. This creates an instance of the WelcomeView class just created and loads it to the page.

  1. On the Build tab ensure META-INF, WebContent, plugin.xml, src are all ticked for Binary Build.

  2. On the Overview tab, launch the Organize Manifests Wizard and complete.

    15

  3. Select File > New > Feature Project. Call it com.paulwithers.helloVaadinFeature.

    16

  4. Click Next and initialize from the com.paulwithers.helloVaadin plugin.

  5. Select File > New > Update Site Project. Call it com.paulwithers.helloVaadinUpdate and click Finish. Click Add Feature… and select com.paulwithers.helloVaadinFeature. Click Build All.

  6. Right-click com.paulwithers.helloVaadinUpdate and click Export…. Choose General > File System. You only need to select the site.xml. Export to an appropriate location.

    17

  7. In an Update Site database on the relevant server, import the update site by pointing to the site.xml.

    18

    As with any OSGi plugin, you will need to issue “restart task http” command to the server for the plugin to be available.

  8. If you browse to the “helloVaadin” URL on the server (corresponding to the contextRoot in the plugin.xml), you should now see “Hello Anonymous” message.

    19

If you log in or prefix the contextRoot with the filepath of a database that does not allow anonymous access, you will see a welcome message for the current logged in user.

20