Developing Vaadin apps with Python

To accomplish exactly what?

This article describes how to start developing Vaadin apps with Python programming language. Goal is that programmer could use Python instead of Java with smallest amount of boilerplate code necessary to get the environment working.

Luckily Python can make use of Java classes and vice versa. For detailed tutorial how to accomplish this in general please see http://www.jython.org/jythonbook/en/1.0/JythonAndJavaIntegration.html and http://wiki.python.org/jython/UserGuide.

Requirements

For setup used in this article you will need to install PyDev plugin to your Eclipse and Jython. See http://pydev.org/ and http://www.jython.org/ for more details.

Let’s get started

To get started create a new Vaadin project or open existing as you would normally do. As you have PyDev installed as Eclipse plugin you can start developing after few steps.

  • Add Python nature to your project by right clicking the project and selecting PyDev → Set as PyDev Project. After this the project properties has PyDev specific sections.

  • Go to PyDev - Interpreter/Grammar and select Jython as your Python interpreter.

  • Add a source folder where your Python source code will reside. Go to section PyDev - PYTHONPATH and add source folder. Also add vaadin-x.x.x.jar to PYTHONPATH in external libraries tab.

  • Add jython.jar to your project’s classpath and into deployment artifact.

  • Map your python source folder into WEB-INF/classes in deployment artifact. Go to Deployment Assembly → Add → Folder.

Modify web.xml and ApplicationServlet

First of all to build a basic Vaadin app you need to define your app in web.xml. You have something like this in your web.xml:

<servlet>
  <servlet-name>Vaadin Application</servlet-name>
  <servlet-class>com.vaadin.terminal.gwt.server.ApplicationServlet</servlet-class>
  <init-param>
    <description>Vaadin application class to start</description>
    <param-name>application</param-name>
    <param-value>com.vaadin.example.ExampleApplication</param-value>
  </init-param>
</servlet>

This will have to be modified a bit. Servlet init parameter application is a Java class name which will be instantiated for each user session. Default implementation of com.vaadin.terminal.gwt.server.ApplicationServlet can only instantiate Java classes so therefore you must override that class so that it is able to instantiate Python objects. Of course if you want the main Application object to be a Java class there is no need to modify the web.xml.

Here’s the modified section of web.xml. Implementation of PythonServlet is explained later. Init parameter application is now actually Python class.

<servlet>
  <servlet-name>Python Application</servlet-name>
  <servlet-class>com.vaadin.example.pythonapp.PythonServlet</servlet-class>
  <init-param>
    <description>Vaadin application class to start</description>
    <param-name>application</param-name>
    <param-value>python.vaadin.pythonapp.PyApplication</param-value>
  </init-param>
</servlet>

And here’s the PythonServlet. This is altered version of original Vaadin ApplicationServlet.

package com.vaadin.example.pythonapp;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;

import org.python.core.PyObject;
import org.python.util.PythonInterpreter;

import com.vaadin.Application;
import com.vaadin.terminal.gwt.server.AbstractApplicationServlet;

public class PythonServlet extends AbstractApplicationServlet {
  // Private fields
  private Class<? extends Application> applicationClass;

  /**
   * Called by the servlet container to indicate to a servlet that the servlet
   * is being placed into service.
   *
   * @param servletConfig
   *            the object containing the servlet's configuration and
   *            initialization parameters
   * @throws javax.servlet.ServletException
   *             if an exception has occurred that interferes with the
   *             servlet's normal operation.
   */
  @Override
  public void init(javax.servlet.ServletConfig servletConfig)
        throws javax.servlet.ServletException {
    super.init(servletConfig);

    final String applicationModuleName = servletConfig
        .getInitParameter("application");
    if (applicationModuleName == null) {
      throw new ServletException(
          "Application not specified in servlet parameters");
    }

    String[] appModuleSplitted = applicationModuleName.split("\\.");
    if(appModuleSplitted.length < 1) {
      throw new ServletException("Cannot parse class name");
    }

    final String applicationClassName = appModuleSplitted[appModuleSplitted.length-1];

    try {
      PythonInterpreter interpreter = new PythonInterpreter();
      interpreter.exec("from "+applicationModuleName+" import "+applicationClassName);
      PyObject pyObj = interpreter.get(applicationClassName).__call__();
      Application pyApp = (Application)pyObj.__tojava__(Application.class);
      applicationClass = pyApp.getClass();
    } catch (Exception e) {
      e.printStackTrace();
      throw new ServletException("Failed to load application class: "
          + applicationModuleName, e);
    }
  }

  @Override
  protected Application getNewApplication(HttpServletRequest request)
      throws ServletException {

    // Creates a new application instance
    try {
      final Application application = getApplicationClass().newInstance();

      return application;
    } catch (final IllegalAccessException e) {
      throw new ServletException("getNewApplication failed", e);
    } catch (final InstantiationException e) {
      throw new ServletException("getNewApplication failed", e);
    } catch (ClassNotFoundException e) {
      throw new ServletException("getNewApplication failed", e);
    }
  }

  @Override
  protected Class<? extends Application> getApplicationClass()
      throws ClassNotFoundException {
    return applicationClass;
  }
}

The most important part is the following. It uses Jython’s PythonInterpreter to instantiate and convert Python classes into Java classes. Then Class object is stored for later use of creating new instances of it on demand.

PythonInterpreter interpreter = new PythonInterpreter();
interpreter.exec("from "+applicationModuleName+" import "+applicationClassName);
PyObject pyObj = interpreter.get(applicationClassName).__call__();
Application pyApp = (Application)pyObj.__tojava__(Application.class);

Now the Python application for Vaadin is good to go. No more effort is needed to get it running. So next we see how the application itself can be written in Python.

Python style Application object

Creating an Application is pretty straightforward. You would write class that is identical to the Java counterpart except it’s syntax is Python. Basic hello world application would look like this

from com.vaadin import Application
from com.vaadin.ui import Label
from com.vaadin.ui import Window

class PyApplication(Application):
  def __init__(self):
    pass

  def init(self):
    mainWindow = Window("Vaadin with Python")
    label = Label("Vaadin with Python")
    mainWindow.addComponent(label)
    self.setMainWindow(mainWindow)

Event listeners

Python does not have anonymous classes like Java and Vaadin’s event listeners rely heavily on implementing listener interfaces which are very often done as anonymous classes. So therefore the closest equivalent of

Button button = new Button("java button");
button.addListener(new Button.ClickListener() {
   public void buttonClick(ClickEvent event) {
      //Do something for the click
   }
});

is

button = Button("python button")
class listener(Button.ClickListener):
   def buttonClick(self, event):
      #do something for the click
button.addListener(listener())

Jython supports for some extend AWT/Swing-style event listeners but however that mechanism is not compatible with Vaadin. Same problem applies to just about anything else event listening interface in Java libraries like Runnable or Callable. To reduce the resulted verbosity some decorator code can be introduced like here https://gist.github.com/sunng87/947926.

Creating custom components

Creating custom Vaadin components is pretty much as straightforward as the creation of Vaadin main application. Override the CustomComponent class in similar manner as would be done with Java.

from com.vaadin.ui import CustomComponent
from com.vaadin.ui import VerticalLayout
from com.vaadin.ui import Label
from com.vaadin.ui import Button
from com.vaadin.terminal import ThemeResource

class PyComponent(CustomComponent, Button.ClickListener):
  def __init__(self):
    mainLayout = VerticalLayout()
    button = Button("click me to toggle the icon")
    self.label = Label()
    button.addListener(self)
    mainLayout.addComponent(self.label)
    mainLayout.addComponent(button)
    self.super__setCompositionRoot(mainLayout)

  def buttonClick(self, event):
    if self.label.getIcon() == None:
      self.label.setIcon(ThemeResource("../runo/icons/16/lock.png"));
    else:
      self.label.setIcon(None)

Containers and PythonBeans

Although not Python style of doing things there are some occasions that require use of beans.

Let’s say that you would like to have a table which has it’s content retrieved from a set of beans. Content would be one row with two columns where cells would contain strings "first" and "second" respectively. You would write this code to create and fill the table.

table = Table()
container = BeanItemContainer(Bean().getClass())
bean = Bean()
bean.setFirst("first")
bean.setSecond("second")
container.addItem(bean)
table.setContainerDataSource(container)

and the Bean object would look like this

class Bean(JavaBean):
  def __init__(self):
    self.__first = None
    self.__second = None

  def getFirst(self):
    return self.__first

  def getSecond(self):
    return self.__second

  def setFirst(self, val):
    self.__first = val

  def setSecond(self, val):
    self.__second = val

and JavaBean

public interface JavaBean {
  String getFirst();
  void setFirst(String first);
  String getSecond();
  void setSecond(String second);
}

Note that in this example there is Java interface mixed into Python code. That is because Jython in it’s current (2.5.2) version does not fully implement reflection API for python objects. Result without would be a table that has no columns.

Implementing a Java interface adds necessary piece of information of accessor methods so that bean item container can handle it.

Filtering container

Let’s add filtering to previous example. Implement custom filter that allows only bean that 'first' property is set to 'first'

container.addContainerFilter(PyFilter())

class PyFilter(Container.Filter):
  def appliesToProperty(self, propertyId):
    return True

  def passesFilter(self, itemId, item):
    prop = item.getItemProperty("first")
    if prop.getValue() == "first":
      return True
    else:
      return False

Again pretty straightforward.

Debugging

Debugging works as you would debug any Jython app remotely in a servlet engine. See PyDev’s manual for remote debugging at http://pydev.org/manual_adv_remote_debugger.html.

Setting breakpoints directly via Eclipse IDE however does not work. Application is started as a Java application and the debugger therefore does not understand Python code.

Final thoughts

By using Jython it allows easy access from Python code to Java code which makes it really straightforward to develop Vaadin apps with Python.

Some corners are bit rough as they require mixing Java code or are not possible to implement with Python as easily or efficiently than with Java.

How this differs from Muntjac?

Muntjac project is a python translation of Vaadin and it’s goal is pretty much same as this article’s: To enable development of Vaadin apps with Python.

Muntjac’s approach was to take Vaadin’s Java source code and translate it to Python while keeping the API intact or at least similar as possible. While in this article the Vaadin itself is left as is.

Simple Python applications like shown above can be executed with Vaadin or Muntjac. Application code should be compatible with both with small package/namespace differences.

Muntjac requires no Jython but it also lacks the possibility to use Java classes directly.

The problems we encountered above with requiring the use of mixed Java code are currently present in Muntjac (v1.0.4) as well. For example the BeanItemContainer is missing from the Muntjac at the moment.